Tâches de maintenance avant la mise à niveau pre-upgrade-maintenance-tasks

Avant de commencer la mise à niveau, il est important d’effectuer ces tâches de maintenance pour vous assurer que le système est prêt et peut être restauré en cas de problème :

Vérification de la disponibilité de l’espace disque nécessaire ensure-sufficient-disk-space

Lors de l’exécution de la mise à niveau, en plus des activités de mise à niveau de contenu et de code, une migration du référentiel doit être effectuée. La migration crée une copie du référentiel au nouveau format de segment Tar. Par conséquent, vous avez besoin de suffisamment d’espace disque pour conserver une seconde version potentiellement plus grande de votre référentiel.

Sauvegarde complète d’AEM fully-back-up-aem

AEM doit être entièrement sauvegardé avant le début de la mise à niveau. Veillez à sauvegarder votre référentiel, l’installation de l’application, le magasin de données et les instances Mongo, le cas échéant. Pour plus d’informations sur la sauvegarde et la restauration d’une instance AEM, reportez-vous à la section Sauvegarde et restauration.

Sauvegarde des modifications sur /etc backup-changes-etc

Le processus de mise à niveau est utile dans le maintien et la fusion du contenu existant et des configurations à partir des chemins d’accès /apps et /libs dans le référentiel. Pour les modifications apportées au chemin d’accès /etc, y compris les configurations Context Hub, il est souvent nécessaire de réappliquer ces modifications après la mise à niveau. Alors que la mise à niveau crée une copie de sauvegarde de toutes les modifications qui ne peuvent pas fusionner sous /var, nous vous recommandons de sauvegarder ces modifications manuellement avant le début de la mise à niveau.

Générer le fichier quickstart.properties generate-quickstart-properties

Lors du démarrage d’AEM depuis le fichier jar, un fichier quickstart.properties est généré sous crx-quickstart/conf. Si AEM a uniquement été démarré avec le script de démarrage dans le passé, ce fichier n’est pas présent et la mise à niveau échoue. Assurez-vous de vérifier l’existence de ce fichier et redémarrez AEM à partir du fichier jar s’il n’est pas présent.

Configuration de la purge du workflow et du journal d’audit configure-wf-audit-purging

Les tâches WorkflowPurgeTask et com.day.cq.audit.impl.AuditLogMaintenanceTask nécessitent des configurations OSGi distinctes et ne fonctionneront pas sans celles-ci. Si elles échouent lors de l’exécution de la tâche avant la mise à niveau, des configurations manquantes en sont la raison la plus probable. Par conséquent, veillez à ajouter des configurations OSGi pour ces tâches ou à les supprimer complètement de la liste des tâches d’optimisation avant la mise à niveau si vous ne souhaitez pas les exécuter. Vous trouverez la documentation relative à la configuration des tâches de purge des workflows dans la section Administration des instances de workflow et la configuration de la tâche de maintenance du journal d’audit dans la section Maintenance du journal d’audit dans AEM 6.

Pour la purge des workflows et des journaux d’audit sur CQ 5.6 et la purge des journaux d’audit sur AEM 6.0, voir Purge des noeuds de workflow et d’audit.

Installation, configuration et exécution des tâches précédant la mise à niveau install-configure-run-pre-upgrade-tasks

En raison du niveau de personnalisation accordé par AEM, il n’existe généralement pas de méthode uniforme pour effectuer les mises à niveau. Ainsi, la création d’une procédure normalisée pour les mises à niveau est un processus difficile.

Dans les versions précédentes, il était également difficile pour les mises à niveau d’AEM ayaqnt été arrêtées ou ayant échoué de reprendre en toute sécurité. Ce problème entraînait des situations où le redémarrage de la procédure de mise à niveau complète était nécessaire ou dans lesquelles des mises à niveau défectueuses étaient effectuées sans déclencher d’avertissement.

Pour résoudre ces problèmes, Adobe a ajouté plusieurs améliorations au processus de mise à niveau, le rendant plus résilient et plus convivial. Les tâches de maintenance préalables à la mise à niveau qui devaient auparavant être effectuées manuellement sont optimisées et automatisées. En outre, des rapports après la mise à niveau ont été ajoutés afin que le processus puisse être entièrement examiné dans l’espoir que les problèmes éventuels soient plus facilement détectés.

Les tâches de maintenance préalables à la mise à niveau sont actuellement réparties sur différentes interfaces, qui sont partiellement ou entièrement exécutées manuellement. L’optimisation de la maintenance avant la mise à niveau introduite dans AEM 6.3 permet de déclencher ces tâches de manière unifiée et d’examiner leur résultat à la demande.

Toutes les tâches incluses dans l’étape d’optimisation avant la mise à niveau sont compatibles avec toutes les versions à partir d’AEM 6.0.

