docs(adr) — stockage objet MinIO : qui déclare quoi, et qui détient quoi

Trois questions indépendantes, tranchées lors du branchement de Kadans sur
MinIO (2026-07-26) : qui déclare les buckets d'une app, qui détient les
identifiants capables de les créer, et comment l'app lit les siens.

La décision de fond est du fondateur : CHACUN SON PÉRIMÈTRE. Une application
déclare ses buckets depuis son propre dépôt ; `tools` fournit le serveur, un
module de standardisation et un compte de provisionnement — pas la liste. Une
première version faisait tout porter par l'infra partagée : à ce rythme, chaque
bucket de chaque app devenait une PR sur le dépôt commun.

L'ADR consigne aussi les trois identités et leurs portées (root / provisionneur
/ compte de service), pourquoi la lecture des identifiants est une propriété
inconditionnelle de la plateforme plutôt qu'une déclaration par app, et pourquoi
les octets ne transitent pas par l'API — avec les conséquences que ça impose
(endpoint public, CORS aux origines exactes, pas de basic-auth sur l'ingress S3).

Les alternatives écartées sont listées avec leur motif, dont deux que j'avais
moi-même proposées et qui étaient plus faibles.

Deux limites assumées y figurent : le provisionneur est un secret PARTAGÉ entre
rôles CI (sa compromission permet de créer des buckets, pas de lire des objets),
et les noms d'actions d'administration MinIO n'ont pas été éprouvés contre le
serveur au moment d'écrire.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01CoafGWmRVESaWX819USUUA

ansible/arcodange/factory/playbooks/03_cicd.yml

@@ -64,7 +64,8 @@
                   # Where to store the registration result.
                   file: .runner
                   # Execute how many tasks concurrently at the same time.
-                  capacity: 2
+                  # 1 seul job à la fois : les hôtes (8 Go, control-plane k3s sur pi1) ne survivent pas à 2 builds lourds simultanés.
+                  capacity: 1
                   # Extra environment variables to run jobs.
                   envs:
                     A_TEST_ENV_NAME_1: a_test_env_value_1
@@ -117,7 +118,9 @@
                   # Whether to use privileged mode or not when launching task containers (privileged mode is required for Docker-in-Docker).
                   privileged: false
                   # And other options to be used when the container is started (eg, --add-host=my.gitea.url:host-gateway).
-                  options:
+                  # Plafonds durs : un build ne doit jamais pouvoir affamer l'hôte (incident 2026-07-23 :
+                  # nuxt generate à 3,5 Go RSS sur pi1 → load 150, ingress+API k3s morts → gitea.arcodange.lab injoignable).
+                  options: "--memory=3g --memory-swap=3g --cpus=2 --pids-limit=512"
                   # The parent directory of a job's working directory.
                   # NOTE: There is no need to add the first '/' of the path as act_runner will add it automatically. 
                   # If the path starts with '/', the '/' will be trimmed.

argocd/templates/apps.yaml

@@ -24,6 +24,14 @@ spec:
   destination:
     server: https://kubernetes.default.svc
     namespace: {{ $ns }}
+  {{- /* Champs à exclure du diff (ex: /spec/volumeName d'un PVC rebindé à la
+         main après le drill coupure de courant — immuable côté API). À coupler
+         avec la syncOption RespectIgnoreDifferences=true pour que l'apply
+         réinjecte la valeur live au lieu de tenter de la vider. */}}
+  {{- with $app_attr.ignoreDifferences }}
+  ignoreDifferences:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
   syncPolicy:
     {{- if $app_attr.syncPolicy }}
     {{- toYaml $app_attr.syncPolicy | nindent 4 }}
@@ -34,6 +42,9 @@ spec:
     {{- end }}
     syncOptions:
       - CreateNamespace=true
+      {{- range $app_attr.syncOptions }}
+      - {{ . }}
+      {{- end }}
 {{- /*
   Non-prod environments (ADR-0002 elision rule): one extra Application per env
   under `<app_attr>.envs`. Each renders the SAME repo + chart, overlaid with

argocd/values.yaml

@@ -4,6 +4,15 @@
 gitea_applications:
   url-shortener:
     annotations: {}
+    # Le PVC live a un spec.volumeName épinglé (rebind du volume Longhorn) que
+    # le chart ne déclare pas : sans ceci, chaque sync tente de le vider et
+    # l'API le refuse (spec immuable) → SyncError permanent.
+    ignoreDifferences:
+      - kind: PersistentVolumeClaim
+        jsonPointers:
+          - /spec/volumeName
+    syncOptions:
+      - RespectIgnoreDifferences=true
   tools:
     annotations: {}
     syncPolicy:
@@ -51,6 +60,14 @@ gitea_applications:
     annotations:
       argocd-image-updater.argoproj.io/image-list: kadans-jobs=gitea.arcodange.lab/arcodange/kadans-jobs:latest
       argocd-image-updater.argoproj.io/kadans-jobs.update-strategy: digest
+  kadans-api:
+    org: arcodange
+    # L'API cœur partage le stack Vault/DB « kadans » (VaultAuth, creds Postgres,
+    # policy KV) : elle vit donc dans le namespace de l'app front qu'elle sert.
+    namespace: kadans
+    annotations:
+      argocd-image-updater.argoproj.io/image-list: kadans-api=gitea.arcodange.lab/arcodange/kadans-api:latest
+      argocd-image-updater.argoproj.io/kadans-api.update-strategy: digest
 
 argocd_image_updater_chart_values:
   config:

doc/adr/20260726-stockage-objet-minio.md

@@ -0,0 +1,111 @@
+[← ADRs](.) · [factory](../..) · **20260726 — stockage objet (MinIO) : qui déclare quoi**
+
+> **Cross-references** (bidirectionnel : chaque fichier listé doit citer cette ADR en tête)
+>
+> - **Infra partagée** (repo `arcodange-org/tools`) :
+>   [`minio/iac/modules/minio_app/`](https://gitea.arcodange.lab/arcodange-org/tools/src/branch/main/minio/iac/modules/minio_app) ·
+>   [`minio/iac/provisioner.tf`](https://gitea.arcodange.lab/arcodange-org/tools/src/branch/main/minio/iac/provisioner.tf) ·
+>   [`minio/values.yaml`](https://gitea.arcodange.lab/arcodange-org/tools/src/branch/main/minio/values.yaml) ·
+>   [`hashicorp-vault/iac/modules/app_policy/main.tf`](https://gitea.arcodange.lab/arcodange-org/tools/src/branch/main/hashicorp-vault/iac/modules/app_policy/main.tf)
+> - **Premier consommateur** (repo `arcodange/kadans`) :
+>   [`iac/main.tf`](https://gitea.arcodange.lab/arcodange/kadans/src/branch/main/iac/main.tf)
+> - **API consommatrice** (repo `arcodange/kadans-api`) :
+>   [`stockage.go`](https://gitea.arcodange.lab/arcodange/kadans-api/src/branch/main/stockage.go) ·
+>   [`chart/values.yaml`](https://gitea.arcodange.lab/arcodange/kadans-api/src/branch/main/chart/values.yaml)
+> - **Related ADR** :
+>   [`04_tool_hashicorp_vault.md`](04_tool_hashicorp_vault.md) (rôles et politiques Vault) ·
+>   [`20260407-network-architecture.md`](20260407-network-architecture.md) (Cloudflare / Traefik / CrowdSec)
+
+# ADR 20260726 : stockage objet (MinIO) — qui déclare quoi, et qui détient quoi
+
+## Status
+
+Proposed
+
+## Context
+
+MinIO est déployé dans le namespace `tools` (chart officiel, standalone, volume Longhorn). Le premier consommateur est Kadans, qui doit téléverser des rendus vidéo depuis le navigateur pour qu'ils suivent l'utilisateur d'un appareil à l'autre.
+
+Trois questions se posaient, et elles sont indépendantes :
+
+1. **Qui déclare les buckets** d'une application ?
+2. **Qui détient les identifiants** capables de les créer ?
+3. **Comment l'application lit** les siens à l'exécution ?
+
+Une première version faisait tout porter par `tools` : une liste de consommateurs dans son Terraform, les buckets dans son chart. Elle a été rejetée — à ce rythme, chaque bucket de chaque application devient une PR sur l'infra partagée, et le dépôt commun devient le goulot de tout le monde.
+
+## Decision
+
+### 1. Chacun son périmètre
+
+**Une application déclare ses buckets depuis son propre dépôt.** `tools` fournit le serveur, un module de standardisation, et un compte de provisionnement — **pas la liste**.
+
+```hcl
+# iac/main.tf de l'application
+module "stockage" {
+  source    = "git::…/tools.git//minio/iac/modules/minio_app?depth=1&ref=main"
+  app       = "kadans"
+  buckets   = ["kadans-videos"]
+  providers = { minio = minio }
+}
+```
+
+Le module crée les buckets (privés), une politique bornée à ces buckets, un compte de service, et écrit ses clés dans `kvv2/minio/<app>`.
+
+### 2. Trois identités, trois portées
+
+| Identité | Peut | Ne peut pas | Qui la lit |
+|---|---|---|---|
+| **root** MinIO | tout | — | le seul pipeline `minio` (`kvv2/minio/config`) |
+| **provisionneur** | créer bucket, politique, compte de service | lire ou écrire un objet | le rôle **CI** de chaque app (`kvv2/minio/provisioner`) |
+| **compte de service** d'une app | lire/écrire dans **ses** buckets | tout le reste | le **pod** de l'app (`kvv2/minio/<app>`) |
+
+C'est la pièce qui rend le point 1 possible. Provisionner demande des droits d'administration ; confier le **root** aurait donné à chaque application la lecture des objets de **toutes** les autres. Le provisionneur, lui, peut créer des buckets — une nuisance si une app est compromise — mais **pas lire les vidéos d'une autre**.
+
+### 3. La lecture est une propriété de la plateforme
+
+Le module Vault central `app_policy` accorde à **toute** application la lecture de `kvv2/data/minio/<son nom>`, **inconditionnellement**.
+
+Pas de drapeau, pas de déclaration par app : le chemin porte le nom de l'application, donc la règle **ne peut jamais exposer que ses propres clés**. Une app qui ne stocke rien y lit un chemin qui n'existe pas — une règle inerte, pas un privilège.
+
+Conséquence pratique : déclarer un consommateur se fait à **un seul endroit**, son propre `iac/`. Rien à synchroniser, donc rien à oublier.
+
+### 4. Les octets ne passent pas par l'API
+
+L'application signe des **URL présignées** ; le navigateur téléverse **directement** vers MinIO. Faire transiter 50 à 200 Mo par un pod applicatif doublerait le transit et exposerait l'API à un seul gros fichier.
+
+Corollaires :
+
+- l'endpoint signé doit être **joignable par le navigateur**, donc **public** (`s3.arcodange.fr`) — une page servie en HTTPS ne peut pas téléverser vers `http://` (contenu mixte), et un TLD interne ne se résout pas hors du LAN ;
+- **CORS** liste les origines **exactes** de l'application, jamais `*` : une URL présignée qui fuiterait serait sinon rejouable depuis n'importe quel site ;
+- l'ingress public ne porte **pas** de basic-auth, contrairement aux autres : une requête S3 porte sa propre signature, et un défi HTTP Basic casserait un PUT présigné auquel le navigateur ne peut pas répondre.
+
+### 5. Un bucket par cycle de vie, pas par application
+
+Une application peut avoir plusieurs buckets. Deux contenus aux durées de vie différentes méritent deux politiques de purge — Kadans en aura deux (un rendu de travail à garder, un aperçu régénérable).
+
+Le compte de service est **par application** : ajouter un bucket ne crée aucune clé, le compte existant gagne l'accès.
+
+## Consequences
+
+- **Le dépôt `tools` n'est plus modifié** quand une application change ses buckets. C'était l'objet de la décision.
+- **Ordre de déploiement contraint** : le module doit exister sur `main` de `tools` avant qu'une application l'appelle (`?ref=main`), et le provisionneur doit exister avant le premier plan d'application.
+- **Le provisionneur est un secret partagé** entre les rôles CI. Sa compromission permet de créer des buckets et des comptes, pas de lire des objets. Si ce risque devient inacceptable, la suite est une identité de provisionnement **par application**, bornée par préfixe de bucket — MinIO ne le permet pas simplement aujourd'hui.
+- **Non vérifié à la rédaction** : les noms d'actions d'administration MinIO de la politique du provisionneur viennent de la documentation, pas d'un essai. Le premier `apply` les confirmera ou les corrigera.
+
+## Alternatives Considered
+
+| Option | Pourquoi non |
+|---|---|
+| `tools` détient la liste des consommateurs | Chaque bucket de chaque app devient une PR sur l'infra partagée — rejeté par le fondateur, et c'est le cœur de cette ADR |
+| Les buckets déclarés dans le chart de MinIO (`values.yaml`) | Même défaut : la déclaration vit chez l'infra, pas chez l'application |
+| Chaque app crée son compte de service avec le **root** | Le root lit et écrit tous les objets de toutes les apps : le distribuer à chaque rôle CI revient à ne plus avoir de cloisonnement |
+| Déclarer la lecture Vault par app (`kv_read_paths`) | Mécanisme réel, mais c'est la trappe pour lire un secret appartenant à une **autre** app (creds GCS de Longhorn pour l'ERP). Y ranger un motif standard le rend invisible et oblige à le redéclarer partout |
+| Un drapeau `object_storage = true` par app | Une déclaration de plus à tenir synchronisée avec le `iac/` de l'app — donc une à oublier. La règle inerte ne coûte rien |
+| Une identité de provisionnement par app | Souhaitable, mais MinIO ne borne pas simplement les actions d'administration par préfixe. À reconsidérer si le modèle de menace change |
+
+## Success Metrics
+
+- Ajouter une application consommatrice ne touche **aucun** fichier de `tools`.
+- Un compte de service compromis ne donne accès qu'aux objets qu'il gérait déjà.
+- Le root de MinIO n'apparaît dans aucune politique Vault en dehors du pipeline `minio`.

doc/adr/README.md

@@ -15,6 +15,7 @@
   - [x] gitea packages
 - [ ] devsecops tools
   - [x] [hashicorp vault](./04_tool_hashicorp_vault.md)
+  - [x] [stockage objet MinIO — qui déclare quoi](./20260726-stockage-objet-minio.md)
   - [ ] terrakube
   - [ ] prometheus/grafana
   - [ ] ansible AWX

doc/runbooks/new-web-app/07-argocd-register.md

@@ -39,6 +39,7 @@ Options supplémentaires :
 | Champ | Quand l'utiliser | Effet |
 |---|---|---|
 | `org: arcodange` | dépôt hors `arcodange-org` | change le `repoURL` (défaut `arcodange-org`) |
+| `namespace: <autre>` | **service compagnon** partageant le namespace d'une app existante | déploie hors du namespace `<app>` (défaut = nom de l'app) — voir [9. Service compagnon](09-service-compagnon.md) |
 | `syncPolicy: …` | contrôle manuel | surcharge la policy (défaut : `automated {prune, selfHeal}`) |
 
 ## Ce que ça génère
@@ -79,7 +80,7 @@ flowchart LR
 ## Notes / contraintes
 
 > [!IMPORTANT]
-> `path: chart` et `namespace: <app>` sont **déduits du nom**, pas configurables par entrée. C'est pourquoi le dossier doit s'appeler `chart/` ([étape 1](01-gitea-repo.md)) et le nom doit être cohérent partout ([conventions](conventions.md)).
+> `path: chart` est **fixe** (jamais configurable) : c'est pourquoi le dossier doit s'appeler `chart/` ([étape 1](01-gitea-repo.md)) et le nom doit être cohérent partout ([conventions](conventions.md)). Le `namespace` vaut **le nom de l'app par défaut**, mais se surcharge via `namespace:` — utilisé par les [services compagnons](09-service-compagnon.md) qui partagent le namespace d'une app existante.
 
 - Le chart `factory/argocd` est lui-même réconcilié par ArgoCD (app-of-apps racine) : committer `values.yaml` sur `main` suffit à faire apparaître/synchroniser la nouvelle `Application`. Pas de `kubectl apply` manuel.
 - `prune: true` + `selfHeal: true` : ArgoCD supprime ce qui n'est plus dans le chart et réécrase les dérives manuelles. En tenir compte avant tout `kubectl edit`.
@@ -88,4 +89,5 @@ flowchart LR
 
 - [4. Chart Helm](04-helm-chart.md) — le contenu déployé (le dossier `chart/`).
 - [6. Workflows CI](06-ci-workflows.md) — les annotations `argocd-image-updater` collaborent avec l'image poussée.
+- [9. Service compagnon](09-service-compagnon.md) — le champ `namespace:` pour déployer dans le namespace d'une app existante.
 - [8. Checklist](08-checklist.md) — vérifier que l'`Application` passe `Healthy`/`Synced`.

doc/runbooks/new-web-app/09-service-compagnon.md

@@ -0,0 +1,146 @@
+[Factory](../../../README.md) > [Doc](../../README.md) > [Runbooks](../README.md) > [Nouvelle application web](README.md) > **9. Service compagnon**
+
+# 9. Service compagnon (namespace partagé)
+
+> **Status:** ✅ Active
+> **Upstream:** [7. Enregistrement ArgoCD](07-argocd-register.md) (le champ `namespace:` utilisé ici)
+> **Related:** [Conventions de nommage](conventions.md) · [4. Chart Helm](04-helm-chart.md) · [2. Base de données](02-database.md) · [Checklist](08-checklist.md)
+
+---
+
+## Summary
+
+Tous les autres chapitres décrivent une app **autonome** : son dépôt, sa base, son stack Vault, son namespace, son ServiceAccount — tout porte le même nom `<app>`. Mais certains services ne sont pas une app à part entière : ce sont des **compagnons** d'une app existante. Une **API cœur** à côté de son front, une **façade d'analyse** qui sert une app — ils vivent dans le **même namespace** que l'app qu'ils servent et **réutilisent son identité** (Vault, base, ServiceAccount) plutôt que d'en provisionner une nouvelle.
+
+Ce chapitre décrit ce raccourci et son **piège principal** : la convention « tout est nommé `<app>` » ([conventions](conventions.md)) **ne tient plus** pour un compagnon — ses identités Vault/DB/SA restent celles de l'app **primaire**, pas les siennes.
+
+## Compagnon ou app autonome ?
+
+Fais un **compagnon** quand le service partage réellement l'identité et les données de l'app primaire. Fais une **app autonome** (chapitres 1→8) dès qu'il lui faut sa propre base ou ses propres accès.
+
+| Prends un compagnon si… | Prends une app autonome si… |
+|---|---|
+| Il lit/écrit **la base de l'app primaire** (même données) | Il lui faut **sa propre base** |
+| Il partage le cycle de vie de l'app (déployé avec, pour elle) | Il a un cycle de vie indépendant |
+| Une seule origine CORS / un seul domaine logique | Domaine et exposition propres |
+
+Un compagnon garde **son propre dépôt Gitea et son propre chart** (donc sa propre image, sa CI de build, son ingress). Ce qu'il **ne** refait pas : base, rôles Vault, ServiceAccount, namespace.
+
+## Les deux formes de compagnon
+
+### A. Compagnon sans état — juste le namespace partagé
+
+Le service n'a **ni base ni secret Vault** (ex. façade d'analyse `kadans-jobs`). Il suffit de le déployer dans le namespace de l'app primaire. Une seule chose le distingue d'une app normale à l'[étape 7](07-argocd-register.md) : la clé **`namespace:`**.
+
+```yaml
+# factory/argocd/values.yaml
+  kadans-jobs:
+    org: arcodange
+    namespace: kadans          # ← sinon ArgoCD déduirait « kadans-jobs »
+    annotations:
+      argocd-image-updater.argoproj.io/image-list: kadans-jobs=…/kadans-jobs:latest
+      argocd-image-updater.argoproj.io/kadans-jobs.update-strategy: digest
+```
+
+Son chart ne contient que `deployment` / `service` / `ingress`. **Pas d'`iac/`, rien dans `postgres/iac/terraform.tfvars`, pas de CRD Vault.**
+
+### B. Compagnon partageant le stack Vault/DB de l'app primaire
+
+Le service lit la **base de l'app primaire** avec **ses** creds dynamiques (ex. API cœur `kadans-api` sur la base `kadans`). Il réutilise, **à l'identique**, tout ce qui a été provisionné pour le primaire :
+
+| Ressource | Elle porte le nom du **primaire**, jamais du compagnon |
+|---|---|
+| Base PostgreSQL | `kadans` (pas `kadans-api`) |
+| Rôle DB dynamique Vault | `postgres/creds/kadans` |
+| Rôle d'auth K8s Vault | `kadans` (bound au SA `kadans` / ns `kadans`) |
+| Policy KV runtime | `kadans` (accès `kvv2/kadans/*`) |
+| ServiceAccount K8s | `kadans` (créé par le chart du **primaire**) |
+
+Donc le compagnon **ne fait PAS** l'[étape 2](02-database.md) (pas de nouvelle base), **PAS** l'[étape 5](05-app-terraform.md) (pas de nouvel `app_roles`, pas d'`iac/`), et **ne s'ajoute PAS** à la liste `applications` de `postgres` / `tools`. Son `VaultDynamicSecret` pointe simplement le mount/chemin du primaire :
+
+```yaml
+# chart du compagnon — vaultdynamicsecret.yaml
+spec:
+  mount: postgres
+  path: creds/kadans           # = le rôle DB du PRIMAIRE
+  vaultAuthRef: kadans         # cf. le VaultAuth ci-dessous
+```
+
+Le host DB reste **`pgbouncer.tools`**, base = celle du primaire ([étape 4](04-helm-chart.md) « via pgbouncer, jamais en direct »).
+
+> [!IMPORTANT]
+> **Le piège du VaultAuth manquant.** Le `VaultDynamicSecret` a besoin d'un CR **`VaultAuth`** dans le namespace (VSO le résout par nom, dans le même namespace). Deux cas :
+>
+> - **Le primaire consomme déjà Vault** → son chart a déjà posé un `VaultAuth` (nommé `auth` par convention, [étape 4](04-helm-chart.md)). Le compagnon **le référence** (`vaultAuthRef: auth`) et ne crée rien.
+> - **Le primaire ne consomme PAS Vault** (front statique, aucune base — cas de `kadans`) → **personne** n'a créé de `VaultAuth` dans le namespace. Le compagnon doit alors **poser le sien**, mais pointant le rôle et le SA du **primaire** :
+>
+> ```yaml
+> # chart du compagnon — vaultauth.yaml (cas « primaire sans Vault »)
+> apiVersion: secrets.hashicorp.com/v1beta1
+> kind: VaultAuth
+> metadata:
+>   name: kadans               # ou « auth » ; l'important est spec.kubernetes.*
+>   namespace: {{ .Release.Namespace }}
+> spec:
+>   # PAS de vaultConnectionRef → VSO retombe sur sa connexion globale (comme erp/webapp).
+>   method: kubernetes
+>   mount: kubernetes
+>   kubernetes:
+>     role: kadans             # ← rôle K8s Vault du PRIMAIRE
+>     serviceAccount: kadans   # ← SA du PRIMAIRE (créé par SON chart)
+>     audiences: [vault]
+> ```
+>
+> C'est la seule raison pour laquelle le SA et le rôle du VaultAuth ne portent **pas** le nom du service qui le déploie. Ne crée **pas** un second SA `kadans-api` : le rôle K8s Vault `kadans` n'accepte que le SA `kadans`.
+
+> [!WARNING]
+> **N'écris PAS `vaultConnectionRef: default` dans un namespace applicatif.** VSO résout `vaultConnectionRef` **dans le namespace du CR** — or la VaultConnection `default` n'existe que dans le namespace **`tools`**. La nommer explicitement ailleurs fait chercher `<ns>/default` (inexistant) : le `VaultDynamicSecret` reste bloqué sur `VaultConnection "default" not found`, le Secret n'est jamais matérialisé, et le pod tourne en `CreateContainerConfigError`. Les apps hors `tools` (erp, webapp) **omettent** ce champ et laissent VSO utiliser sa `defaultVaultConnection`. (crowdsec/plausible peuvent l'écrire car ils vivent **dans** `tools`.)
+
+## Carte
+
+```mermaid
+%%{init: {'theme': 'base'}}%%
+flowchart TB
+    classDef prim fill:#059669,stroke:#047857,color:#fff
+    classDef comp fill:#b45309,stroke:#92400e,color:#fff
+    classDef sh fill:#7c3aed,stroke:#6d28d9,color:#fff
+
+    subgraph NS["namespace « kadans »"]
+      SA["ServiceAccount kadans<br>(chart du PRIMAIRE)"]:::sh
+      VA["VaultAuth<br>role kadans · SA kadans"]:::sh
+      PRIM["Deployment kadans<br>(front, sans Vault)"]:::prim
+      COMP["Deployment kadans-api<br>(compagnon, lit la base)"]:::comp
+    end
+    VA -->|"vaultAuthRef"| VDS["VaultDynamicSecret<br>postgres/creds/kadans"]:::sh
+    COMP --> VA
+    VDS --> COMP
+    COMP --> PGB["pgbouncer.tools → base kadans"]:::sh
+    SA -.->|"identité empruntée"| VA
+```
+
+## Précédents vivants
+
+| Compagnon | Primaire | Partage | CRD Vault dans son chart |
+|---|---|---|---|
+| [`kadans-jobs`](https://gitea.arcodange.lab/arcodange/kadans-jobs) | `kadans` | namespace seul (sans état) | aucun |
+| [`kadans-api`](https://gitea.arcodange.lab/arcodange/kadans-api) | `kadans` | namespace + base + Vault | `vaultauth` (le primaire n'a pas de Vault) + `vaultdynamicsecret` |
+
+## Delta de checklist
+
+Par rapport à la [checklist standard](08-checklist.md), un compagnon **saute** :
+
+- ❌ [Étape 2](02-database.md) — pas de nouvelle base ni de rôle propriétaire.
+- ❌ [Étape 5](05-app-terraform.md) — pas d'`iac/`, pas d'`app_roles`, rien à ajouter aux listes `applications`.
+
+…et **ajuste** :
+
+- ✅ [Étape 4](04-helm-chart.md) — `VaultDynamicSecret` pointe `creds/<primaire>` ; poser un `vaultauth.yaml` **seulement** si le primaire ne consomme pas déjà Vault (rôle + SA = ceux du primaire).
+- ✅ [Étape 7](07-argocd-register.md) — ajouter `namespace: <primaire>` à l'entrée `gitea_applications`.
+- ✅ Ordre de merge : le fix/chart du compagnon **avant** son enregistrement ArgoCD, pour que la 1ʳᵉ synchro parte d'un chart correct.
+
+## Related
+
+- [7. Enregistrement ArgoCD](07-argocd-register.md) — le champ `namespace:` qui place le compagnon dans le namespace du primaire.
+- [4. Chart Helm](04-helm-chart.md) — la forme des CRD VSO et la connexion via `pgbouncer.tools`.
+- [Conventions de nommage](conventions.md) — la règle « tout est `<app>` » que ce chapitre nuance pour un compagnon.
+- [Référence VSO faisant autorité](https://gitea.arcodange.lab/arcodange-org/tools/src/branch/main/hashicorp-vault/iac/modules/README.md) — VaultConnection/VaultAuth/VaultDynamicSecret côté `tools`.

doc/runbooks/new-web-app/README.md

@@ -2,7 +2,7 @@
 
 # Mettre en service une nouvelle application web
 
-> **Last Updated:** 2026-07-12
+> **Last Updated:** 2026-07-24
 > **Status:** ✅ Procédure courante
 > **Related:** [Conventions de nommage](conventions.md) · [Checklist](08-checklist.md) · [ADR CI/CD](../../adr/03_cicd_gitea_action_argocd.md) · [ADR Vault](../../adr/04_tool_hashicorp_vault.md)
 
@@ -92,6 +92,7 @@ Ces fondations existent et ne sont **pas** à refaire pour chaque app :
 | 06b | [CI des apps Bun/Nuxt](06b-bun-nuxt-ci.md) | `.gitea/workflows/ci.yml` : gates lint/test/`nuxt build` + piège Node 18→20 | ✅ |
 | 07 | [Enregistrement ArgoCD](07-argocd-register.md) | `factory/argocd/values.yaml` → Application + déploiement | ✅ |
 | 08 | [Checklist](08-checklist.md) | Récapitulatif ordonné + definition of done | ✅ |
+| 09 | [Service compagnon](09-service-compagnon.md) | Un service qui partage le namespace + stack Vault/DB d'une app existante (ex. API cœur, façade) | ✅ |
 
 ## Légende de statut
 

doc/runbooks/new-web-app/conventions.md

@@ -44,6 +44,9 @@ Les briques se « branchent » entre elles **par convention de nom**, pas par co
 ✅ **Utilise un nom court, stable, kebab-case** dès le départ.
 ❌ **N'introduis pas** de variantes (`my_app` vs `my-app`, `MyApp`, pluriels) : rien ne te préviendra, l'app échouera silencieusement à se connecter ou à se déployer.
 
+> [!NOTE]
+> **Exception : les services compagnons.** Un service qui partage le namespace et le stack d'une app existante (ex. une API cœur à côté de son front) **emprunte l'identité du primaire** — sa base, son rôle Vault et son ServiceAccount portent le nom du **primaire**, pas le sien. La règle « tout est `<app>` » ne vaut alors que pour son dépôt, son chart et son image. Voir [9. Service compagnon](09-service-compagnon.md).
+
 ## Plusieurs environnements pour une même app
 
 Une application peut être déployée plusieurs fois (prod, sandbox, …) **sans devenir une app distincte** : même dépôt, même chart, même version. On ajoute une seconde coordonnée `<env>` au nom, régie par une **règle d'élision** ([ADR-0002](../../../vibe/ADR/0002-per-application-environments.md)) :
@@ -76,3 +79,4 @@ Déclaration : `postgres/iac/terraform.tfvars` et la liste `applications` côté
 - [05 · Terraform de l'app](05-app-terraform.md) — appelle `app_roles` avec `name=<app>`.
 - [06 · Workflows CI](06-ci-workflows.md) — s'authentifie avec `gitea_cicd_<app>`.
 - [07 · Enregistrement ArgoCD](07-argocd-register.md) — déclare `<app>` dans `gitea_applications`.
+- [09 · Service compagnon](09-service-compagnon.md) — l'exception : un compagnon emprunte l'identité de l'app primaire.