Configuration d’OSGi pour Adobe Experience Manager as a Cloud Service

Le framework OSGi est un élément fondamental de la pile technologique d’Adobe Experience Manager (AEM). Il est utilisé pour contrôler les lots composites d’AEM et leurs configurations.

OSGi fournit les primitives normalisées qui permettent de construire des applications à partir de petits composants réutilisables et collaboratifs. Ces composants peuvent être créés dans une application et déployés. Cela permet une gestion conviviale des lots OSGi, car ils peuvent être arrêtés, installés et démarrés individuellement. Les interdépendances sont gérées automatiquement. Chaque composant OSGi est contenu dans l’un des différents lots. Pour plus d’informations, voir la spécification OSGi.

Vous pouvez gérer les paramètres de configuration des composants OSGi par le biais de fichiers de configuration intégrés à un projet de code AEM.

Fichiers de configuration OSGi

Les modifications de configuration sont définies dans les packages de code du projet AEM (ui.apps) en tant que fichiers de configuration (.cfg.json) sous les dossiers de configuration spécifiques au mode d’exécution :

/apps/example/config.<runmode>

Le format des fichiers de configuration OSGi est basé sur JSON et suit le format .cfg.json défini par le projet Apache Sling.

Les configurations OSGi ciblent les composants OSGi à l’aide de leur identifiant persistant (PID), qui correspond, par défaut, au nom de classe Java™ du composant OSGi. Par exemple, pour fournir une configuration OSGi pour un service OSGi implémenté par :

com.example.workflow.impl.ApprovalWorkflow.java

un fichier de configuration OSGi est défini à l’adresse suivante :

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

selon le format de configuration OSGi cfg.json.

Résolution du mode d’exécution

Il est possible de cibler des configurations OSGi spécifiques sur des instances AEM données grâce aux modes d’exécution. Pour utiliser un mode d’exécution, créez des dossiers de configuration sous /apps/example (« example » correspondant au nom de votre projet), selon le format suivant :

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

Les configurations OSGi de ces dossiers sont utilisées si les modes d’exécution définis dans le nom de dossier de configuration correspondent aux modes utilisés par AEM.

Par exemple, si AEM utilise les modes d’exécution author et dev, les nœuds de configuration contenus dans /apps/example/config.author/ et /apps/example/config.author.dev/ sont appliqués, tandis que les nœuds de configuration contenus dans /apps/example/config.publish/ et /apps/example/config.author.stage/ ne le sont pas.

Si plusieurs configurations correspondant au même PID sont applicables, la configuration comportant le nombre le plus élevé de modes d’exécution correspondants est appliquée.

La granularité de cette règle se trouve au niveau du PID. Vous ne pouvez pas définir certaines propriétés pour le même PID dans /apps/example/config.author/ et des propriétés plus spécifiques dans /apps/example/config.author.dev/ pour le même PID. La configuration comportant le nombre le plus élevé de modes d’exécution correspondants est effective pour tout le PID.

Lors d’un développement local, un paramètre de démarrage en mode d’exécution, -r, est utilisé pour spécifier la configuration OSGI du mode d’exécution.

$ java -jar aem-sdk-quickstart-xxxx.x.xxx.xxxx-xxxx.jar -r publish,dev

Vérifier les modes d’exécution

Les modes d’exécution AEM as a Cloud Service sont bien définis en fonction du type d’environnement et du service. Consultez la liste complète des modes d’exécution d’AEM as a Cloud Service disponibles.

Les valeurs de configuration OSGi spécifiées par le mode d’exécution peuvent être vérifiées en :

1. Ouvrant Developer Console pour les environnements AEM as a Cloud Services
2. Sélectionnant le ou les niveaux de service à inspecter, à l’aide du menu déroulant Capsule.
3. Sélectionnant l’onglet Statut
4. Sélectionnant des Configurations du menu déroulant Export de statut
5. Cliquant sur le bouton Obtenir le statut

La vue résultante affiche toutes les configurations de composant OSGi pour le ou les niveaux sélectionnés avec leurs valeurs de configuration OSGi applicables. Ces valeurs peuvent être référencées de manière croisée avec les valeurs de configuration OSGi dans le code source du projet AEM sous /apps/example/osgiconfig/config.<runmode(s)>.

Pour vérifier que les valeurs de configuration OSGi appropriées sont appliquées :