Méthode de configuration how-to-set-it-up

Dans AEM version 6.3 et ultérieure, les tâches d’optimisation de la maintenance avant la mise à niveau sont incluses dans le fichier jar de démarrage rapide.

Utilisation how-to-use-it

Le composant OSGi PreUpgradeTasksMBean est préconfiguré avec une liste de tâches de maintenance bénéficiant déjà de la mise à niveau, pouvant toutes être exécutées simultanément. Vous pouvez configurer les tâches en suivant la procédure ci-dessous :

  1. Accédez à la console web en vous rendant sur https://serveraddress:serverport/system/console/configMgr.

  2. Recherchez «  preupgradetasks  », puis cliquez sur le premier composant correspondant. Le nom complet du composant est com.adobe.aem.upgrade.prechecks.mbean.impl.PreUpgradeTasksMBeanImpl.

  3. Modifiez la liste des tâches de maintenance devant être exécutées comme illustré ci-dessous :

    1487758925984

La liste des tâches varie en fonction du mode d’exécution utilisé pour démarrer l’instance. Vous trouverez ci-dessous une description du mode d’exécution pour lequel chaque tâche de maintenance est conçue.

Tâche
Mode d’exécution
Remarques
TarIndexMergeTask
crx2
DataStoreGarbageCollectionTask
crx2
Exécute un marquage et un balayage. Pour les magasins de données partagés, supprimez cette étape et exécutez
manuellement ou préparez correctement les instances avant l’exécution.
ConsistencyCheckTask
crx2
WorkflowPurgeTask
crx2/crx3
Doit configurer la configuration OSGi de purge du workflow Granite d’Adobe avant l’exécution.
GenerateBundlesListFileTask
crx2/crx3
RevisionCleanupTask
crx3
Pour les instances TarMK sur AEM 6.0 à 6.2, exécutez manuellement le nettoyage des révisions hors ligne à la place.
com.day.cq.audit.impl.AuditLogMaintenanceTask
crx3
Doit configurer la configuration OSGi du planificateur de purge du journal d’audit avant l’exécution.
CAUTION
La DataStoreGarbageCollectionTask appelle l’opération de récupération de l’espace mémoire du magasin de données avec la phase de marquage et de balayage, le cas échéant. Pour les déploiements qui utilisent un magasin de données partagé, veillez à le reconfigurer correctement ou à préparer l’instance afin d’éviter la suppression des éléments référencés par une autre instance. Ce processus peut nécessiter l’exécution manuelle de la phase de marquage sur toutes les instances avant de déclencher cette tâche préalable à la mise à niveau.

Configuration par défaut des contrôles de l’intégrité avant la mise à niveau default-configuration-of-the-pre-upgrade-health-checks

Le composant OSGi PreUpgradeTasksMBeanImpl est préconfiguré avec une liste de balises de vérification de l’intégrité précédant la mise à niveau à exécuter lorsque la méthode runAllPreUpgradeHealthChecks est appelée :

  • système  : balise utilisée par les contrôles de l’intégrité de la maintenance Granite

  • avant la mise à niveau  : balise personnalisée qui peut être ajoutée à toutes les vérifications d’intégrité dont vous pouvez définir l’exécution avant une mise à niveau

La liste peut être modifiée. Vous pouvez utiliser les boutons plus (+) et moins (-) en plus des balises pour ajouter d’autres balises personnalisées ou supprimer les balises par défaut.

Méthodes MBean

La fonctionnalité Bean gérée est accessible à l’aide de la console JMX.

Vous pouvez accéder aux MBeans en procédant comme suit :

  1. Accédez à la console JMX à l’adresse https://serveraddress:serverport/system/console/jmx.

  2. Recherchez PreUpgradeTasks et cliquez sur le résultat.

  3. Sélectionnez une méthode à partir de la section Opérations et sélectionnez Invoquer dans la fenêtre suivante.

Vous trouverez ci-dessous la liste de toutes les méthodes disponibles offertes par PreUpgradeTasksMBeanImpl :

