Home

Recommandations pour la gestion de vos sources de déploiement Vitam & VitamUI

Table des matières

Introduction
Prérequis
Installation initiale
Mise à jour des configurations
Montée de version
- Préparation du tronc commun
- Application sur les différents environnements
Annexes

Introduction

Ce document vise à vous accompagner dans la gestion de vos sources de déploiement Ansible pour Vitam et VitamUI, en s’appuyant sur un workflow Git classique (branche commune par version, puis merge vers les environnements). L’objectif est de vous permettre de :

Partir des sources livrées par le Programme Vitam.
Adapter ces sources à vos besoins spécifiques.
Répliquer ces adaptations pour chacun de vos environnements (production, préproduction, etc.).
Faciliter la montée de version et la maintenance.

Avec l'expérience acquise et les erreurs rencontrées, nous vous proposons quelques recommandations pour faciliter la gestion de vos sources de déploiement Ansible au fur et à mesures des versions.

Pour se faire, nous allons nous appuyer sur la puissance de Git afin de gérer l'ensemble des sources et leurs différences.

Dans ce document nous allons vous présenter comment partir des sources livrées, comment les adapter à votre besoin puis comment les répliquer pour chacun de vos environnements.

Hypothèses :

La convention de nommage utilisée dans la procédure correspond à : env-site = <production|preprod>-<primaire-secondaire>.
Vous utilisez Git et maîtrisez les commandes de base (clone, checkout, merge, commit, push).
Vous avez accès à un repository Git interne pour héberger vos adaptations.

Prérequis

Git installé sur votre poste de travail.
Accès en lecture au repository officiel : ProgrammeVitam/deployment.
Droits suffisants pour créer des branches et merger sur votre repository interne.

Architecture du Repository

Nous utilisons deux "remotes" (sources distantes) :

github : Le code source officiel du Programme Vitam (lecture seule).
origin : Votre repository interne (lecture/écriture).

Installation initiale

Ce chapitre est dédié à la première initialisation de vos différentes branches.

Cloner la version souhaitée

L’objectif est de récupérer la version de référence officielle du ProgrammeVitam sur GitHub (ex: 8.1.1) afin de la pousser vers votre repository interne.

# Cloner la version souhaitée depuis le repository officiel
git clone -o github https://github.com/ProgrammeVitam/deployment.git --branch 8.1.1
cd deployment/

# Ajouter votre repository interne
git remote add origin https://my-personal-repo/deployment.git

# Créer une branche pour les adaptations du tronc commun
git checkout -b common-8.1.1

# Pousser la branche vers votre repository interne
git push --set-upstream origin common-8.1.1

Résultat : Votre repository interne contient désormais une branche common-8.1.1, qui servira de tronc commun pour tous vos environnements.

Adapter les sources communes

À partir de cette branche, vous pouvez appliquer les spécificités communes à tous vos environnements (ex: configuration des repositories, variables globales).

# S'assurer de bien être sur le tronc commun
git checkout common-8.1.1

# Appliquer et commiter les modifications communes
git add .
git commit -m "Adaptations initiales sur le tronc commun"

# Pousser les nouvelles modifications
git push

Où intervenir ?

Principalement dans le répertoire environments/.
Si vous devez modifier des fichiers en dehors de environments/, remontez ces adaptations au support Vitam pour qu’elles soient intégrées et supportées dans les prochaines versions.

Exemple de modifications :

Configuration des repositories dans environments/group_vars/all/main/repositories.yml.
Surcharge des variables par défaut (vaults, extra-vars).

Conseil :

Commitez régulièrement pour tracer vos adaptations.
Conservez les fichiers .example ou .plain sans les modifier pour suivre les évolutions entre versions.

Préparation d'un environnement

Pour chaque environnement (preprod-primaire, preprod-secondaire, etc.), créez une branche dédiée à partir du tronc commun.

# Récupération du tronc common
git checkout common-8.1.1

# Création de la branche dédiée à l'environnement cible
git checkout -b preprod-primaire-8.1.1

Dans cette branche, appliquez les spécificités de l’environnement :

