Configuration du projet

Modification des détails de configuration du projet

Pour créer et déployer dans Cloud Manager, les projets AEM existants doivent se conformer à certaines règles de base :

• Les projets doivent être créés à l’aide d’Apache Maven.

• Un fichier pom.xml doit se trouver à la racine du référentiel Git. Ce fichier pom.xml peut faire référence à autant de sous-modules (qui, à leur tour, peuvent comporter d’autres sous-modules, etc.) que nécessaire.

• Vous pouvez ajouter des références à d’autres référentiels d’artefact Maven dans vos fichiers pom.xml. L’accès aux référentiels d’artefacts protégés par mot de passe est pris en charge s’il est configuré. Cependant, l’accès aux référentiels d’artefacts protégés par réseau n’est pas pris en charge.

• Les packages de contenu déployables sont découverts en analysant les fichiers zip de package de contenu se trouvant dans un répertoire appelé target. Un nombre illimité de sous-modules peut produire des packages de contenu.

• Les artefacts déployables de Dispatcher sont découverts en analysant les fichiers zip (contenus dans un répertoire appelé target) dont les répertoires sont appelés conf et conf.d.

• S’il existe plusieurs packages de contenu, l’ordre des déploiements des packages n’est pas garanti. Si un ordre spécifique est nécessaire, il est possible d’utiliser les dépendances de package pour le définir. Les packages peuvent être ignorés du déploiement.

Activation des profils Maven dans Cloud Manager

Dans certains cas, vous devrez peut-être légèrement modifier le processus de génération lors de l’exécution dans Cloud Manager, contrairement à celui qui s’exécute sur les postes de travail des développeurs. Dans ce cas, les profils Maven peuvent être utilisés pour définir la manière dont la génération doit être différente dans différents environnements, notamment Cloud Manager.

L’activation d’un profil Maven dans l’environnement de génération Cloud Manager doit se faire en recherchant la présence de la variable d’environnement appelée CM_BUILD, décrite plus haut. Par contre, un profil destiné à être utilisé uniquement en dehors de l’environnement de création Cloud Manager doit être généré en vérifiant l’absence de cette variable.

Par exemple, si vous souhaitez générer un message de sortie simple uniquement lorsque la génération est exécutée dans Cloud Manager, procédez comme suit :

        <profile>
            <id>cmBuild</id>
            <activation>
                  <property>
                        <name>env.CM_BUILD</name>
                  </property>
            </activation>
            <build>
                <plugins>
                    <plugin>
                        <artifactId>maven-antrun-plugin</artifactId>
                        <version>1.8</version>
                        <executions>
                            <execution>
                                <phase>initialize</phase>
                                <configuration>
                                    <target>
                                        <echo>I'm running inside Cloud Manager!</echo>
                                    </target>
                                </configuration>
                                <goals>
                                    <goal>run</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>

Si vous souhaitez générer un message de sortie simple uniquement lorsque la génération est exécutée en dehors de Cloud Manager, procédez comme suit :

        <profile>
            <id>notCMBuild</id>
            <activation>
                  <property>
                        <name>!env.CM_BUILD</name>
                  </property>
            </activation>
            <build>
                <plugins>
                    <plugin>
                        <artifactId>maven-antrun-plugin</artifactId>
                        <version>1.8</version>
                        <executions>
                            <execution>
                                <phase>initialize</phase>
                                <configuration>
                                    <target>
                                        <echo>I'm running outside Cloud Manager!</echo>
                                    </target>
                                </configuration>
                                <goals>
                                    <goal>run</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>

Prise en charge d’un référentiel Maven protégé par mot de passe

Pour utiliser un référentiel Maven protégé par mot de passe dans Cloud Manager, spécifiez le mot de passe (et éventuellement le nom d’utilisateur) en tant que Variable pipeline secrète, puis référencez ce secret dans un fichier nommé .cloudmanager/maven/settings.xml dans le référentiel git. Ce fichier suit le schéma de fichier de paramètres Maven. Au démarrage du processus de création de Cloud Manager, l’élément <servers> de ce fichier est fusionné dans le fichier settings.xml par défaut fourni par Cloud Manager. Les ID de serveur commençant par adobe et cloud-manager sont considérés comme réservés et ne doivent pas être utilisés par des serveurs personnalisés. Les ID de serveur ne correspondant pas à l’un de ces préfixes ou à l’ID par défaut central ne seront jamais mis en miroir par Cloud Manager. Une fois ce fichier en place, l’ID de serveur est référencé à l’intérieur d’un élément <repository> et/ou <pluginRepository> dans le fichier pom.xml. En règle générale, ces éléments <repository> et/ou <pluginRepository> sont contenus dans un profil spécifique à Cloud Manager, bien que cela ne soit pas strictement nécessaire.