1. Dans la sortie Configuration de Developer Console
2. Recherchez le pid représentant la configuration OSGi à vérifier ; il s’agit du nom du fichier de configuration OSGi dans le code source du projet AEM.
3. Vérifiez la liste properties pour le pid et que la clé et les valeurs correspondent au fichier de configuration OSGi dans le code source du projet AEM pour le mode d’exécution en cours de vérification. =

Types de valeurs de configuration OSGi

Il existe trois types de valeurs de configuration OSGi utilisables avec Adobe Experience Manager as a Cloud Service.

1. Valeurs intégrées, codées en dur dans la configuration OSGi et stockées dans Git. Par exemple :

   {
      "connection.timeout": 1000
   }
   

2. Valeurs secrètes, qui ne doivent pas être stockées dans Git pour des raisons de sécurité. Par exemple :

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

3. Valeurs spécifiques à un environnement, qui varient selon les environnements de développement et ne peuvent donc pas être ciblées avec précision par le mode d’exécution (puisqu’il existe un seul mode d’exécution dev dans Adobe Experience Manager as a Cloud Service). Par exemple :

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

   Un seul fichier de configuration OSGi peut utiliser conjointement n’importe quelle combinaison de ces types de valeurs de configuration. Par exemple :

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

Choix du type de valeur de configuration OSGi approprié

Le cas le plus courant pour OSGi consiste à utiliser des valeurs de configuration OSGi intégrées. Les configurations spécifiques à un environnement ne s’appliquent que pour des cas d’utilisation spécifiques où une valeur diffère d’un environnement de développement à l’autre.

Les configurations spécifiques à un environnement étendent les configurations OSGi traditionnelles définies de manière statique, qui contiennent des valeurs intégrées. Elles permettent de gérer les valeurs de configuration OSGi de manière externe via l’API Cloud Manager. Il est important de comprendre dans quels cas appliquer l’approche la plus courante et traditionnelle consistant à définir les valeurs intégrées et à les stocker dans Git, au lieu de les abstraire dans des configurations spécifiques à un environnement.

Les conseils suivants expliquent dans quels cas utiliser des configurations spécifiques à un environnement, secrètes ou non :

Cas d’utilisation de valeurs de configuration intégrées

Les valeurs de configuration intégrées sont considérées comme l’approche standard à utiliser dans la mesure du possible. Les configurations intégrées offrent les avantages suivants :

• Elles sont gérées à l’aide de règles de gouvernance et d’un historique des versions dans Git.
• Les valeurs sont implicitement liées aux déploiements de code.
• Elles ne nécessitent aucune autre considération ni coordination de déploiement.

Lorsque vous définissez une valeur de configuration OSGi, commencez avec des valeurs intégrées, et ne sélectionnez que les configurations secrètes ou spécifiques à un environnement, si le cas d’utilisation le nécessite.

Cas d’utilisation de valeurs de configuration non secrètes spécifiques à un environnement

N’utilisez des configurations spécifiques à un environnement ($[env:ENV_VAR_NAME]) que pour les valeurs de configuration non secrètes lorsque les valeurs varient pour le niveau d’aperçu ou varient selon les environnements de développement. Cela inclut les instances de développement en local et les environnements de développement Adobe Experience Manager as a Cloud Service. Outre la définition de valeurs uniques pour le niveau d’aperçu, évitez d’utiliser des configurations non secrètes spécifiques à des environnements d’évaluation ou de production d’Adobe Experience Manager as a Cloud Service.

• N’utilisez des configurations non secrètes spécifiques à un environnement que pour les valeurs de configuration qui diffèrent entre le niveau de publication et de prévisualisation, ou pour les valeurs qui diffèrent entre les environnements de développement, y compris les instances de développement locales.
• Outre le scénario où le niveau d’aperçu doit varier du niveau de publication, utilisez les valeurs intégrées standard dans les configurations OSGi pour les valeurs non secrètes d’évaluation et de production. À cet égard, il n’est pas recommandé d’utiliser des configurations spécifiques à un environnement pour faciliter les modifications de configuration au moment de l’exécution dans les environnements d’évaluation et de production ; ces modifications doivent être introduites par le biais du processus de gestion du code source.

Cas d’utilisation de valeurs secrètes de configuration spécifiques à un environnement

Adobe Experience Manager as a Cloud Service nécessite des configurations spécifiques à un environnement ($[secret:SECRET_VAR_NAME]) pour toute valeur secrète de configuration OSGi (mots de passe, clés d’API privées) ou toute autre valeur qui ne peut pas être stockée dans Git pour des raisons de sécurité.

Utilisez des configurations secrètes spécifiques à un environnement pour stocker les valeurs secrètes de tous les environnements Adobe Experience Manager as a Cloud Service, y compris ceux d’évaluation et de production.

