Configuration d’OSGi pour Adobe Experience Manager as a Cloud Service configuring-osgi-for-aem-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 osgi-configuration-files

Les modifications de configuration sont définies dans les packages de code du projet AEM (ui.config) 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 runmode-resolution

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 :

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 :

Types de valeurs de configuration OSGi types-of-osgi-configuration-values

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

Choix du type de valeur de configuration OSGi approprié how-to-choose-the-appropriate-osgi-configuration-value-type

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 when-to-use-inline-configuration-values

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 :

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 when-to-use-non-secret-environment-specific-configuration-values

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.

Cas d’utilisation de valeurs secrètes de configuration spécifiques à un environnement when-to-use-secret-environment-specific-configuration-values

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 creating-osgi-configurations

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 writing-osgi-configurations

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.

Génération de configurations OSGi à l’aide de l’environnement d’exécution Quickstart du SDK AEM generating-osgi-configurations-using-the-aem-sdk-quickstart

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.

Formats des propriétés de configuration OSGi osgi-configuration-property-formats

Valeurs intégrées inline-values

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 environment-specific-configuration-values

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 secret-configuration-values

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 variable-naming

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 :

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

Valeurs par défaut default-values

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 local-development

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 (https://experienceleague.adobe.com/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 author-vs-publish-configuration

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

Exemples de configurations configuration-examples

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 cloud-manager-api-format-for-setting-properties

Pour plus d’informations sur l’API Cloud Manager et sur sa configuration, voir Adobe Cloud Manager sur le site Web d’Adobe Developer .

Définition de valeurs via l’API setting-values-via-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 getting-values-via-api

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

Voir API Cloud Manager pour plus d’informations.

Suppression de valeurs via l’API deleting-values-via-api

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

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

Voir API Cloud Manager pour plus d’informations.

Obtention de valeurs via la ligne de commande getting-values-via-cli

$ 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 setting-values-via-cli

$ 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 deleting-values-via-cli

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

Nombre de variables number-of-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 deployment-considerations-for-secret-and-environment-specific-configuration-values

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. Les points de contrôle et tests de qualité exécutés par Cloud Manager lors d’un déploiement de code standard 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.