Par exemple, supposons que le référentiel se trouve à l’adresse https://repository.myco.com/maven2, que le nom d’utilisateur que Cloud Manager doit utiliser soit cloudmanager et que le mot de passe soit secretword.

Tout d’abord, définissez le mot de passe comme secret sur le pipeline :

$ aio cloudmanager:set-pipeline-variables PIPELINEID --secret CUSTOM_MYCO_REPOSITORY_PASSWORD secretword

Faites ensuite référence à ceci à partir du fichier .cloudmanager/maven/settings.xml :

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>myco-repository</id>
            <username>cloudmanager</username>
            <password>${env.CUSTOM_MYCO_REPOSITORY_PASSWORD}</password>
        </server>
    </servers>
</settings>

Enfin référencez l’identifiant du serveur dans le fichier pom.xml :

<profiles>
    <profile>
        <id>cmBuild</id>
        <activation>
                <property>
                    <name>env.CM_BUILD</name>
                </property>
        </activation>
        <repositories>
             <repository>
                 <id>myco-repository</id>
                 <name>MyCo Releases</name>
                 <url>https://repository.myco.com/maven2</url>
                 <snapshots>
                     <enabled>false</enabled>
                 </snapshots>
                 <releases>
                     <enabled>true</enabled>
                 </releases>
             </repository>
         </repositories>
         <pluginRepositories>
             <pluginRepository>
                 <id>myco-repository</id>
                 <name>MyCo Releases</name>
                 <url>https://repository.myco.com/maven2</url>
                 <snapshots>
                     <enabled>false</enabled>
                 </snapshots>
                 <releases>
                     <enabled>true</enabled>
                 </releases>
             </pluginRepository>
         </pluginRepositories>
    </profile>
</profiles>

Déploiement de sources

Il est recommandé de déployer les sources Java avec le binaire dans un référentiel Maven.

Configurez le module maven-source-plugin dans votre projet :

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-source-plugin</artifactId>
            <executions>
                <execution>
                    <id>attach-sources</id>
                    <goals>
                        <goal>jar-no-fork</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

Déploiement de sources de projet

Il est recommandé de déployer la source du projet dans son intégralité avec le binaire dans un référentiel Maven, ce qui permet de reconstruire l’artefact exact.

Configurez le module maven-assembly-plugin dans votre projet :

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-assembly-plugin</artifactId>
            <executions>
                <execution>
                    <id>project-assembly</id>
                    <phase>package</phase>
                    <goals>
                        <goal>single</goal>
                    </goals>
                    <configuration>
                        <descriptorRefs>
                            <descriptorRef>project</descriptorRef>
                        </descriptorRefs>
                    </configuration>
                </execution>
            </executions>
        </plugin>

Omission des modules de contenu

Dans Cloud Manager, chaque compilation peut produire un certain nombre de modules de contenu.
Pour diverses raisons, il peut être préférable de produire un module de contenu, mais de ne pas le déployer. Cela peut s’avérer utile, par exemple, lors de la création de modules de contenu utilisés uniquement à des fins de test ou qui seront recompilés lors d’une autre étape du processus de compilation, c’est-à-dire sous la forme d’un sous-module d’un autre module.

Pour tenir compte de ces scénarios, Cloud Manager recherche une propriété nommée cloudManagerTarget dans les propriétés des modules de contenu créés. Si cette propriété est définie sur « none (aucun) », le module sera ignoré et non déployé. Le mécanisme permettant de définir cette propriété dépend de la manière dont la compilation produit le module de contenu. Par exemple, avec filevault-maven-plugin, vous devez configurer le module externe comme suit :

        <plugin>
            <groupId>org.apache.jackrabbit</groupId>
            <artifactId>filevault-package-maven-plugin</artifactId>
            <extensions>true</extensions>
            <configuration>
                <properties>
                    <cloudManagerTarget>none</cloudManagerTarget>
                </properties>
        <!-- other configuration -->
            </configuration>
        </plugin>