Création de configurations OSGi

Deux méthodes sont possibles pour créer des configurations OSGi, comme décrit ci-dessous. La première méthode est en général appliquée pour configurer des composants OSGi personnalisés qui possèdent des propriétés et des valeurs OSGi connues du développeur, la seconde pour les composants OSGi fournis par AEM.

Écriture de configurations OSGi

Les fichiers de configuration OSGi au format JSON peuvent être écrits manuellement directement dans le projet AEM. C’est souvent la méthode la plus rapide pour créer des configurations OSGi relatives à des composants OSGi bien connus, et en particulier pour les composants OSGi personnalisés, conçus et mis au point par le développeur qui définit également les configurations. Cette approche peut également être utilisée pour copier/coller et mettre à jour des configurations pour un même composant OSGi sur différents dossiers de mode d’exécution.

1. Dans votre IDE, ouvrez le projet ui.apps, recherchez ou créez le dossier de configuration (/apps/.../config.<runmode>) qui cible les modes d’exécution auxquels la nouvelle configuration OSGi doit s’appliquer
2. Dans ce dossier de configuration, créez un fichier <PID>.cfg.json. Le PID est l’identité persistante du composant OSGi. Il s’agit généralement du nom de classe complet de l’implémentation du composant OSGi. Par exemple :
   /apps/.../config/com.example.workflow.impl.ApprovalWorkflow.cfg.json
   Notez que les noms des fichiers de configuration OSGi d’usine appliquent la convention de dénomination <factoryPID>-<name>.cfg.json.
3. Ouvrez le nouveau fichier .cfg.json et définissez les combinaisons clé/valeur pour les paires propriété et valeur OSGi, en appliquant le format de configuration OSGi JSON.
4. Enregistrez les modifications dans le nouveau fichier .cfg.json.
5. Ajoutez et validez votre nouveau fichier de configuration OSGi sur Git.

Génération de configurations OSGi à l’aide de l’environnement d’exécution Quickstart du SDK AEM

Il est possible d’utiliser la console web AEM de l’environnement d’exécution Quickstart Jar du SDK AEM pour configurer les composants OSGi et exporter les configurations OSGi au format JSON. La console facilite la configuration des composants OSGi fournis par AEM dont les propriétés OSGi et leurs formats de valeurs ne sont pas nécessairement bien maîtrisés par le développeur chargé de définir les configurations OSGi du projet AEM.

1. Connectez-vous à la console web AEM du SDK AEM à l’adresse https://<host>:<port>/system/console en tant qu’utilisateur administrateur
2. Accédez à OSGi > Configuration
3. Pour configurer, recherchez le composant OSGi et appuyez sur son titre pour le modifier.
   
4. Modifiez, si nécessaire, les valeurs des propriétés de configuration OSGi à l’aide de l’interface utilisateur web.
5. Enregistrez l’identité persistante (PID) en lieu sûr. Cette méthode est utilisée ultérieurement pour générer le fichier JSON de configuration OSGi.
6. Appuyez sur Enregistrer.
7. Accédez à OSGi > OSGi Installer Configuration Printer (Imprimante de configuration du programme d’installation OSGi).
8. Collez le PID copié à l’étape 5 et assurez-vous que le format de sérialisation est défini sur OSGi Configurator JSON (Configurateur OSGi au format JSON).
9. Appuyez sur Imprimer.
10. La configuration OSGi au format JSON s’affichera dans la section Propriétés de configuration sérialisées.
    
11. Dans votre IDE, ouvrez le projet ui.apps, recherchez ou créez le dossier de configuration (/apps/.../config.<runmode>) qui cible les modes d’exécution auxquels la nouvelle configuration OSGi doit s’appliquer.
12. Dans ce dossier de configuration, créez un fichier <PID>.cfg.json. Le PID est la même valeur qu’à l’étape 5.
13. Collez les propriétés de configuration sérialisées de l’étape 10 dans le fichier .cfg.json.
14. Enregistrez les modifications dans le nouveau fichier .cfg.json.
15. Ajoutez et validez votre nouveau fichier de configuration OSGi sur Git.

Formats des propriétés de configuration OSGi

Valeurs intégrées

Les valeurs insérées sont formatées en tant que paires nom-valeur normales, selon la syntaxe JSON standard. Par exemple :

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

Valeurs de configuration spécifiques à un environnement

La configuration OSGi doit attribuer un espace réservé à la variable qui doit être définie pour chaque environnement :

