Notes et procédures spécifiques V10.0
#####################################

.. caution:: Veuillez appliquer les procédures spécifiques à chacune des versions précédentes en fonction de la version de départ selon la suite suivante: V8.1 -> V9.0 -> V9.1 -> V10.0

Adaptation des sources de déploiement ansible
=============================================

Mise à jour de la pile Elastic vers 9.4.9 (US #17109)
----------------------------------------------------

Kibana passe de 9.3.2 à 9.4.9 pour corriger la vulnérabilité Brotli du runtime
Node.js embarqué (CVE-2026-111497, ESA-2026-232). Cette distribution embarque
Node.js 24.22.1 ; ne pas remplacer ce runtime séparément.
Elasticsearch, son plugin ``analysis-icu``, Logstash et Filebeat sont alignés
sur 9.4.9. Les paquets DEB/RPM, les images conteneurs, les valeurs Ansible par
défaut et les serveurs Elasticsearch de développement et de CI sont concernés.
Les artefacts Elasticsearch/ICU 8.19.8 nécessaires aux migrations depuis les
anciennes versions sont conservés.

Les clients Java Elasticsearch restent en 9.3.2 : ils sont compatibles avec un
serveur de version mineure supérieure dans la même version majeure, conformément
à la `politique de compatibilité du client Java
<https://github.com/elastic/elasticsearch-java#compatibility>`_. Cela ne dispense
pas de qualifier les recherches et l'indexation de Vitam.

Préparation
~~~~~~~~~~~

Avant la montée de version, pour chaque environnement :

* Recenser les versions réellement exécutées, les références et empreintes des
  artefacts, les plugins et les éventuelles surcharges ``elasticsearch.version``,
  ``kibana.version``, ``logstash.version`` et ``filebeat.version``. Adapter ces
  surcharges à la cible ; elles prennent le pas sur les valeurs par défaut.
* Distinguer les clusters logs et données et leurs instances Kibana. Kibana-data
  passe par ``elastic-kibana-interceptor`` ; ce chemin doit être testé séparément.
* Lire les changements incompatibles et les problèmes connus de chaque composant
  entre la version de départ et la cible. Vérifier notamment les usages ILM,
  TSDB, les modèles d'index et les plugins personnalisés. Prévoir au moins 2 Go
  de mémoire par instance Kibana, selon la recommandation Elastic depuis 9.4.
* Publier les paquets, le plugin ICU et les images 9.4.9 dans les dépôts utilisés
  par l'environnement avant de lancer le déploiement. Les images Elasticsearch,
  Kibana et Logstash sont récupérées depuis ``docker.elastic.co`` par la CI,
  puis publiées sous les noms habituels ``vitam-external/<composant>:9.4.9``.
  Autoriser l'accès au registre Elastic depuis les machines de build et de
  développement ; les images de déploiement restent servies par le registre interne.
* Suspendre les écritures, les traitements et les accès selon la procédure de
  migration applicable. Réaliser et vérifier des snapshots cohérents des deux
  clusters Elasticsearch, y compris l'état fonctionnel Kibana pour ses objets
  sauvegardés. Conserver également les exports des objets Kibana, les configurations,
  les clés de chiffrement et les artefacts de la version de départ. Un export
  des tableaux de bord seul ne constitue pas une sauvegarde complète de Kibana.

Déploiement et qualification
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mettre à jour Elasticsearch avant Kibana : Kibana 9.4 ne doit pas démarrer sur
Elasticsearch 9.3. Le master playbook ``ansible-vitam/vitam.yml`` respecte cet
ordre pour les usages logs et données. En déploiement sélectif, terminer et
contrôler la mise à jour du cluster concerné et du plugin ICU avant celle de
Kibana, puis terminer l'alignement de Logstash et Filebeat. Maintenir les Jobs
Vitam arrêtés jusqu'à la fin de la post-migration, comme indiqué ci-dessous.

En qualification, exécuter une installation neuve et une montée de version sur
un environnement représentatif, pour les modes de déploiement utilisés :

* Contrôler la version de chaque nœud Elasticsearch, la santé des deux clusters
  et la version du plugin ICU. Vérifier l'indexation, les recherches et les
  analyseurs utilisés par Vitam.
* Contrôler la version de Kibana et du Node.js fourni par le paquet ou l'image
  réellement installé. Vérifier ``/status`` et l'absence d'erreurs de migration
  des objets sauvegardés pour Kibana-log et Kibana-data.
* Vérifier les imports des tableaux de bord, leurs objets liés et l'index par
  défaut. Tester la consultation des logs, les recherches sur les données via
  l'intercepteur, ainsi que les parcours Vitam/Vitam UI et connecteurs utilisés.
* Vérifier que Filebeat et Logstash acheminent de nouveaux événements jusqu'à
  Elasticsearch et que ceux-ci sont consultables dans Kibana.
* Répéter une restauration de la sauvegarde de départ en qualification. Joindre
  au ticket les versions observées, MR, résultats CI, preuves de ces contrôles
  et liste des environnements restant à traiter avant clôture.

Restauration
~~~~~~~~~~~~

En cas d'échec, arrêter les composants mis à jour et les écritures. Reconstituer
un environnement de la version de départ avec ses configurations, plugins et
clés, puis restaurer les snapshots pris avant la migration et vérifier la
cohérence avec les autres données Vitam avant de rouvrir les accès.

.. caution::
   Une rétrogradation des binaires ne restaure pas les index ni les objets
   sauvegardés migrés. Ne pas ouvrir les répertoires de données mis à jour avec
   une ancienne version d'Elasticsearch. Les écritures postérieures au snapshot
   ne sont pas récupérées par cette restauration ; prévoir leur reprise avant
   de rétablir le service.

Références : `avis de sécurité Elastic ESA-2026-232
<https://discuss.elastic.co/t/kibana-8-19-24-9-4-9-9-5-6-security-update-esa-2026-232/391369>`_,
`compatibilité et ordre d'installation
<https://www.elastic.co/docs/deploy-manage/deploy/self-managed/install-kibana>`_,
`notes Kibana <https://www.elastic.co/docs/release-notes/kibana>`_ et
`notes Elasticsearch <https://www.elastic.co/docs/release-notes/elasticsearch>`_.

Réorganisation du stockage workspace par tenant et seuils de saturation
------------------------------------------------------------------------

Le composant ``workspace-collect`` persiste les objets binaires sous un répertoire propre à chaque tenant. Cette organisation permet de renforcer des quotas de stockage et de refuser les versements du module de collecte lorsque le stockage approche de la saturation. Le composant ``workspace`` conserve son organisation historique.

.. caution::
   Avant toute migration depuis une version de Vitam V9.1- (V9.1 ou inférieure) vers une version V10.0+ (V10.0 ou supérieure), assurez-vous préalablement que le module de collecte ne contienne aucune transaction active.
   Seules les transactions versées avec succès (``ACK_OK``), versées avec avertissement(s) (``ACK_WARNING``) ou abandonnées (``ABORTED``), et dont la purge des données a été réalisée, peuvent être migrées sans risque.
   Les transactions ouvertes en édition (``OPEN``), en cours de validation (``READY``), validées (``VALIDATED``), en cours d'envoi (``SENDING``), envoyées et en cours de traitement par le SAE (``SENT``), rejetées par le SAE (``ACK_KO``) ou en erreur technique (``KO``) peuvent contenir des binaires et doivent être finalisées (versées et acquittées par Vitam, ou abandonnées) avant la migration, sans quoi ces transactions seront corrompues et ne pourront plus être ni reprises ni purgées.

   Il convient de :

   - finaliser toutes les transactions sur l'ensemble des tenants (verser et attendre l'acquittement en succès ou avec avertissement(s), ou abandonner) ;
   - attendre la purge des binaires (délai pouvant atteindre 2 heures) ;
   - vérifier sur le serveur ``workspace-collect`` que le répertoire de stockage ``/vitam/data/workspace-collect/`` ne contient plus aucun binaire.

