Configurazione di OSGi per AEM as a Cloud Service

OSGiè un elemento fondamentale nello stack tecnologico di Adobe Experience Manager (AEM). Viene utilizzato per controllare i bundle compositi di AEM e le sue configurazioni.

OSGi fornisce le primitive standardizzate che consentono di creare applicazioni da componenti di piccole dimensioni, riutilizzabili e collaborativi. Questi componenti possono essere composti in un’applicazione e distribuiti. Questo consente di gestire facilmente i bundle OSGi quando possono essere arrestati, installati e avviati individualmente. Le interdipendenze vengono gestite automaticamente. Ciascun componente OSGi è contenuto in uno dei vari bundle. Per ulteriori informazioni, vedere la specifica OSGi.

Potete gestire le impostazioni di configurazione per i componenti OSGi tramite file di configurazione che fanno parte di un progetto di codice AEM.

File di configurazione OSGi

Le modifiche alla configurazione sono definite nei pacchetti di codice del progetto AEM (ui.apps) come file di configurazione (.cfg.json) nelle cartelle di configurazione specifiche della modalità di esecuzione:

/apps/example/config.<runmode>

Il formato dei file di configurazione OSGi è basato su JSON utilizzando il formato .cfg.json definito dal progetto Apache Sling.

Le configurazioni OSGi sono destinate ai componenti OSGi tramite il relativo PID (Persistent Idenity), che per impostazione predefinita corrisponde al nome della classe Java del componente OSGi. Ad esempio, per fornire la configurazione OSGi per un servizio OSGi implementato da:

com.example.workflow.impl.ApprovalWorkflow.java

un file di configurazione OSGi è definito in:

/apps/example/config/com.example.workflow.impl.ApprovalWorkflow.cfg.json

seguendo il formato di configurazione cfg.json OSGi.

Risoluzione del modo di esecuzione

Configurazioni OSGi specifiche possono essere indirizzate a istanze AEM specifiche utilizzando le modalità di esecuzione. Per utilizzare la modalità di esecuzione, create le cartelle di configurazione in /apps/example (dove esempio è il nome del progetto), nel formato:

/apps/example/config.<author|publish>.<dev|stage|prod>/

Eventuali configurazioni OSGi in tali cartelle saranno utilizzate se le modalità di esecuzione definite nel nome della cartella di configurazione corrispondono alle modalità di esecuzione utilizzate da AEM.

Ad esempio, se AEM utilizza le modalità di esecuzione author e dev, i nodi di configurazione in /apps/example/config.author/ e /apps/example/config.author.dev/ saranno applicati, mentre i nodi di configurazione in /apps/example/config.publish/ e /apps/example/config.author.stage/ non saranno applicati.

Se si applicano più configurazioni per lo stesso PID, viene applicata la configurazione con il numero più elevato di modalità di esecuzione corrispondenti.

La granularità di questa regola è a livello PID. Ciò significa che non è possibile definire alcune proprietà per lo stesso PID in /apps/example/config.author/ e più specifiche in /apps/example/config.author.dev/ per lo stesso PID. La configurazione con il maggior numero di modalità di esecuzione corrispondenti sarà efficace per l'intero PID.

Quando si sviluppa localmente, è possibile passare un parametro di avvio in modalità di esecuzione per stabilire quale configurazione OSGI in modalità di esecuzione verrà utilizzata.

Tipi di valori di configurazione OSGi

Esistono tre varietà di valori di configurazione OSGi che possono essere utilizzati con AEM come Cloud Service.

1. Valori in linea, ossia valori hardcoded nella configurazione OSGi e memorizzati in Git. Esempio:

   {
      "connection.timeout": 1000
   }
   

2. Valori segreti, che sono valori che non devono essere memorizzati in Git per motivi di sicurezza. Esempio:

   {
   "api-key": "$[secret:server-api-key]"
   } 
   