use $[env:ENV_VAR_NAME]

Les clients ne doivent utiliser cette technique que pour les propriétés de configuration OSGi liées à leur code personnalisé ; elle ne doit pas être employée pour remplacer la configuration OSGi définie par Adobe.

Valeurs de configuration secrètes

La configuration OSGi doit attribuer un espace réservé au secret qui doit être défini pour chaque environnement :

use $[secret:SECRET_VAR_NAME]

Dénomination des variables

Les règles ci-dessous s’appliquent à la fois aux valeurs de configuration secrètes et à celles spécifiques à un environnement.

Les noms des variables doivent respecter les règles suivantes :

• Longueur minimale : 2
• Longueur maximale : 100
• Respect de l’expression régulière : [a-zA-Z_][a-zA-Z_0-9]*

Les valeurs des variables ne doivent pas dépasser 2 048 caractères.

Valeurs par défaut

Les règles ci-dessous s’appliquent à la fois aux valeurs de configuration secrètes et à celles spécifiques à un environnement.

Si aucune valeur spécifique à l’environnement n’est définie, l’espace réservé n’est pas remplacé au moment de l’exécution. Il est conservé, car aucune interpolation n’a eu lieu. Pour éviter cette situation, une valeur par défaut peut être fournie dans l’espace réservé selon la syntaxe suivante :

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

Si une valeur par défaut est fournie, l’espace réservé est remplacé par la valeur spécifique à l’environnement, s’il en existe une, ou par la valeur par défaut fournie.

Développement local

Les règles ci-dessous s’appliquent à la fois aux valeurs de configuration secrètes et à celles spécifiques à un environnement.

Les variables peuvent être définies dans l’environnement local afin d’être récupérées par l’instance AEM locale au moment de l’exécution. Par exemple, sous Linux® :

export ENV_VAR_NAME=my_value

Il est recommandé d’écrire un script bash simple qui définit les variables d’environnement utilisées dans les configurations et qui les exécute avant de démarrer AEM. Il est possible de simplifier cette approche à l’aide d’outils tels que https://direnv.net/. Selon leurs types, il est possible d’archiver les valeurs dans la gestion du code source (si elles peuvent être partagées avec tous).

Les valeurs des secrets sont lues à partir de fichiers. Il est donc nécessaire de créer un fichier texte contenant la valeur secrète pour chaque espace réservé utilisant un secret.

Si, par exemple, $[secret:server_password] est utilisé, un fichier texte nommé server_password doit être créé. Tous ces fichiers secrets doivent être stockés dans le même répertoire et la propriété de framework org.apache.felix.configadmin.plugin.interpolation.secretsdir doit être configurée avec ce répertoire local.

org.apache.felix.configadmin.plugin.interpolation.secretsdir est une propriété de framework Sling. Par conséquent, cette propriété n’est pas définie dans la console Felix (/system/console?lang=fr), mais dans le fichier sling.properties utilisé lors du démarrage du système. Ce fichier se trouve dans le sous-répertoire /conf du dossier Jar/install extrait (crx-quickstart/conf).

Exemple : ajoutez la ligne suivante à la fin du fichier « crx-quickstart/conf/sling.properties » pour configurer « crx-quickstart/secretsdir » en tant que dossier secret :

org.apache.felix.configadmin.plugin.interpolation.secretsdir=${sling.home}/secretsdir

Configuration de création ou de publication

Si une propriété OSGI nécessite des valeurs différentes pour la création et la publication :

• Des dossiers OSGi config.author et config.publish distincts sont nécessaires, comme décrit dans la section Résolution du mode d’exécution.
• Deux options permettent de créer des noms de variable indépendants :

  • la première option, recommandée : dans tous les dossiers OSGI (comme config.author et config.publish) déclarés pour définir des valeurs différentes, utilisez le même nom de variable. Par exemple :

    $[env:ENV_VAR_NAME;default=<value>], où la valeur par défaut correspond à la valeur par défaut de ce niveau (auteur ou publication). Lors de la définition de la variable d’environnement par le biais de l’API Cloud Manager ou d’un client, différenciez les niveaux à l’aide du paramètre « service », comme décrit dans cette documentation de référence de l’API. Le paramètre « service » lie la valeur de la variable au niveau OSGI approprié. Il peut s’agir de « création », « publication » ou « aperçu ».

  • la deuxième option, qui consiste à déclarer des variables distinctes à l’aide d’un préfixe tel que author_<samevariablename> et publish_<samevariablename> ;

Exemples de configurations

