# Déployer Data Asso sur Kubernetes

Le [lot 22446](../work-items/22446-helm-postgresql.md) fournit un [chart Helm](../../delivery/helm/data-asso/Chart.yaml), des [valeurs par cible](../../delivery/environments/) et une [commande manuelle pour une branche](../../delivery/scripts/deploy-branch.ts). Voir la [fiche des ressources CI/CD](../work-items/22443-ressources-ci-cd.md) pour l’identité du runner, les paramètres du cluster et les preuves externes à obtenir.

| Cible | Namespace | Périmètre |
| --- | --- | --- |
| Branche | `data-asso-v3-<slug>`, au plus 55 caractères | Recette isolée et commande manuelle. L’opérateur attribue un nom stable et distinct à chaque branche, avec suffixe stable en cas de troncature. |
| Intégration | `data-asso-v3-main` | Livraison automatique après le scan du même pipeline de `main`, une fois l’intégration activée et provisionnée. |
| Production | `data-asso-v3-prod` | Paramètres de rendu. Les hôtes, l’issuer, la classe d’Ingress, l’identité et le déclenchement Maintainer seront qualifiés dans [#22449](https://projets.synaltic.fr/issues/22449). |

Chaque namespace reçoit ses services, identités, références de Secrets et stockage propres. Sous `dev.synaltic.app`, les hôtes sont `<namespace>.dev.synaltic.app` (Next.js), `docs-<namespace>.dev.synaltic.app` (documentation) et `portail-<namespace>.dev.synaltic.app` (portail). Traefik route chaque origine vers un Service `ClusterIP` sur `/`. L’annotation `cert-manager.io/cluster-issuer: letsencrypt-prod` demande un certificat distinct par Ingress. Les paramètres dev restent à vérifier avec les contrôles de recette.

## Préparer la recette d’intégration

Le job `Deploy:Main` s’exécute sur `cluster-dev` pour un push sur la branche canonique protégée `main` lorsque la publication d’images et la livraison d’intégration sont activées. Sa dépendance obligatoire à `Scan:Images` du même pipeline lui transmet l’archive du scan réussi. L’entrée d’intégration lit uniquement `.ci-delivery/reports/delivery-manifest.json` et vérifie la cible, le commit, le pipeline, les quatre références par digest et les origines compilées avant toute mutation Kubernetes. Le job compare également le commit du checkout à celui du pipeline. Le job réussi conserve pendant trente jours, selon l’expiration configurée, la copie exacte du manifeste utilisé. [Manifeste admis pour la recette d’intégration](../work-items/22445-images-scans-versionnement.md#manifeste-admis-pour-la-recette-dintégration)

### Préparer les écarts Data Asso

Reprendre les preuves LCA documentées dans [#22443](../work-items/22443-ressources-ci-cd.md) pour les usages déjà observés des runners et les conventions de stockage, d’Ingress, de certificat et de RoleBinding. LCA utilise déjà PostgreSQL 18, `csi-cinder-high-speed` et `ReadWriteOnce`. Data Asso reprend le compte PostgreSQL partagé par le serveur et ses clients. Le volume Data Asso est de 20Gi, monté sur `/var/lib/postgresql`. LCA utilise 40Gi sur `/var/lib/postgresql/data` avec un `PGDATA` explicite. Les preuves LCA et les validations locales Helm et Node sont réutilisées à hauteur de ce qu’elles démontrent. [Vérifications déjà réalisées](../work-items/22446-helm-postgresql.md#vérifications-et-preuves)

- **Cible et accès.** L’exploitation préprovisionne `data-asso-v3-main` avec le label `dataasso.synaltic.app/environment=main` et son Secret PostgreSQL partagé. Le job de livraison matérialise le Secret de pull Harbor. Helm et kubectl utilisent la configuration Kubernetes fournie au job `cluster-dev`. À défaut de contexte utilisable, le job crée un kubeconfig temporaire qui référence le jeton et la CA déjà montés par le runner. Il utilise l’IP du service Kubernetes fournie par l’environnement ou résout `kubernetes.default.svc` en IP. Les deux clients vérifient TLS avec la CA montée. Le journal relève le seul nom d’utilisateur retourné par `kubectl auth whoami` si l’API le permet. Contrôler avec `kubectl auth can-i` les droits effectifs requis pour le namespace nommé, les ressources et Secrets de release Helm, les opérations `get`, `create` et `patch` sur le Secret de pull, le PVC, les ConfigMaps de verrou et de provenance, les Jobs, les pods et leurs journaux. Confirmer les refus d’écriture hors cible et de suppression des namespaces et PV. Si le RoleBinding `developers-superdev-binding` est installé, vérifier le sujet `developers`, le ClusterRole `superdev` et les droits cumulés d’un membre réel dans le namespace.
- **Frontière GitLab.** Le Maintainer vérifie la ref protégée, les acteurs et droits de déclenchement ou de relance, les autres refs protégées, les protections héritées et les politiques. Examiner les surcharges pouvant agir sur la sélection, le checkout, le contexte ou l’image. Attester que les jobs de contribution, de build et des autres cibles sont hors de la portée de l’identité Kubernetes de livraison, y compris lorsqu’ils utilisent `cluster-dev`. Le tag de runner sert à choisir un exécuteur. Le réglage GitLab global reste celui du projet. [Sécurité des pipelines sur branches protégées](https://docs.gitlab.com/ci/pipelines/#pipeline-security-on-protected-branches) · [Priorité des variables GitLab](https://docs.gitlab.com/ci/variables/#ci-cd-variable-precedence)
- **Base et compte PostgreSQL.** Utiliser l’image officielle PostgreSQL 18 par digest, dans la famille de `postgres:18.0` utilisée par LCA. Sur PVC vierge, l’image initialise la base et le compte de `secrets.postgres`. PostgreSQL, le Job de migration, le Job WALDEC et Next utilisent exactement la même référence. Sur un PVC préparé, rapprocher le volume du témoin de provenance (UID du namespace, pipeline, empreinte du manifeste) et vérifier que le compte existant correspond au Secret et dispose des droits requis par la migration. Un PVC existant sans témoin est refusé. Garder `DATAASSO_MAIN_DEPLOYMENT` désactivé jusqu’à la vérification des accès et du compte partagé.

### Activer et vérifier

Le Maintainer et l’exploitation renseignent les paramètres suivants dans les réglages protégés avant un push autorisé de `main`.

| Entrée | Portée et valeur |
| --- | --- |
| `DATAASSO_IMAGE_PUBLICATION` | Paramètre de projet évalué à la création du pipeline, `enabled` pour produire et scanner les images. |
| `DATAASSO_MAIN_DEPLOYMENT` | Paramètre distinct de projet évalué à la création, `enabled` pour inclure la livraison automatique de `main`. Utiliser le scope `*` pour les deux paramètres évalués dans les règles. |
| `DATAASSO_MAIN_RUNTIME_VALUES_FILE` | Scope `data-asso-v3-main`, type fichier. JSON au [format runtime commun](#renseigner-les-valeurs-runtime), avec préfixe Harbor des images admises, image PostgreSQL 18 par digest, classe de stockage, nom du Secret de pull et référence du Secret PostgreSQL préprovisionné. Le JSON contient les références de Secrets. |

Le job utilise `node:24.22.2-bookworm` et installe Helm 3.22.1 et kubectl 1.35.2 pour Linux amd64. Il vérifie les empreintes des archives officielles avant extraction dans un répertoire temporaire. Helm 3.22 prend en charge Kubernetes 1.35. [Compatibilité Helm 3](https://v3.helm.sh/docs/v3/topics/version_skew/) · [Archives Kubernetes 1.35.2](https://github.com/kubernetes/kubernetes/blob/v1.35.2/CHANGELOG/CHANGELOG-1.35.md#downloads-for-v1352)

### Préparer le Secret de pull Harbor

Le Maintainer conserve la variable fichier protégée `DATAASSO_HARBOR_PULL_AUTH_FILE` déjà utilisée par `Scan:Images` et rend la même valeur disponible à `Deploy:Main`. Vérifier les noms d’environnement et les accès effectifs avant de passer sa portée à `data-asso-v3-main*` ou à une portée équivalente. Les noms actuels sont `data-asso-v3-main/scan` et `data-asso-v3-main`. Le motif couvre également `data-asso-v3-main/build`. Le build utilise sa propre variable de publication. Les deux robots existants disposent de pull et push. [Contrat des variables d’images](../work-items/22445-images-scans-versionnement.md#conditions-dactivation-intégration)

Le job utilise l’entrée Docker de l’hôte du préfixe Harbor validé contre le manifeste. Sous le verrou et après enregistrement de la provenance, il crée le Secret de type `kubernetes.io/dockerconfigjson` nommé dans `secrets.imagePull`, par exemple `data-asso-harbor-pull`, distinct de `pg-secret`. Si cet objet porte déjà le label `dataasso.synaltic.app/pull-secret-owner=deploy-main` et le type attendu, le job actualise uniquement `.dockerconfigjson` avec préconditions d’UID et de version. La création passe par stdin. Pour la mise à jour, le job transmet le chemin d’un fichier temporaire privé (`0600`) à un appel direct et borné de kubectl, puis supprime le fichier dès la fin de l’appel. Un objet existant non géré par ce job bloque la livraison et reste en place. Le journal `harbor-pull-secret-ready` consigne seulement le nom du Secret avant Helm.

### Consigner les preuves de recette

Rassembler ces preuves avec les identifiants du pipeline et de la tentative `ci-<CI_JOB_ID>`. Réutiliser les résultats déjà acquis sur la configuration retenue et compléter les écarts suivants.

1. **Images et accès HTTP.** Rapprocher le build, le scan réussi et le déploiement du même pipeline de `main`. Comparer les quatre digests du manifeste admis avec les images réellement tirées par les workloads, les origines Docusaurus avec celles du chart et le SHA-256 du manifeste avec l’empreinte du témoin. Pour les trois hôtes propres à l’intégration, relever la résolution DNS, le routage Traefik vers les Services, l’émission cert-manager par `letsencrypt-prod` et le nom et la chaîne du certificat réellement servi en HTTPS.
2. **Base, données et isolation.** Confirmer le quota applicable et relever la liaison et le montage effectifs du PVC de 20Gi sur `/var/lib/postgresql`, classe `csi-cinder-high-speed`, en `ReadWriteOnce`. Dans la recette isolée, relire la même donnée témoin et retrouver le même PVC après un redéploiement puis après la recréation du pod PostgreSQL. Vérifier le parcours réseau depuis les clients autorisés et son isolation vis-à-vis des autres namespaces. Conserver la preuve isolée pour les opérations de remplacement et confirmer le volume réellement monté sur `main`.
3. **Compte et ordre des traitements.** Sur la base de recette, relever la disponibilité PostgreSQL, puis la réussite de `migrate:deploy` et la fin des pods du Job de migration avant le démarrage du Job WALDEC. Relever le résultat `applied` ou `unchanged` et le SHA-256 du snapshot, puis le marqueur `ready` de Next et la disponibilité des trois applications. Vérifier l’usage du même compte PostgreSQL dans les trois workloads clients. Les sondes `pg_isready` constatent la disponibilité du serveur. Les connexions et opérations des workloads apportent la preuve d’accès à la base. Conserver les identités et statuts sans afficher les URI de connexion ni les valeurs des Secrets.
4. **Échecs et reprise.** Réutiliser les preuves locales et toute preuve isolée déjà recueillie sur l’arrêt des étapes dépendantes, les attentes bornées et les diagnostics distincts de base inaccessible, de schéma absent et de WALDEC non publié. Compléter en environnement jetable les preuves isolées encore manquantes. Le `resource_group` sérialise les jobs GitLab. Si le résultat d’une livraison est incertain, conserver le verrou Kubernetes et réconcilier les opérations et leur provenance avant relance. [Diagnostic Next](nextjs.md#diagnostiquer-la-disponibilité) · [Réconcilier un échec](#réconcilier-un-échec)

Le parcours d’intégration utilise `delivery/scripts/deploy-main.ts` dans GitLab. Les commandes de préparation, de diagnostic et de nettoyage de branche ci-dessous s’appliquent aux namespaces jetables. `deploy-branch.ts` refuse les namespaces permanents.

## Préparer une branche

L’opérateur préprovisionne le namespace jetable avec le label `dataasso.synaltic.app/environment=branch`. Depuis `cluster-dev`, établir l’identité effective avec `kubectl --context "$C" auth whoami` ou SelfSubjectReview, puis contrôler ses droits avec `kubectl --context "$C" auth can-i <verbe> <ressource> -n "$N"`. Prévoir la lecture du namespace cible par nom, les droits Helm sur ses ressources et ses métadonnées de release (Secrets), les Jobs, `get` et `list` sur les pods et la lecture de `pods/log`. Prévoir la création, la lecture et la suppression du ConfigMap de verrou, ainsi que la lecture, la création et la mise à jour du ConfigMap de provenance. Le contrôle de reprise demande aussi la lecture du PVC PostgreSQL. Une recette avec accès direct au pod ou vérification du volume requiert aussi les droits de lecture et sous-ressources correspondants. L’identité de branche doit être cantonnée à sa cible. Contrôler les refus sur les namespaces permanents, les PV et la suppression de namespaces via `auth can-i`. L’opérateur lit les paramètres cluster-scope et peut provisionner le RoleBinding facultatif `developers-superdev-binding` dans les namespaces autorisés. Vérifier le sujet `developers`, le ClusterRole `superdev` et les droits cumulés avec un vrai membre du groupe.

Préparer les quatre images `linux/amd64` conformément au [contrat #22445](../work-items/22445-images-scans-versionnement.md#manifeste-et-scan). Récupérer auprès du producteur autorisé la copie du manifeste admis archivée par le scan réussi et sa provenance. La cible du manifeste doit être le namespace de branche. Les paramètres compilés des deux images Docusaurus doivent correspondre aux hôtes ci-dessus, avec `SITE_BASE_URL=/` et `OTHER_SITE_URL` pointant vers l’autre origine avec slash final. Les valeurs locales du script ne démontrent pas la réussite du scan.

## Renseigner les valeurs runtime

Fournir un fichier JSON d’exploitation avec les noms de Secrets et de clés. Le même format sert à la recette manuelle, à la livraison de branche et au fichier de valeurs de `Deploy:Main`. Exemple avec des références fictives.

```json
{
  "harborRepository": "registry.example.invalid/dataasso",
  "postgresImage": "registry.example.invalid/library/postgres@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "storageClass": "csi-cinder-high-speed",
  "secrets": {
    "imagePull": "data-asso-harbor-pull",
    "postgres": {"name": "data-asso-db", "databaseKey": "database", "userKey": "user", "passwordKey": "password"}
  }
}
```

Préprovisionner le Secret PostgreSQL dans chaque namespace. Pour une branche, préprovisionner aussi le Secret de pull. Pour `main`, renseigner le nom que le job utilise pour [matérialiser le Secret de pull](#préparer-le-secret-de-pull-harbor). L’opérateur fournit le digest qualifié de PostgreSQL 18 et confirme la StorageClass, les quotas, l’architecture et la compatibilité du runtime. Les variables d’initialisation PostgreSQL s’appliquent au premier démarrage sur un volume vierge.

Pour actualiser un fichier préparé avec le format précédent, conserver la référence `secrets.postgres` du compte existant et retirer `secrets.jobs` et `secrets.nextjs`. Le script de livraison et le schéma Helm exigent les seules clés `imagePull` et `postgres` sous `secrets`. Sur un PVC conservé, les valeurs de cette référence doivent correspondre au compte déjà présent.

## Livrer et observer les traitements

Depuis la racine, utiliser Node 24, Helm 3 et un kubectl compatible avec le cluster. Fournir le même kubeconfig qualifié aux deux clients et le contexte explicitement à la commande. Choisir un identifiant de tentative neuf et stable pour le suivi.

```sh
node delivery/scripts/deploy-branch.ts \
  --context "$C" --namespace "$N" \
  --manifest /chemin/vers/delivery-manifest.json \
  --runtime-values /chemin/vers/runtime.json \
  --attempt recette-1
```

1. Le script contrôle les références par digest, le namespace, le label de branche et les origines compilées. Il valide les quatre rendus avant la première écriture, puis prend le verrou `data-asso-delivery-lock`. Le hash du manifeste, le commit source et les identifiants du pipeline et du job sont journalisés. Sous ce verrou, le script contrôle les ressources encore présentes et le ConfigMap `data-asso-delivery-provenance`. Il refuse un pipeline plus ancien, un hash différent pour le même pipeline et une claim présente sans témoin. Le script confirme l’écriture du témoin avant d’engager PostgreSQL. Le témoin est indépendant des releases Helm, lié à l’UID du namespace et conservé lors d’un arrêt avec conservation de la base.
2. La release `data-asso-db` attend PostgreSQL sur `postgres:5432`. Son StatefulSet garde la claim `data-data-asso-postgres-0` de 20Gi en `ReadWriteOnce`. L’image PostgreSQL 18 stocke ses fichiers sous `/var/lib/postgresql/18/docker`; le volume est monté sur `/var/lib/postgresql`. La NetworkPolicy d’entrée permet TCP/5432 aux pods clients étiquetés dans le même namespace. Son effet dépend du CNI et des autres politiques en place. Les identités autorisées à créer des pods dans ce namespace peuvent attribuer ces labels.
3. Le Job `data-asso-migrate-<tentative>` exécute `migrate:deploy`. Après `Complete=True`, la terminaison des pods du même UID de Job et la confirmation d’un pod réussi, le Job `data-asso-waldec-<tentative>` synchronise le [snapshot qualifié](waldec.md#synchroniser-dans-docker) inclus dans l’image data-jobs avec son SHA-256. L’attente du client est bornée à 330 s par Job et chaque Job a une échéance active de 300 s, `backoffLimit: 0` et `restartPolicy: Never`. Le script attend aussi la terminaison des pods WALDEC. Il lit les logs du seul pod réussi, dont le conteneur `data-jobs` a terminé avec un code zéro, puis vérifie de nouveau son UID et son propriétaire. Il journalise l’UID du pod, l’empreinte, le statut `applied` ou `unchanged` et l’identifiant de tentative. Un résultat absent ou ambigu bloque la livraison. L’état des Jobs et leurs journaux restent disponibles.
4. La release `data-asso-web` attend les trois applications. Next publie sa readiness après lecture effective du référentiel, alors que la liveness suit uniquement le serveur HTTP. Chaque attente Helm est configurée à 5 min et la commande est bornée à 330 s. Contrôler séparément la disponibilité HTTPS et l’émission des certificats. Lors d’une mise à jour, une version HTTP antérieure peut continuer de répondre pendant la préparation des données. Évaluer la compatibilité de toute future migration avec cette version avant livraison.

Lire les états et les journaux avec les identifiants de tentative exacts.

```sh
kubectl --context "$C" -n "$N" get sts,deploy,job,pod,pvc,ingress
kubectl --context "$C" -n "$N" get job data-asso-waldec-recette-1 -o yaml
kubectl --context "$C" -n "$N" get pods -l "batch.kubernetes.io/controller-uid=$JOB_UID" -o wide
kubectl --context "$C" -n "$N" logs pod/"$POD_REUSSI" -c data-jobs
kubectl --context "$C" -n "$N" describe pod <pod-next>
```

Renseigner `JOB_UID` à partir du Job et utiliser le nom exact du pod confirmé dans le journal. Sur un cluster ancien, reprendre la clé `controller-uid` si c’est celle indiquée dans le sélecteur du Job. Pour une tentative en échec, lire les logs du pod concerné après contrôle de son propriétaire.

Pour Next, contrôler le marqueur `data-waldec-readiness` sur `/waldec?q=000000` avec un port-forward vers le pod si le Service n’a pas d’endpoint prêt. `database_unavailable` indique un problème de connexion, `schema_incomplete` un schéma absent ou incomplet et `waldec_not_loaded` une publication absente. Voir les [autres codes Next](nextjs.md#diagnostiquer-la-disponibilité). Un HTTP 200 peut accompagner un diagnostic d’indisponibilité. Une erreur de pull, un PVC en attente ou l’absence de certificat ont leurs propres états dans les ressources Kubernetes.

## Réconcilier un échec

L’écriture des valeurs, les quatre rendus Helm et la première lecture du namespace précèdent toute mutation Kubernetes. Le journal indique l’étape et, pour une erreur de client, une catégorie sans reproduire sa sortie. Corriger l’échec puis relancer la livraison autorisée. À partir de la tentative de création du verrou, le diagnostic inclut la consigne de réconciliation ci-dessous.

Une erreur, une interruption ou un retour de mutation incertain arrête le script. Laisser le verrou jusqu’à la fin de la réconciliation. Relire l’UID du namespace, le verrou (UID, `resourceVersion`, tentative, empreinte), le témoin de provenance, les deux releases et les Jobs et pods nommés. Si l’écriture du témoin a donné un résultat incertain, comparer sa provenance à celle du verrou et établir si la phase DB a commencé. Si la création ou la mise à jour du Secret de pull a un résultat incertain sur `main`, relever son nom, son type, son label de gestion et son `resourceVersion` et rapprocher ces éléments du journal et du verrou avant reprise. Un Job peut poursuivre son exécution après la fin du client. Confirmer la fin du processus de livraison et des pods de traitements, y compris ceux en terminaison. Éviter la suppression forcée des pods et le retrait des finalizers pour provoquer une progression. Si un nœud est isolé et que l’arrêt d’un traitement reste incertain, établir son arrêt effectif avant toute reprise. Si une création est incertaine, chercher le nom exact du Job et examiner son UID, ses conditions, son image et ses logs. Relire `migrate:status` via une opération ponctuelle distincte si nécessaire et l’[état durable WALDEC](waldec.md#résultats-et-reprise) pour le SHA et l’issue de la tentative. Résoudre l’état `pending-*` d’une release et les opérations non terminées avant toute nouvelle mutation.

Après une réconciliation documentée, l’opérateur peut libérer le verrou via un DELETE conditionné à l’UID et à la `resourceVersion` relus. Placer les préconditions dans un JSON `{"apiVersion":"v1","kind":"DeleteOptions","preconditions":{"uid":"…","resourceVersion":"…"}}` et envoyer son contenu avec `kubectl --context "$C" delete --raw "/api/v1/namespaces/$N/configmaps/data-asso-delivery-lock" -f -`. Relire en cas de réponse perdue. Un UID différent appartient à une autre opération. Reprendre avec un identifiant neuf et le même manifeste admis ou un manifeste plus récent approuvé. Une publication déjà appliquée peut donner `unchanged`. Les journaux du runner et les Jobs conservés permettent de rapprocher les preuves.

## Préparer la base des diagnostics sur une branche vierge

Cette préparation correspond aux étapes 5 et 6 de la recette. Utiliser une cible jetable préprovisionnée avec ses références runtime. La préparation crée le témoin avant le premier PostgreSQL, puis conserve la même claim jusqu’à la livraison officielle. Les essais de migration et d’empreinte utilisent `prepa-1`. La livraison officielle utilise `recette-1`.

Dans une session Bash dédiée qui utilise le stockage Helm standard en Secrets, définir `C`, `N`, `MANIFEST` (chemin de la copie admise exacte) et `RUNTIME` (chemin du JSON d’exploitation). Exécuter les blocs dans l’ordre depuis la racine du dépôt. Les commandes utilisent `jq`, `sha256sum` et Python avec PyYAML, déjà employé pour les vérifications Helm. L’identité opérateur doit aussi pouvoir lister les releases, les ressources de livraison et créer, supprimer et joindre le pod de diagnostic dans la seule cible de recette. Les seules données d’exploitation lues ici sont les noms de Secrets et de clés. En cas d’échec d’une commande ou d’un contrôle, arrêter la séquence et [réconcilier l’opération](#réconcilier-un-échec) avant de continuer.

### Réserver la cible et confirmer sa provenance

```bash
set -euo pipefail
: "${C:?contexte requis}" "${N:?namespace requis}" "${MANIFEST:?manifeste admis requis}" "${RUNTIME:?valeurs runtime requises}"
[[ $N =~ ^data-asso-v3-[a-z0-9]([a-z0-9-]*[a-z0-9])?$ && ${#N} -le 55 ]]
[[ $N != data-asso-v3-main && $N != data-asso-v3-prod ]]
prep=prepa-1
official=recette-1
scratch=$(mktemp -d)
cp -- "$MANIFEST" "$scratch/manifest.json"
cp -- "$RUNTIME" "$scratch/runtime.json"
sum=$(sha256sum "$scratch/manifest.json")
manifest_sha=${sum%% *}
k() { kubectl --context "$C" -n "$N" --request-timeout 10s "$@"; }
h() ( unset "${!HELM_KUBE@}"; export HELM_DRIVER=secret; helm "$@"; )
ns_uid() {
  k get namespace "$N" -o json | jq -er --arg ns "$N" '
    .metadata | select(.name == $ns and .deletionTimestamp == null
      and .labels["dataasso.synaltic.app/environment"] == "branch")
    | .uid | strings | select(length > 0)'
}

jq -e --arg ns "$N" --arg attempt "$prep" --arg hash "$manifest_sha" --slurpfile runtime "$scratch/runtime.json" '
  . as $manifest | $runtime[0] as $r
  | "https://docs-\($ns).dev.synaltic.app" as $docs
  | "https://portail-\($ns).dev.synaltic.app" as $portal
  | ["data-jobs", "developer-portal", "documentation", "nextjs"] as $units
  | if ($r | keys) == ["harborRepository", "postgresImage", "secrets", "storageClass"]
      and $manifest.schemaVersion == 1 and $manifest.target == $ns and $manifest.platform == "linux/amd64"
      and ($manifest.commit | test("^[a-f0-9]{40}$"))
      and ([$manifest.pipelineId, $manifest.buildJobId] | all(test("^[1-9][0-9]*$")))
      and ($r.harborRepository | test("^[a-z0-9][a-z0-9.-]*(:[0-9]+)?/[a-z0-9][a-z0-9._-]*$"))
      and ($manifest.images | keys) == $units
      and all($units[]; . as $unit | $manifest.images[$unit]
        | .repository == ($r.harborRepository + "/" + $unit)
          and (.digest | test("^sha256:[a-f0-9]{64}$"))
          and .reference == (.repository + "@" + .digest))
      and ($manifest.images.documentation.parameters
        | .SITE_URL == $docs and .OTHER_SITE_URL == ($portal + "/") and .SITE_BASE_URL == "/")
      and ($manifest.images["developer-portal"].parameters
        | .SITE_URL == $portal and .OTHER_SITE_URL == ($docs + "/") and .SITE_BASE_URL == "/")
    then {namespace: $ns, attempt: $attempt,
      provenance: {commit, pipelineId, buildJobId, manifestSha256: $hash},
      images: ((.images | map_values(.reference)) + {postgres: $r.postgresImage}),
      secrets: $r.secrets, storage: {className: $r.storageClass}}
    else error("manifeste incompatible avec la recette") end
' "$scratch/manifest.json" > "$scratch/values.json"

chart=delivery/helm/data-asso
values=(--namespace "$N" -f delivery/environments/branch.yaml -f "$scratch/values.json")
for phase in database migrate waldec applications; do
  h template "$phase" "$chart" "${values[@]}" --set-string "phase=$phase" > "$scratch/$phase.yaml"
done

namespace_uid=$(ns_uid)
jq -c --arg uid "$namespace_uid" '.provenance + {namespaceUid: $uid, attempt}' \
  "$scratch/values.json" > "$scratch/provenance.json"
configmap() {
  jq -n --arg ns "$N" --arg name "$1" --slurpfile data "$scratch/provenance.json" '
    {apiVersion: "v1", kind: "ConfigMap", metadata: {name: $name, namespace: $ns}, data: $data[0]}'
}
confirm() {
  jq -e --arg ns "$N" --arg name "$1" --slurpfile expected "$scratch/provenance.json" '
    .metadata.name == $name and .metadata.namespace == $ns
    and (.metadata.uid | strings | length > 0)
    and (.metadata.resourceVersion | strings | length > 0)
    and .metadata.deletionTimestamp == null and .data == $expected[0]' "$2" > /dev/null
}
lock=data-asso-delivery-lock
witness=data-asso-delivery-provenance
configmap "$lock" | k create -f - -o json > "$scratch/lock.json"
confirm "$lock" "$scratch/lock.json"
[[ $(ns_uid) == "$namespace_uid" ]]

# Seules les ressources de livraison doivent être absentes. Les Secrets sont déjà provisionnés.
resources=$(k get statefulsets,deployments,jobs,pods,persistentvolumeclaims -o name)
releases=$(h list --kube-context "$C" -n "$N" --all -q)
existing_witness=$(k get configmap "$witness" --ignore-not-found -o name)
[[ -z $resources && -z $releases && -z $existing_witness ]]
configmap "$witness" | k create -f - -o json > "$scratch/witness-created.json"
confirm "$witness" "$scratch/witness-created.json"
k get configmap "$witness" -o json > "$scratch/witness.json"
confirm "$witness" "$scratch/witness.json"
jq -e --slurpfile created "$scratch/witness-created.json" '
  .metadata.uid == $created[0].metadata.uid' "$scratch/witness.json" > /dev/null
```

Conserver le verrou pour tous les essais suivants. Les fichiers d’identité dans `scratch` et la provenance permettent de relire les objets en cas de réponse incertaine. Une création incertaine du verrou ou du témoin suspend les essais avant PostgreSQL. Relire le nom, l’UID, la version de ressource et toutes les données attendues, et établir l’état du namespace et des opérations. En cas de conflit avec un objet existant, transmettre le diagnostic à son propriétaire.

### Observer les diagnostics et l’échec WALDEC

Définir cette fonction avant le lancement des Jobs. Elle attend une condition terminale du Job et la terminaison des pods du même UID et retourne le nom du seul pod dont le conteneur `data-jobs` a l’issue demandée. Conserver le verrou si la borne est atteinte, si le Job est remplacé ou si la preuve est ambiguë.

```bash
job_pods() {
  local job=$1 wanted=$2 creation=$3 job_doc job_uid selector pod_list pod_name start=$SECONDS
  job_doc=$(cat "$creation") || return 1
  job_uid=$(jq -er --arg job "$job" '.metadata | select(.name == $job) | .uid | strings | select(length > 0)' <<< "$job_doc") || return 1
  selector=$(jq -er --arg uid "$job_uid" '
    .spec.selector.matchLabels | to_entries
    | map(select((.key == "batch.kubernetes.io/controller-uid" or .key == "controller-uid") and .value == $uid))
    | first | select(. != null) | "\(.key)=\(.value)"' <<< "$job_doc") || return 1
  while (( SECONDS - start < 330 )); do
    job_doc=$(k get job "$job" -o json) || return 1
    [[ $(jq -er '.metadata.uid' <<< "$job_doc") == "$job_uid" ]] || return 1
    if ! jq -e --arg wanted "$wanted" 'any(.status.conditions[]?;
      .status == "True" and .type == (if $wanted == "Succeeded" then "Complete" else "Failed" end))' \
      <<< "$job_doc" > /dev/null; then
      sleep 2
      continue
    fi
    pod_list=$(k get pods -l "$selector" -o json) || return 1
    if jq -e --arg job "$job" --arg uid "$job_uid" '
      (.items | length > 0) and all(.items[];
        any(.metadata.ownerReferences[]?; .controller == true and .apiVersion == "batch/v1" and .kind == "Job" and .name == $job and .uid == $uid)
        and (.status.phase == "Succeeded" or .status.phase == "Failed")
        and .status.reason != "NodeLost"
        and ([.status.containerStatuses[]? | select(.state.running != null)] | length == 0)
        and (.metadata.deletionTimestamp == null or any(.status.containerStatuses[]?;
          .name == "data-jobs" and .state.terminated != null)))' <<< "$pod_list" > /dev/null; then
      pod_name=$(jq -er --arg wanted "$wanted" '
        [.items[] | select(.status.phase == $wanted and any(.status.containerStatuses[]?;
          .name == "data-jobs" and .state.terminated.exitCode == (if $wanted == "Succeeded" then 0 else 2 end)))]
        | select(length == 1) | .[0].metadata.name' <<< "$pod_list") || return 1
      (( SECONDS - start < 330 )) || return 1
      printf '%s\n' "$pod_name"
      return
    fi
    sleep 2
  done
  return 1
}
```

Créer un pod de diagnostic à partir du template Next. Il garde les labels d’accès à PostgreSQL et retire le label `app.kubernetes.io/component` utilisé par le Service Next. Exécuter les commandes du bloc une à une. Pour le port-forward, utiliser un deuxième terminal avec les mêmes `C` et `N`.

```bash
python3 - "$scratch/applications.yaml" "$N" <<'PY' | k create -f -
import json
from pathlib import Path
import sys
import yaml

source, namespace = sys.argv[1:]
deployment, = [doc for doc in yaml.safe_load_all(Path(source).read_text())
               if doc and doc['kind'] == 'Deployment' and doc['metadata']['name'] == 'data-asso-nextjs']
template = deployment['spec']['template']
labels = dict(template['metadata']['labels'])
labels.pop('app.kubernetes.io/component')
print(json.dumps({'apiVersion': 'v1', 'kind': 'Pod',
                  'metadata': {'name': 'data-asso-next-diagnostic', 'namespace': namespace, 'labels': labels},
                  'spec': template['spec']}))
PY
# Deuxième terminal : kubectl --context "$C" -n "$N" port-forward pod/data-asso-next-diagnostic 13000:3000
readiness() {
  local result
  result=$(curl --fail --max-time 10 'http://127.0.0.1:13000/waldec?q=000000' \
    | grep -o 'data-waldec-readiness="[a-z_]*"') || return 1
  [[ $result == "data-waldec-readiness=\"$1\"" ]] || return 1
  printf '%s\n' "$result"
}
readiness database_unavailable

h upgrade --install data-asso-db "$chart" --kube-context "$C" \
  "${values[@]}" --set-string phase=database --wait --timeout 5m
k get pvc data-data-asso-postgres-0 -o json | jq -er '.metadata.uid' > "$scratch/pvc-uid"
readiness schema_incomplete

k create -f "$scratch/migrate.yaml" -o json > "$scratch/migrate-created.json"
job_pods data-asso-migrate-prepa-1 Succeeded "$scratch/migrate-created.json"
readiness waldec_not_loaded

python3 - "$scratch/waldec.yaml" <<'PY' | k create -f - -o json > "$scratch/waldec-created.json"
import json
from pathlib import Path
import sys
import yaml

job = yaml.safe_load(Path(sys.argv[1]).read_text())
args = job['spec']['template']['spec']['containers'][0]['args']
args[args.index('--sha256') + 1] = '0' * 64
print(json.dumps(job))
PY
```

Lire le JSON du pod WALDEC dont le conteneur a renvoyé le code 2 et vérifier l’absence de publication via le pod de diagnostic. Puis arrêter le port-forward et supprimer le seul pod de diagnostic, en attendant sa disparition.

```bash
failed_pod=$(job_pods data-asso-waldec-prepa-1 Failed "$scratch/waldec-created.json")
k logs "pod/$failed_pod" -c data-jobs | tee "$scratch/waldec-failed.json" \
  | jq -e '.status == "failed" and .expectedSha256 == ("0" * 64)
    and .sha256 == "cd58f33f78dfa4a000a856c8b01412e9d41c7bbfc676b0ffbc2151223d8448bd"
    and .uncertain != true'
readiness waldec_not_loaded
# Arrêter le port-forward du deuxième terminal avant la suppression.
k delete pod data-asso-next-diagnostic --wait=true --timeout=90s
```

### Libérer le verrou et livrer sur la même base

Vérifier la terminaison des deux Jobs et de leurs pods, l’arrêt du port-forward et l’absence d’autre opération sous le verrou. Confirmer que `data-asso-db` est déployée et qu’aucune release web n’existe. Le StatefulSet, le PVC, les Jobs et le témoin restent présents. Relire les objets si une commande a donné un résultat incertain et conserver le verrou jusqu’à la réconciliation.

```bash
job_pods data-asso-migrate-prepa-1 Succeeded "$scratch/migrate-created.json"
job_pods data-asso-waldec-prepa-1 Failed "$scratch/waldec-created.json"
[[ $(ns_uid) == "$namespace_uid" ]]
h list --kube-context "$C" -n "$N" --all -o json | jq -e '
  length == 1 and .[0].name == "data-asso-db" and .[0].status == "deployed"' > /dev/null
[[ $(k get pvc data-data-asso-postgres-0 -o json | jq -er '.metadata.uid') == "$(cat "$scratch/pvc-uid")" ]]
k get configmap "$witness" -o json > "$scratch/witness-current.json"
confirm "$witness" "$scratch/witness-current.json"
k get configmap "$lock" -o json > "$scratch/lock-current.json"
confirm "$lock" "$scratch/lock-current.json"
jq -e --slurpfile initial "$scratch/witness.json" '
  .metadata.uid == $initial[0].metadata.uid' "$scratch/witness-current.json" > /dev/null
jq -e --slurpfile initial "$scratch/lock.json" '
  .metadata.uid == $initial[0].metadata.uid' "$scratch/lock-current.json" > /dev/null
jq '{apiVersion: "v1", kind: "DeleteOptions", preconditions: (.metadata | {uid, resourceVersion})}' \
  "$scratch/lock-current.json" | k delete --raw "/api/v1/namespaces/$N/configmaps/$lock" -f -

node delivery/scripts/deploy-branch.ts --context "$C" --namespace "$N" \
  --manifest "$scratch/manifest.json" --runtime-values "$scratch/runtime.json" --attempt "$official"
[[ $(k get pvc data-data-asso-postgres-0 -o json | jq -er '.metadata.uid') == "$(cat "$scratch/pvc-uid")" ]]
```

Si la réponse à la suppression du verrou est perdue, relire le nom et l’UID. Lancer la livraison officielle uniquement après avoir établi que l’opération de préparation est terminée et que son verrou a disparu. En présence d’un verrou d’UID différent, laisser son propriétaire poursuivre. Le script officiel relit le témoin du même namespace et les annotations du StatefulSet et des Jobs de préparation. Les deux côtés utilisent les octets exacts du manifeste et donc le même hash. Conserver les journaux et vérifier que les Jobs officiels terminent dans l’ordre avant l’ouverture HTTP.

## Vérifier la recette isolée

- Vérifier le DNS des trois hôtes, la classe Traefik, l’état `Ready` de l’issuer et des certificats, la chaîne et le SNI avec `openssl s_client -verify_hostname <hôte> -verify_return_error` et l’HTTP avec `curl --fail https://<hôte>/`. Relever les canoniques et liens croisés des deux sites.
- Relever les références demandées et les images effectivement tirées sous l’identité du workload. Comparer la création des Jobs, leur état `Complete`, la terminaison de leurs pods et l’UID du pod ayant produit la sortie WALDEC, puis la mise à disposition HTTP. La [préparation des diagnostics](#préparer-la-base-des-diagnostics-sur-une-branche-vierge) établit les trois états Next et l’échec d’empreinte avant la livraison officielle sur la même base.
- Contrôler la connexion à PostgreSQL depuis Next et le refus TCP depuis un pod témoin dans un autre namespace, avec un contrôle de connexion positif. Relever `Bound`, le montage, `SHOW data_directory`, l’UID du PVC/PV et un témoin SQL synthétique. Comparer le témoin et l’empreinte WALDEC publiée après redéploiement puis après recréation du seul pod PostgreSQL de la branche. Le pod recréé a un nouvel UID et la claim garde le sien.

## Nettoyer une branche jetable

Vérifier le contexte, l’UID et le label de la branche. Prendre le même verrou d’exclusion avant tout nettoyage, attendre la fin des Jobs et exporter les preuves. Désinstaller d’abord `data-asso-web` puis `data-asso-db` dans le namespace explicite. Le PVC du StatefulSet et le ConfigMap `data-asso-delivery-provenance` restent présents après la désinstallation. Conserver le témoin, y compris si aucun Job n’a été lancé. Vérifier sa présence et son pipeline avant de libérer le verrou. Une claim sans témoin bloque la prochaine livraison. Garder le même nom et la même classe au redéploiement. Un changement de classe de stockage ou de version majeure PostgreSQL exige une opération dédiée.

Pour une remise à zéro explicitement autorisée, contrôler la `reclaimPolicy`, l’UID de la claim `data-data-asso-postgres-0` et l’absence de pod qui la monte. L’opérateur habilité peut alors supprimer cette seule claim et les Jobs exacts après export des preuves. La suppression de la claim peut supprimer le volume physique selon la politique de classe. Sous le même verrou, confirmer la disparition de la claim, des workloads, des releases et des Jobs de cette branche, ainsi que l’issue attendue du volume, avant de supprimer le ConfigMap de provenance avec ses préconditions UID et `resourceVersion`. Cette dernière suppression remet à zéro le seuil de livraison. Si elle reste incertaine, relire l’objet et le verrou avant toute suite. L’identité de livraison n’a besoin d’aucun droit de suppression de PVC. Le cycle de vie des namespaces relève de l’opérateur cluster. Les digests Harbor et les environnements permanents restent hors de la procédure. Sauvegarde et restauration relèvent de [#22441](https://projets.synaltic.fr/issues/22441).