La configuration des seuils pour le module de collecte et les précautions d'usage des quotas de versement sont décrites dans la documentation d'exploitation, au chapitre :ref:`workspace_storage_thresholds`.

Validation de la chaîne de confiance des certificats TSA
---------------------------------------------------------

Le composant worker peut désormais valider la chaîne de confiance des certificats TSA utilisés lors de la vérification des preuves d'horodatage. Cette validation est **désactivée par défaut** ; aucune action n'est requise lors de la montée de version si vous ne souhaitez pas l'activer.

Pour activer cette validation, positionner la variable suivante (par exemple dans le bloc ``worker`` du fichier ``environments/group_vars/all/advanced/vitam_vars.yml``) :

.. code-block:: yaml

    vitam:
      worker:
        timestamp_truststore_enabled: true

..

Avant le déploiement, déposez ensuite les certificats TSA de confiance dans le répertoire ``environments/certs/timestamping/trusted``, sous forme de fichiers portant l'extension ``.crt`` (encodés indifféremment en DER ou en PEM), puis exécutez :

.. code-block:: bash

    ./generate_stores.sh

..

.. caution:: Le répertoire ``environments/certs/timestamping/trusted`` doit contenir l'ensemble des certificats TSA utilisés au fil du temps : les certificats actuellement en service, mais également les anciens certificats si des renouvellements ont eu lieu. Les preuves d'horodatage déjà produites ont été signées avec les anciens certificats ; leur vérification échouerait si ceux-ci étaient absents du truststore.

Cette commande génère le fichier ``environments/keystores/timestamping/truststore_timestamping.p12`` en utilisant le mot de passe ``truststores.timestamping`` défini dans ``environments/group_vars/all/main/vault-keystores.yml``.

Lorsque la validation est activée, le déploiement du composant worker échoue en l'absence de ce truststore. Après le déploiement, une preuve d'horodatage dont le certificat TSA ne peut pas être rattaché à l'un des certificats de confiance est rejetée lors de sa vérification.

.. TODO : À intégrer dans la procédure de montée de version V10.0 (étape « Lancement du master playbook vitam »).

Gestion du démarrage des Jobs Vitam lors d'une montée de version
----------------------------------------------------------------

Les `Jobs Vitam` sont démarrés automatiquement à la fin du master playbook ``ansible-vitam/vitam.yml``. Ce démarrage est désormais conditionné par l'extra var ``prevent_scheduling_start``, positionnée à ``false`` par défaut.

Lors d'une montée de version, il **faut impérativement** passer ``prevent_scheduling_start=true`` au lancement du master playbook, afin que les `Jobs Vitam` ne se relancent pas alors que la post-migration n'est pas terminée :

.. code-block:: bash

    ansible-playbook -i environments/<inventaire> ansible-vitam/vitam.yml --ask-vault-pass -e prevent_scheduling_start=true

..

Une fois les procédures de post-migration finalisées, les `Jobs Vitam` devront être démarrés explicitement via le playbook d'exploitation :

.. code-block:: bash

    ansible-playbook -i environments/<inventaire> ansible-vitam-exploitation/start_vitam_scheduling.yml --ask-vault-pass

..