Dans les exemples ci-dessous, supposons qu’il y ait trois environnements de développement, en plus des environnements d’évaluation et de production.

Exemple 1

L’objectif est que la valeur de la propriété OSGi my_var1 soit identique pour l’évaluation et la production, mais différente pour chacun des trois environnements de développement.

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

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

Exemple 2

L’objectif est que la valeur de la propriété OSGi my_var1 soit différente pour l’évaluation, la production ainsi que pour chacun des trois environnements de développement. Il est donc nécessaire d’appeler l’API Cloud Manager afin de définir la valeur de my_var1 pour chaque environnement de développement.

{
 "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
}

Exemple 3

L’objectif est que la valeur de la propriété OSGi my_var1 soit identique pour l’évaluation, la production et un seul des environnements de développement, mais différente pour les deux autres. Dans ce cas, il est nécessaire d’appeler l’API Cloud Manager afin de définir la valeur de my_var1 pour chacun des environnements de développement, y compris celui dont la valeur doit être identique à celle de l’évaluation et de la production. Il n’héritera pas de la valeur définie dans le dossier config.

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

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

Vous pouvez également définir une valeur par défaut pour le jeton de remplacement dans le dossier config.dev, de sorte qu’elle soit identique à celle du dossier config.

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

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

Format de l’API Cloud Manager pour la définition des propriétés

Voir cette page à propos de la configuration de l’API.

Définition de valeurs via l’API

L’appel à l’API déploie les nouvelles variables et valeurs dans un environnement cloud, comme pour un pipeline de déploiement de code client classique. Les services de création et de publication sont redémarrés et font référence aux nouvelles valeurs, généralement en quelques minutes.

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

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

Obtention de valeurs via l’API

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

Pour plus d’informations, consultez cette page.

Suppression de valeurs via l’API

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

Pour supprimer une variable, indiquez-la avec une valeur vide.

Pour plus d’informations, consultez cette page.

Obtention de valeurs via la ligne de commande

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

Définition de valeurs via la ligne de commande

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

Suppression de valeurs via la ligne de commande

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

Nombre de variables

Jusqu’à 200 variables peuvent être déclarées par environnement.

Considérations relatives au déploiement pour les valeurs de configuration secrètes et spécifiques à chaque environnement

Les valeurs de configuration secrètes et spécifiques à chaque environnement étant situées en dehors de Git, et ne faisant pas partie des mécanismes de déploiement officiels d’Adobe Experience Manager as a Cloud Service, le client doit les gérer, les administrer et les intégrer dans le processus de déploiement d’Adobe Experience Manager as a Cloud Service.

Comme mentionné ci-dessus, l’appel à l’API déploie les nouvelles variables et valeurs dans des environnements cloud, comme pour un pipeline de déploiement de code client classique. Les services de création et de publication sont redémarrés et font référence aux nouvelles valeurs, généralement en quelques minutes. Notez que les points de contrôle et tests de qualité exécutés par Cloud Manager pour un déploiement normal de code ne sont pas effectués pendant ce processus.

En règle générale, les clients appellent l’API pour définir les variables d’environnement avant de déployer le code associé dans Cloud Manager. Dans certains cas, vous pouvez modifier une variable existante après le déploiement du code.

Dans certains scénarios, le déploiement du code client planifié nécessite de définir de nouvelles valeurs pour les variables existantes, ce qui n’est pas approprié avec le code en l’état. Si cela pose problème, il est recommandé d’effectuer des modifications par ajout de variables. Pour ce faire, créez des noms de variable au lieu de simplement modifier la valeur des anciennes. Ainsi, l’ancien code ne fera jamais référence à la nouvelle valeur. Ensuite, lorsque la nouvelle version client semble stable, vous pouvez supprimer les anciennes valeurs.

De même, comme les versions des valeurs d’une variable ne sont pas contrôlées, une restauration du code pourrait entraîner des références à des valeurs plus récentes qui posent problème. La stratégie d’ajout de variables mentionnée ci-dessus pourrait aussi contribuer à éviter cette situation.

Cette stratégie d’ajout de variables est également utile pour les scénarios de reprise après sinistre. Dans ce cas, si une version de code datée de plusieurs jours doit être redéployée, les noms et les valeurs de variables auxquels il fait référence restent inchangés. Cette démarche s’appuie sur une stratégie prévoyant qu’un client attend quelques jours avant de supprimer les variables plus anciennes. Dans le cas contraire, l’ancien code ne pourrait pas faire référence aux variables appropriées.

Ressources Business.Adobe.com