Avec content-package-maven-plugin, il est similaire :

        <plugin>
            <groupId>com.day.jcr.vault</groupId>
            <artifactId>content-package-maven-plugin</artifactId>
            <extensions>true</extensions>
            <configuration>
                <properties>
                    <cloudManagerTarget>none</cloudManagerTarget>
                </properties>
        <!-- other configuration -->
            </configuration>
        </plugin>

Réutilisation de l’artefact de création

Dans de nombreux cas, le même code est déployé dans plusieurs environnements AEM. Dans la mesure du possible, Cloud Manager évite de reconstruire la base de code lorsqu’il détecte que la même validation Git est utilisée dans plusieurs exécutions de pipeline pleine pile.

Lorsqu’une exécution est lancée, la validation de l’HEAD en cours pour le pipeline de branche est extraite. Le hachage de validation est visible dans l’interface utilisateur et via l’API. Une fois l’étape de création terminée, les artefacts obtenus sont stockés en fonction de ce hachage de validation et peuvent être réutilisés lors des exécutions suivantes du pipeline. Lorsqu’une réutilisation se produit, les étapes de création et de qualité du code sont effectivement remplacées par les résultats de l’exécution d’origine. Le fichier journal de l’étape de création répertorie les artefacts et les informations d’exécution qui ont été utilisés pour les créer initialement.

Voici un exemple de ce type de sortie de journal.

The following build artifacts were reused from the prior execution 4 of pipeline 1 which used commit f6ac5e6943ba8bce8804086241ba28bd94909aef:
build/aem-guides-wknd.all-2021.1216.1101633.0000884042.zip (content-package)
build/aem-guides-wknd.dispatcher.cloud-2021.1216.1101633.0000884042.zip (dispatcher-configuration)

Le journal de l’étape de qualité du code contient des informations similaires.

Exclusion

Si vous le souhaitez, le comportement de réutilisation peut être désactivé pour des pipelines spécifiques en définissant la variable de pipeline. CM_DISABLE_BUILD_REUSE to true. Si cette variable est définie, le hachage de validation est toujours extrait et les artefacts résultants sont stockés en vue d’une utilisation ultérieure, mais aucun artefact précédemment stocké ne sera réutilisé. Pour comprendre ce comportement, envisagez le scénario suivant.

1. Un nouveau pipeline est créé.
2. Le pipeline est exécuté (exécution #1) et la validation de l’HEAD en cours est becdddb. L’exécution est réussie et les artefacts obtenus sont stockés.
3. Le CM_DISABLE_BUILD_REUSE est définie.
4. Le pipeline est exécuté à nouveau sans modifier le code. Bien qu’il existe des artefacts stockés associés à becdddb, elles ne sont pas réutilisées en raison de la variable CM_DISABLE_BUILD_REUSE .
5. Le code est modifié et le pipeline est exécuté. La validation de l’HEAD est maintenant f6ac5e6. L’exécution est réussie et les artefacts obtenus sont stockés.
6. Le CM_DISABLE_BUILD_REUSE est supprimée.
7. Le pipeline est exécuté à nouveau sans modifier le code. Puisqu’il existe des artefacts stockés associés à f6ac5e6, ces artefacts sont réutilisés.

Restrictions

• Gestion des versions Maven remplacez la version du projet uniquement dans les pipelines de production. Par conséquent, si la même validation est utilisée à la fois sur une exécution de déploiement de développement et une exécution de pipeline de production, et que le pipeline de déploiement de développement est exécuté en premier, les versions sont déployées en environnement intermédiaire et en production sans être modifiées. Cependant, une balise sera toujours créée dans ce cas.
• Si la récupération des artefacts stockés échoue, l’étape de création est exécutée comme si aucun artefact n’avait été stocké.
• Variables de pipeline autres que CM_DISABLE_BUILD_REUSE ne sont pas prises en compte lorsque Cloud Manager décide de réutiliser des artefacts de version créés précédemment.