Préparation de l’inventaire (ex. environments/hosts.<env>-<site>) dédié.
Personnalisation des jvm_opts et d'autres variables spécifiques à l'environnement.
Surcharge des vaults (conservez les exemples pour référence) mais remplacer ceux livrés par les votres.
Génération de la PKI.
Création des host_vars à l'aide du playbook ansible-vitam-exploitation/generate_hostvars_for_2_network_interfaces.yml.

# Commiter les modifications
git add .
git commit -m "Adaptations custom environnement preprod-primaire-8.1.1"

# Commiter d'autres modifications
git add .
Poursuite des adaptations custom environnement preprod-primaire-8.1.1

# Pousser cette nouvelle branche sur votre repository interne
git push --set-upstream origin preprod-primaire-8.1.1

Mise à jour des configurations

Une fois que la préparation de vos sources ansible est terminée, vous allez pouvoir effectuer vos premiers tests de déploiement et itérer ainsi au fur et à mesure des adaptations que vous allez avoir besoin d'appliquer toujours en appliquant le workflow de mise à jour suivant.

Workflow de mise à jour:

Appliquer les modifications communes dans la branche principale (common-8.1.1).
Commiter et pousser ces modifications.
Merger ces modifications vers les branches des environnements.
Appliquer les adaptations spécifiques à chaque environnement si nécessaire.

Exemple :

# 1. Se placer sur la branche principale
git checkout common-8.1.1

# 2. Appliquer et commiter les modifications communes
git add .
git commit -m "Nouvelles adaptations sur le tronc commun"

# 2.bis. Appliquer d'autres modifications communes
git commit -m "Encore de nouvelles modifications sur le tronc commun"

# 3. Pousser les modifications sur le repository interne
git push

# 4. Appliquer les modifications communes vers un environnement
git checkout preprod-primaire-8.1.1
git merge origin/common-8.1.1

# 5. Résoudre les éventuels conflits, puis commiter et pousser la branche mise à jour
git add .
git commit -m "Nouvelles adaptations custom environnement preprod-primaire-8.1.1"
git push

Montée de version

Ce chapitre est dédié au rapatriement des sources de déploiement d'une nouvelle release Vitam.

Préparation du tronc commun

Lors de la livraison d’une nouvelle version (ex: 9.1.0), rapatriez-la depuis le repository officiel et mergez vos adaptations.

# À partir de votre tronc commun actuel
git checkout common-8.1.1

# Créer un nouveau tronc commun pour la nouvelle version
git checkout -b common-9.1.0

# Ajouter le repository officiel (si ce n'est pas déjà fait)
git remote add github https://github.com/ProgrammeVitam/deployment.git

# Rapatrier la nouvelle version et résolvez les conflits si besoin
git fetch github
git merge github/9.1.0

# Pusher la nouvelle branche sur votre repository interne
git push --set-upstream origin common-9.1.0

Application sur les différents environnements

Une fois le tronc commun mis à jour, appliquez ces modifications à chaque environnement.

# Cloner la branche de l'environnement actuel
git checkout preprod-primaire-8.1.1

# Créer une branche pour la nouvelle version
git checkout -b preprod-primaire-9.1.0

# Merger les modifications du tronc commun et résolvez les conflits éventuels
git merge origin/9.1.0

# Appliquer les modifications customes relatives à l'environnement
git add .
git commit -m "Adaptations custom environnement preprod-primaire-9.1.0"

# Pousser la branche de la nouvelle version de votre environnement
git push --set-upstream origin preprod-primaire-9.1.0

Conseil :

Cette étape devrait être simple et rapide vu que les principaux travaux ont étés fait sur le tronc commun.
Vérifiez et corrigez les éventuels conflits résiduels.

Annexes

Annexes en lien avec la procédure précédente.

Bonnes pratiques

Nommage des branches : Utilisez un format clair : <env>-<site>-<version> (ex: preprod-primaire-8.1.1).
Commits :
- Messages clairs et explicites.
- Commits atomiques (une modification = un commit).
Merge :
- Privilégiez les merges réguliers depuis le tronc commun vers les environnements.
- Évitez les merges "géants" pour faciliter la résolution des conflits.
Sécurité :
- Ne conservez pas vos fichiers vault_pass.txt ou vault_pki.pass sous Git.