Nom de méthode
Type
Description
getAvailablePreUpgradeTasksNames()
INFO
Affiche la liste des noms des tâches de maintenance disponibles avant la mise à niveau.
getAvailablePreUpgradeHealthChecksTagNames()
INFO
Affiche la liste des noms des balises de vérification d’intégrité avant la mise à niveau.
runAllPreUpgradeTasks()
ACTION
Exécute toutes les tâches de maintenance avant la mise à niveau de la liste.
runPreUpgradeTask(preUpgradeTaskName)
ACTION
Exécute la tâche de maintenance avant la mise à niveau avec le nom donné en tant que paramètre.
isRunAllPreUpgradeTaskRunning()
ACTION_INFO
Vérifie si la tâche runAllPreUpgradeTasksmaintenance est en cours d’exécution.
getAnyPreUpgradeTaskRunning()
ACTION_INFO
Vérifie si une tâche de maintenance avant la mise à niveau est en cours d’exécution et
renvoie un tableau contenant les noms des tâches en cours d’exécution.
getPreUpgradeTaskLastRunTime(preUpgradeTaskName)
ACTION
Affiche l’heure d’exécution exacte de la tâche de maintenance avant la mise à niveau avec le nom donné en tant que paramètre.
getPreUpgradeTaskLastRunState(preUpgradeTaskName)
ACTION
Affiche le dernier état d’exécution de la tâche de maintenance avant la mise à niveau avec le nom donné en tant que paramètre.
runAllPreUpgradeHealthChecks(shutDownOnSuccess)
ACTION

Exécute toutes les vérifications d’intégrité avant la mise à niveau et enregistre leur statut dans un fichier nommé preUpgradeHCStatus.properties situé sur le chemin d’accès Sling de l’accueil. Si le paramètre shutDownOnSuccess est défini sur true, l’instance AEM est arrêtée, mais uniquement lorsque toutes les vérifications d’intégrité avant la mise à niveau ont le statut « OK ».

Le fichier de propriétés est utilisé comme prérequis pour toute mise à niveau ultérieure
et le processus de mise à niveau est arrêté si l’exécution de la vérification de l’intégrité précédant la mise à niveau
a échoué. Si vous souhaitez tout de même ignorer le résultat des vérifications d’intégrité
avant la mise à niveau et lancer la mise à niveau, vous pouvez supprimer le fichier.

detectUsageOfUnavailableAPI(aemVersion)
ACTION
Répertorie tous les packages importés qui ne fonctionneront plus lors
de la mise à niveau à la version d’AEM spécifiée. La version AEM cible doit être
indiquée en tant que paramètre.
NOTE
Les méthodes MBean peuvent être invoquées via :
  • La console JMX
  • Toute application externe qui se connecte à JMX
  • cURL

Désactivation des modules de connexion personnalisés disable-custom-login-modules

NOTE
Cette étape est nécessaire uniquement si vous effectuez une mise à niveau à partir d’une version d’AEM 5. Elle peut être entièrement ignorée pour les mises à niveau à partir des versions plus anciennes à AEM 6.

La manière dont les modules de connexion LoginModules sont configurés pour l’authentification au niveau du référentiel a complètement changé dans Apache Oak.

Dans les versions d’AEM qui utilisaient CRX2, la configuration était placée dans le fichier repository.xml du référentiel alors qu’à partir de la version 6 et suivantes, cette opération est effectuée dans le service Apache Felix JAAS Configuration Factory via la console web.

En conséquence, toute configuration existante doit être désactivée et recréée pour Apache Oak après la mise à niveau.

Pour désactiver les modules personnalisés définis dans la configuration JAAS de repository.xml, vous devez modifier la configuration pour utiliser la valeur LoginModule par défaut, comme dans l’exemple suivant :

<Security >
             ....
          <!--
                 Use LoginModule authenticating against repository itself
                 -->
                 <LoginModule class = "com.day.crx.core.CRXLoginModule" >
                     <param name = "anonymousId" value = "anonymous" />
                     <param name = "adminId" value ="admin" />
                     <param name = "disableNTLMAuth" value = "true" />
                     <param name = "tokenExpiration" value = "43200000" />
                     <!-- param name="trust_credentials_attribute" value="d5b9167e95dad6e7d3b5d6fa8df48af8"/
                -->
                 </LoginModule >
         </ Security>
NOTE
Pour plus d’informations, consultez la section Authentification avec le module de connexion externe.
Pour un exemple de configuration de LoginModule dans AEM 6, consultez la section Configuration de LDAP avec AEM 6.

Suppression des mises à jour du répertoire /install remove-updates-install-directory

NOTE
Supprimez uniquement les packages du répertoire crx-quickstart/install APRÈS avoir arrêté l’instance AEM. Cette étape est l’une des dernières avant de commencer la procédure de mise à niveau statique.

Supprimez tous les packs de services, les packs de fonctionnalités ou les correctifs logiciels qui ont été déployés via le répertoire crx-quickstart/install sur le système de fichiers local. Cela évite l’installation accidentelle d’anciens correctifs et packs de services en plus de la nouvelle version d’AEM une fois la mise à jour terminée.

Arrêt de toutes les instances Cold Standby stop-tarmk-coldstandby-instance

Si vous utilisez un secours différé TarMK, arrêtez tous les secours différés. Cela garantit un moyen efficace de revenir en ligne en cas de problèmes lors de la mise à niveau. Une fois la mise à niveau terminée, les secours différés doivent être reconstruits à partir des instances principales mises à niveau.

Désactivation des tâches planifiées personnalisées disable-custom-scheduled-jobs

Désactivez toutes les tâches OSGi planifiées incluses dans le code de votre application.

Exécution d’un nettoyage des révisions hors ligne execute-offline-revision-cleanup

NOTE
Cette étape n’est nécessaire que pour les installations TarMK.

Si vous utilisez TarMK, vous devez exécuter le nettoyage des révisions hors ligne avant la mise à niveau. Cela permet à l’étape de migration du référentiel et aux tâches de mise à niveau suivantes de s’exécuter beaucoup plus rapidement et de garantir que le nettoyage des révisions en ligne peut s’exécuter correctement une fois la mise à niveau terminée. Pour plus d’informations sur l’exécution du nettoyage des révisions hors ligne, reportez-vous à la section Exécution du nettoyage des révisions hors ligne.

Exécution de la récupération de l’espace mémoire du magasin de données execute-datastore-garbage-collection

NOTE
Cette étape n’est nécessaire que pour les instances exécutant crx3.

Après avoir exécuté le nettoyage des révisions sur les instances CRX3, vous devez exécuter la récupération de l’espace mémoire du magasin de données pour supprimer tous les objets blob non référencés dans le magasin de données. Pour obtenir des instructions, consultez la documentation sur la récupération de l’espace mémoire du magasin de données.

Mise à niveau du schéma de base de données si nécessaire upgrade-the-database-schema-if-needed

En règle générale, la pile Apache Oak sous-jacente utilisée par AEM pour la persistance s’occupe de la mise à niveau du schéma de base de données, si nécessaire.

Cependant, il peut arriver que le schéma ne puisse pas être mis à niveau automatiquement. Il s’agit principalement d’environnements de sécurité élevée dans lesquels la base de données s’exécute sous un utilisateur ou une utilisatrice avec des privilèges limités. Lorsqu’un tel scénario se produit, AEM continue à utiliser l’ancien schéma.

Pour éviter qu’un tel scénario ne se produise, mettez à niveau le schéma en procédant comme suit :

  1. Arrêtez l’instance AEM qui doit être mise à niveau.

  2. Mettez à niveau le schéma de la base de données. Consultez la documentation relative au type de base de données pour savoir quels outils sont nécessaires pour obtenir le résultat.

    Pour plus d’informations sur la façon dont Oak gère les mises à niveau des schémas, consultez cette page sur le site web d’Apache.

  3. Continuez la mise à niveau d’AEM.

Suppression des utilisateurs susceptibles d’entraver la mise à niveau delete-users-that-might-hinder-the-upgrade

NOTE
Cette tâche de maintenance avant la mise à niveau n’est nécessaire que si :
  • vous effectuez une mise à niveau à partir des versions d’AEM antérieures à AEM 6.3 ;
  • vous rencontrez les erreurs mentionnées ci-dessous lors de la mise à niveau.

Il existe des cas exceptionnels où les utilisateurs et utilisatrices du service peuvent se retrouver dans des versions AEM plus anciennes mal balisées en tant qu’utilisateurs ou utilisatrices standard.

Si un tel scénario se produit, la mise à niveau échoue avec un message similaire à celui-ci :

ERROR [Apache Sling Repository Startup Thread] com.adobe.granite.repository.impl.SlingRepositoryManager Exception in a SlingRepositoryInitializer, SlingRepository service registration aborted
java.lang.RuntimeException: Unable to create service user [communities-utility-reader]:java.lang.RuntimeException: Existing user communities-utility-reader is not a service user.

Pour contourner ce problème, procédez comme suit :

  1. Désolidarisez l’instance du trafic d’exploitation.

  2. Créez une sauvegarde d’un ou de plusieurs utilisateurs ou utilisatrices à l’origine du problème. Vous pouvez effectuer cette tâche à l’aide du gestionnaire de modules. Pour plus d’informations sur les packages, consultez la rubrique Utilisation des packages.

  3. Supprimez un ou plusieurs utilisateurs ou utilisatrices à l’origine du problème. Vous trouverez ci-dessous une liste d’utilisateurs qui peuvent appartenir à cette catégorie :

    1. dynamic-media-replication
    2. communities-ugc-writer
    3. communities-utility-reader
    4. communities-user-admin
    5. oauthservice
    6. sling-scripting

Rotation des fichiers journaux rotate-log-files

Nous vous recommande d’archiver vos fichiers journaux actuels avant de commencer la mise à niveau. Cela facilite la surveillance et l’analyse de vos fichiers journaux pendant et après la mise à niveau pour identifier et résoudre les problèmes qui peuvent surgir.

recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2