3. I valori specifici dell'ambiente, che sono valori che variano da un ambiente di sviluppo all'altro, e quindi non possono essere mirati in modo accurato dalla modalità di esecuzione (poiché esiste un'unica modalità di dev esecuzione in AEM come Cloud Service). Esempio:

   {
    "url": "$[env:server-url]"
   }
   

   Tenere presente che un singolo file di configurazione OSGi può utilizzare insieme qualsiasi combinazione di questi tipi di valori di configurazione. Esempio:

   {
   "connection.timeout": 1000,
   "api-key": "$[secret:server-api-key]",
   "url": "$[env:server-url]"
   }
   

Come scegliere il tipo di valore di configurazione OSGi appropriato

Il caso comune per OSGi utilizza valori di configurazione OSGi in linea. Le configurazioni specifiche per l'ambiente sono utilizzate solo per casi d'uso specifici in cui un valore varia in base agli ambienti di sviluppo.

Le configurazioni specifiche per l’ambiente estendono le configurazioni OSGi tradizionali e statiche che contengono valori in linea, consentendo di gestire i valori di configurazione OSGi esternamente tramite l’API di Cloud Manager. È importante capire quando utilizzare l'approccio comune e tradizionale di definire i valori in linea e memorizzarli in Git, anziché astrarre i valori in configurazioni specifiche per l'ambiente.

Le seguenti linee guida riguardano i casi in cui utilizzare configurazioni non segrete e specifiche dell'ambiente segreto:

Quando utilizzare i valori di configurazione in linea

I valori delle configurazioni in linea sono considerati l'approccio standard e devono essere utilizzati quando possibile. Le configurazioni in linea offrono i seguenti vantaggi:

• Sono mantenuti, con governance e storia della versione in Git
• I valori sono implicitamente legati alle distribuzioni del codice
• Non richiedono ulteriori considerazioni di implementazione o di coordinamento

Quando definite un valore di configurazione OSGi, iniziate con i valori in linea, tutte le configurazioni specifiche per il segreto o l'ambiente selezionate solo se necessarie per il caso d'uso.

Quando utilizzare valori di configurazione non segreti per l'ambiente

Utilizzare configurazioni specifiche dell'ambiente ($[env:ENV_VAR_NAME]) solo per i valori di configurazione non segreti quando i valori variano in base agli ambienti di sviluppo. Ciò include le istanze di sviluppo locale e qualsiasi AEM come ambienti di sviluppo Cloud Service. Evitare di utilizzare configurazioni non segrete specifiche per l'ambiente per AEM come ambienti di fase o produzione Cloud Service.

• Utilizzate solo configurazioni non segrete specifiche per l'ambiente per i valori di configurazione che differiscono tra gli ambienti di sviluppo, incluse le istanze di sviluppo locale.
• Utilizzate invece i valori inline standard nelle configurazioni OSGi per i valori non segreti di Stage e Produzione. A tale proposito, non è consigliabile utilizzare configurazioni specifiche per l'ambiente per facilitare l'esecuzione delle modifiche di configurazione in fase di esecuzione agli ambienti di fase e produzione; queste modifiche dovrebbero essere introdotte tramite la gestione del codice sorgente.

Quando utilizzare i valori di configurazione specifici dell'ambiente segreto

AEM come Cloud Service richiede l'uso di configurazioni specifiche dell'ambiente ($[secret:SECRET_VAR_NAME]) per qualsiasi valore di configurazione OSGi segreto, come password, chiavi API private o qualsiasi altro valore che non può essere memorizzato in Git per motivi di sicurezza.

Utilizzate configurazioni specifiche per l'ambiente segreto per memorizzare il valore per i segreti su tutte le AEM come ambienti di Cloud Service, inclusi Stage e Produzione.

Creazione di configurazioni OSGi

Esistono due modi per creare nuove configurazioni OSGi, come descritto di seguito. Il primo approccio è in genere utilizzato per configurare componenti OSGi personalizzati con proprietà e valori OSGi ben noti dallo sviluppatore, e il secondo per i componenti OSGi AEM forniti.

Scrittura di configurazioni OSGi

I file di configurazione OSGi formattati JSON possono essere scritti manualmente direttamente nel progetto AEM. Questo è spesso il modo più veloce per creare configurazioni OSGi per componenti OSGi noti, e in particolare componenti OSGi personalizzati che sono stati progettati e sviluppati dallo stesso sviluppatore che definisce le configurazioni. Questo approccio può essere utilizzato anche per copiare/incollare e aggiornare le configurazioni per lo stesso componente OSGi in diverse cartelle in modalità di esecuzione.

1. Nell'IDE, aprire il progetto ui.apps, individuare o creare la cartella di configurazione (/apps/.../config.<runmode>) che esegue le modalità di esecuzione a cui deve essere applicata la nuova configurazione OSGi
2. In questa cartella di configurazione, create un nuovo file <PID>.cfg.json. Il PID è l’Identità persistente del componente OSGi, in genere è il nome completo della classe dell’implementazione del componente OSGi. Esempio:
   /apps/.../config/com.example.workflow.impl.ApprovalWorkflow.cfg.json
   Tenete presente che i nomi dei file factory di configurazione OSGi utilizzano la convenzione di <PID>-<factory-name>.cfg.json denominazione
3. Aprite il nuovo file .cfg.json e definite le combinazioni chiave/valore per le coppie di proprietà e valori OSGi, seguendo il formato di configurazione JSON OSGi.
4. Salva le modifiche nel nuovo file .cfg.json
5. Aggiungete e inviate il nuovo file di configurazione OSGi a Git

Generazione di configurazioni OSGi tramite l’SDK AEM Quickstart

La console AEM Web AEM SDK Quickstart Jar può essere utilizzata per configurare componenti OSGi ed esportare configurazioni OSGi come JSON. Questo è utile per configurare componenti OSGi forniti AEM le cui proprietà OSGi e i relativi formati di valore potrebbero non essere ben compresi dallo sviluppatore che definisce le configurazioni OSGi nel progetto AEM. Tenere presente che utilizzando l'interfaccia utente Configurazione della console Web AEM scrivere file .cfg.json nell'archivio, per evitare possibili comportamenti imprevisti durante lo sviluppo locale, quando le configurazioni OSGi AEM definite dal progetto possono essere diverse dalle configurazioni generate.

1. Accedi alla console Web AEM Jar dell'SDK AEM come utente amministratore
2. Passa a OSGi > Configurazione
3. Individuate il componente OSGi da configurare e toccate il titolo per modificarlo
   
4. Modificare i valori delle proprietà di configurazione OSGi tramite l'interfaccia utente Web in base alle esigenze
5. Registra l’identità persistente (PID) in un luogo sicuro, verrà utilizzato in seguito per generare il JSON di configurazione OSGi
6. Tocca Salva
7. Passare a OSGi > Stampante di configurazione OSGi Installer
8. Incolla nel PID copiato al passaggio 5, verifica che il formato di serializzazione sia impostato su "OSGi Configurator JSON"
9. Toccate Stampa,
10. La configurazione OSGi in formato JSON verrà visualizzata nella sezione Proprietà di configurazione serializzate
    
11. Nell'IDE, aprire il progetto ui.apps, individuare o creare la cartella di configurazione (/apps/.../config.<runmode>) che esegue le modalità di esecuzione a cui deve essere applicata la nuova configurazione OSGi.
12. In questa cartella di configurazione, create un nuovo file <PID>.cfg.json. Il PID è lo stesso valore del Passaggio 5.
13. Incollate le proprietà di configurazione serializzata dal passaggio 10 al file .cfg.json.
14. Salva le modifiche nel nuovo file .cfg.json.
15. Aggiungete e inviate il nuovo file di configurazione OSGi a Git.

Formati delle proprietà di configurazione OSGi

Valori in linea

Come ci si può aspettare, i valori in linea sono formattati come coppie nome-valore standard, seguendo la sintassi JSON standard. Esempio:

{
   "my_var1": "val",
   "my_var2": [ "abc", "def" ],
   "my_var3": 500
}

Valori di configurazione specifici per l'ambiente

Nella configurazione OSGi deve essere assegnato un segnaposto per la variabile che deve essere definita per ambiente:

use $[env:ENV_VAR_NAME]

I clienti devono utilizzare questa tecnica solo per le proprietà di configurazione OSGI relative al loro codice personalizzato; non deve essere utilizzato per ignorare configurazione OSGI definita dal Adobe.

Valori di configurazione segreti

Nella configurazione OSGi deve essere assegnato un segnaposto per il segreto che deve essere definito in base all’ambiente:

use $[secret:SECRET_VAR_NAME]

Denominazione variabile

Quanto segue si applica sia ai valori di configurazione specifici dell'ambiente che ai valori segreti.

I nomi delle variabili devono seguire le regole seguenti:

• lunghezza minima: 2
• lunghezza massima: 100
• deve corrispondere a regex: [a-zA-Z_][a-zA-Z_0-9]*

I valori per le variabili non devono superare i 2048 caratteri.

Valori predefiniti

Quanto segue si applica sia ai valori di configurazione specifici dell'ambiente che ai valori segreti.

Se non viene impostato alcun valore per ambiente, in fase di esecuzione il segnaposto non verrà sostituito e lasciato in posizione poiché non è stata eseguita l'interpolazione. Per evitare questo problema, è possibile fornire un valore predefinito all'interno del segnaposto con la sintassi seguente:

$[env:ENV_VAR_NAME;default=<value>]

Se viene fornito un valore predefinito, il segnaposto verrà sostituito con il valore per ambiente specificato oppure con il valore predefinito fornito.

Sviluppo locale

Quanto segue si applica sia ai valori di configurazione specifici dell'ambiente che ai valori segreti.

Le variabili possono essere definite nell'ambiente locale in modo che vengano rilevate dal AEM locale in fase di esecuzione. Ad esempio, in Linux:

export ENV_VAR_NAME=my_value

Si consiglia di scrivere uno script di base semplice che imposti le variabili di ambiente utilizzate nelle configurazioni ed esegua tale script prima di avviare AEM. Strumenti come https://direnv.net/ semplificano questo approccio. A seconda del tipo di valori, possono essere sottoposti a check-in nella gestione del codice sorgente, se possono essere condivisi tra tutti.

I valori per i segreti vengono letti dai file. Pertanto, per ogni segnaposto che utilizza un segreto è necessario creare un file di testo contenente il valore segreto.

Ad esempio, se si utilizza $[secret:server_password], è necessario creare un file di testo denominato server_password. Tutti questi file segreti devono essere memorizzati nella stessa directory e la proprietà framework org.apache.felix.configadmin.plugin.interpolation.secretsdir deve essere configurata con quella directory locale.

Configurazione autore e pubblicazione

Se una proprietà OSGI richiede valori diversi per autore e pubblicazione:

• utilizzare cartelle config.author e config.publish OSGi separate, come descritto nella sezione Risoluzione in modalità di esecuzione.
• è necessario utilizzare nomi di variabili indipendenti. Si consiglia di utilizzare un prefisso come author_<variablename> e publish_<variablename> in cui i nomi delle variabili sono identici

Esempi di configurazione

Negli esempi riportati di seguito, si supponga che siano presenti 3 ambienti di sviluppo, oltre agli ambienti stage e prod.

Esempio 1

L'intento è che il valore della proprietà OSGI my_var1 sia lo stesso per stage e prod, ma differisca per ciascuno degli ambienti di sviluppo 3.

{ 
 "my_var1": "val",
 "my_var2": "abc",
 "my_var3": 500
}

{ 
 "my_var1": "$[env:my_var1]"
 "my_var2": "abc",
 "my_var3": 500
}

Esempio 2

L'intento è che il valore della proprietà OSGI my_var1 differisca per l'area di visualizzazione, il prod e per ciascuno degli ambienti di sviluppo 3. Pertanto, l'API di Cloud Manager dovrà essere chiamata per impostare il valore per my_var1 per ogni env di dev.

{ 
 "my_var1": "val1",
 "my_var2": "abc",
 "my_var3": 500
}

{ 
 "my_var1": "val2",
 "my_var2": "abc",
 "my_var3": 500
}

{ 
 "my_var1": "$[env:my_var1]"
 "my_var2": "abc",
 "my_var3": 500
}

Esempio 3

L'intento è che il valore della proprietà OSGi my_var1 sia lo stesso per il palco, la produzione e solo uno degli ambienti di sviluppo, ma che sia diverso per gli altri due ambienti di sviluppo. In questo caso, l'API di Cloud Manager dovrà essere chiamata per impostare il valore di my_var1 per ciascun ambiente di sviluppo, anche per l'ambiente di sviluppo che dovrebbe avere lo stesso valore di fase e produzione. Non erediterà il valore impostato nella cartella config.

{ 
 "my_var1": "val1",
 "my_var2": "abc",
 "my_var3": 500
}

{ 
 "my_var1": "$[env:my_var1]"
 "my_var2": "abc",
 "my_var3": 500
}

Un altro modo per farlo sarebbe impostare un valore predefinito per il token di sostituzione nella cartella config.dev in modo che sia lo stesso valore della cartella config.

{ 
 "my_var1": "val1",
 "my_var2": "abc",
 "my_var3": 500
}

{ 
 "my_var1": "$[env:my_var1;default=val1]"
 "my_var2": "abc",
 "my_var3": 500
}

Formato API di Cloud Manager per l'impostazione delle proprietà

Consultate questa pagina su come deve essere configurata l'API.

Impostazione dei valori tramite API

La chiamata dell'API implementerà le nuove variabili e i nuovi valori in un ambiente Cloud, simile a una tipica pipeline di distribuzione del codice cliente. I servizi di creazione e pubblicazione verranno riavviati e faranno riferimento ai nuovi valori, in genere impiegando alcuni minuti.

PATCH /program/{programId}/environment/{environmentId}/variables

]
        {
                "name" : "MY_VAR1",
                "value" : "plaintext value",
                "type" : "string"  <---default
        },
        {
                "name" : "MY_VAR2",
                "value" : "<secret value>",
                "type" : "secretString"
        }
]

Le variabili predefinite non sono impostate tramite API, ma nella proprietà OSGi stessa.

Per ulteriori informazioni, vedere questa pagina.

Ottenimento di valori tramite API

GET /program/{programId}/environment/{environmentId}/variables

Per ulteriori informazioni, vedere questa pagina.

Eliminazione di valori tramite API

PATCH /program/{programId}/environment/{environmentId}/variables

Per eliminare una variabile, includetela con un valore vuoto.

Per ulteriori informazioni, vedere questa pagina.

Ottenimento dei valori tramite la riga di comando

$ aio cloudmanager:list-environment-variables ENVIRONMENT_ID
Name     Type         Value
MY_VAR1  string       plaintext value 
MY_VAR2  secretString ****

Impostazione dei valori tramite la riga di comando

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --variable MY_VAR1 "plaintext value" --secret MY_VAR2 "some secret value"

Eliminazione dei valori tramite la riga di comando

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --delete MY_VAR1 MY_VAR2

Numero di variabili

È possibile dichiarare fino a 200 variabili per ambiente.

Considerazioni sulla distribuzione di valori di configurazione specifici per l'ambiente e il segreto

Poiché i valori di configurazione segreti e specifici dell'ambiente non rientrano in Git e, pertanto, non fanno parte del AEM formale come meccanismi di implementazione del Cloud Service, il cliente deve gestire, governare e integrare nel AEM come processo di implementazione del Cloud Service.

Come già detto, chiamando l'API i nuovi valori e variabili verranno distribuiti negli ambienti Cloud, in modo simile a un tipico pipeline di distribuzione del codice cliente. I servizi di creazione e pubblicazione verranno riavviati e faranno riferimento ai nuovi valori, in genere impiegando alcuni minuti. I cancelli di qualità e i test eseguiti da Cloud Manager durante una distribuzione regolare del codice non vengono eseguiti durante questo processo.

In genere, i clienti richiamano l'API per impostare le variabili di ambiente prima di distribuire il codice che si basa su di esse in Cloud Manager. In alcuni casi, è possibile modificare una variabile esistente dopo che il codice è già stato distribuito.

L'API potrebbe non riuscire quando è in uso una pipeline, un aggiornamento AEM o una distribuzione cliente, a seconda di quale parte della pipeline end-to-end viene eseguita in quel momento. La risposta di errore indica che la richiesta non è riuscita, anche se non indicherà il motivo specifico.

Potrebbero verificarsi situazioni in cui una distribuzione programmata del codice cliente si basa su variabili esistenti per avere nuovi valori, il che non sarebbe appropriato per il codice corrente. Se questo è un problema, si consiglia di apportare modifiche variabili in modo additivo. A tal fine, create nuovi nomi di variabili invece di modificare semplicemente il valore di vecchie variabili in modo che il codice non faccia mai riferimento al nuovo valore. Quindi, quando il nuovo rilascio del cliente appare stabile, è possibile scegliere di rimuovere i valori precedenti.

Analogamente, poiché i valori di una variabile non dispongono di una versione, un rollback del codice potrebbe fare riferimento a valori più recenti che causano problemi. Anche in questo caso la suddetta strategia di variabile additiva sarebbe d'aiuto.

Questa strategia di variabile additiva è utile anche per gli scenari di disaster recovery in cui, se si desidera ridistribuire il codice da diversi giorni, i nomi e i valori delle variabili a cui fa riferimento rimarranno intatti. Questo si basa su una strategia in cui il cliente attende alcuni giorni prima di rimuovere le vecchie variabili, altrimenti il codice meno recente non avrebbe variabili appropriate a cui fare riferimento.