Schéma du workflow Git

Vous retrouvez ici le schema retraçant le suivi des modifications au sein des différentes versions tel que décrit dans ce document (main correspondant du repository officiel du ProgrammeVitam sur GitHub).

gitGraph
   %% -- RELEASE 8.1.1 --
   commit id: "8.1.1 (GitHub)" tag: "8.1.1"
   branch "common-8.1.1"
   checkout "common-8.1.1"
   commit id: "Adaptations initiales sur le tronc commun"
   commit id: "Poursuite des adaptations communes"
   commit id: "D'autres modifications communes"

   branch "preprod-primaire-8.1.1"
   commit id: "Adaptations custom environnement preprod-primaire-8.1.1"
   commit id: "Poursuite des adaptations custom environnement preprod-primaire-8.1.1"

   checkout "common-8.1.1"
   branch "production-primaire-8.1.1"
   commit id: "Adaptations custom environnement production-primaire-8.1.1"
   commit id: "Poursuite des adaptations custom environnement production-primaire-8.1.1"

   checkout "common-8.1.1"
   commit id: "Nouvelles adaptations sur le tronc commun"
   commit id: "Encore de nouvelles modifications sur le tronc commun"

   checkout "preprod-primaire-8.1.1"
   merge "common-8.1.1" id: "Merge branch common-8.1.1 into branch preprod-primaire-8.1.1"
   commit id: "Nouvelles adaptations custom environnement preprod-primaire-8.1.1"

   checkout "production-primaire-8.1.1"
   merge "common-8.1.1" id: "Merge branch common-8.1.1 into branch production-primaire-8.1.1"
   commit id: "Nouvelles adaptations custom environnement production-primaire-8.1.1"

   %% -- RELEASE 9.1.0 --
   checkout main
   commit id: "9.1.0 (GitHub)" tag: "9.1.0"

   branch "common-9.1.0"
   merge "common-8.1.1" id: "Portage des adaptations communes sur la nouvelle release"
   commit id: "Adaptations initiales sur le tronc commun de la nouvelle release"
   commit id: "Poursuite des adaptations communes à la nouvelle release"

   checkout "preprod-primaire-8.1.1"
   branch "preprod-primaire-9.1.0"
   merge "common-9.1.0" id: "Merge branch common-9.1.0 into branch preprod-primaire-9.1.0"
   commit id: "Adaptations custom environnement preprod-primaire-9.1.0"

   checkout "production-primaire-8.1.1"
   branch "production-primaire-9.1.0"
   merge "common-9.1.0" id: "Merge branch common-9.1.0 into branch production-primaire-9.1.0"
   commit id: "Adaptations custom environnement production-primaire-9.1.0"

Exemple de résolution de conflits

Résolution des conflits :

Git vous indiquera les fichiers en conflit.
Utilisez git status pour les lister.
Ouvrez chaque fichier, recherchez les marqueurs <<<<<<<, =======, >>>>>>>.
Conservez les adaptations nécessaires et supprimez les marqueurs.
Validez avec git add <fichier> puis git commit.

Supposons un conflit dans environments/group_vars/all/vault.yml :

<<<<<<< HEAD
vault_password: "mon_mot_de_passe_interne"
=======
vault_password: "mot_de_passe_officiel"
>>>>>>> github/9.1.0

Résolution :

Conserver votre mot de passe interne.
Supprimer les marqueurs de conflit.

vault_password: "mon_mot_de_passe_interne"

Puis :

git add environments/group_vars/all/main/vault.yml
git commit -m "Résolution conflit vault.yml pour la version 9.1.0"

Glossaire

Tronc commun : Branche principale (common-8.1.1, common-9.1.0) contenant les sources de référence et les adaptations communes poussées sur le repository interne.
Merge : Fusion de deux branches Git.
Push : Action de pousser une branche sur un repository Git.
Vault : Fichier Ansible chiffré contenant des secrets.
repository interne : Un repository Git interne (ex: GitLab, Gitea, Bitbucket) pour stocker vos branches de déploiement personnalisées.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly