Files

T

arcodangeandClaude Opus 4.8 e1167eec27 docs(runbook) — chapitre « service compagnon » (namespace + stack partagés)

Le runbook new-web-app couvre l'app autonome (dépôt/base/Vault/namespace propres,
tout nommé <app>). Il manquait le cas du SERVICE COMPAGNON : un second service qui
partage le namespace — et parfois le stack Vault/DB — d'une app existante (API cœur
à côté de son front, façade d'analyse). Deux précédents vivants non documentés :
kadans-jobs (namespace seul) et kadans-api (namespace + base + Vault).

- Nouvelle page 09-service-compagnon.md : compagnon vs app autonome ; les deux
  formes (sans état / partage Vault+DB) ; le PIÈGE du VaultAuth manquant quand
  l'app primaire ne consomme pas Vault (front statique) → le compagnon pose son
  propre VaultAuth mais avec le rôle+SA du PRIMAIRE ; carte, précédents, delta de
  checklist.
- 07-argocd-register.md : ajoute la ligne `namespace:` aux options (elle existait
  dans values.yaml — kadans-jobs — mais n'était pas documentée) ; corrige le
  callout qui affirmait le namespace « non configurable ».
- conventions.md : note l'exception compagnon à la règle « tout est <app> ».
- README.md : entrée 09 dans l'index + Last Updated.

Vérifié : VaultAuth erp nommé `auth` ; connexion via pgbouncer.tools ; liens
internes tous résolus.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_013ws8L74dVZmp97Wu36fm8j

2026-07-24 10:38:27 +02:00

7.3 KiB

Raw Blame History

Factory > Doc > Runbooks > Nouvelle application web > Conventions de nommage

Conventions de nommage

Pourquoi cette page. Un seul nom — <app> — est réutilisé à l'identique dans une dizaine de systèmes (Gitea, Postgres, Vault, Kubernetes, ArgoCD, GCS, DNS). Toutes les étapes du runbook en dépendent ; on le centralise ici pour ne pas le ré-expliquer partout. Audience. Quiconque crée ou audite une app sur la plateforme. Status. Actif · revu le 2026-05-31.

TL;DR

Choisis un identifiant <app> en kebab-case minuscule (webapp, erp, dance-lessons-coach, url-shortener). Ce nom devient, sans variation, la clé de toutes les ressources. Une seule faute de frappe quelque part casse la chaîne (auth Vault, rattachement DB, sync ArgoCD).

Le nom `<app>` dans chaque système

Système	Identifiant dérivé de `<app>`	Exemple (`erp`)	Source de vérité
Dépôt Gitea	`arcodange-org/<app>` (ou `arcodange/<app>` si `org` surchargé)	`arcodange-org/erp`	argocd/templates/apps.yaml
Base PostgreSQL	`<app>`	`erp`	postgres/iac/main.tf
Rôle propriétaire PG (non-login)	`<app>_role`	`erp_role`	postgres/iac/main.tf
Rôle DB dynamique Vault	`postgres/creds/<app>`	`postgres/creds/erp`	modules/app_roles/main.tf
Rôle d'auth Kubernetes (Vault)	`<app>`	`erp`	modules/app_roles/main.tf
Policy Vault runtime (pod)	`<app>`	`erp`	modules/app_policy/main.tf
Policy Vault CI (ops)	`<app>-ops`	`erp-ops`	modules/app_policy/main.tf
Rôle JWT de CI (Vault)	`gitea_cicd_<app>`	`gitea_cicd_erp`	modules/app_policy/main.tf
Groupe d'identité Vault	`<app>-ops`	`erp-ops`	modules/app_policy/main.tf
Secret KV de config	`kvv2/<app>/config`	`kvv2/erp/config`	modules/app_roles (sortie `kvv2_path_prefix`)
Namespace Kubernetes	`<app>`	`erp`	apps.yaml (`CreateNamespace=true`)
ServiceAccount Kubernetes	`<app>`	`erp`	chart/templates/serviceaccount.yaml
Application ArgoCD	`<app>`	`erp`	apps.yaml
Préfixe d'état OpenTofu (GCS)	`<app>/main`	`erp/main`	iac/backend.tf
Domaine interne	`<app>.arcodange.lab`	`erp.arcodange.lab`	chart/values.yaml (ingress)
Domaine public	`<app>.arcodange.fr`	`webapp.arcodange.fr`	chart/values.yaml (ingress)

Pourquoi cette uniformité est structurante

Les briques se « branchent » entre elles par convention de nom, pas par configuration explicite :

Le module app_roles génère un user PG dynamique avec GRANT <app>_role TO … → il suppose que <app>_role (créé à l'étape 2) porte exactement ce nom.
Le VaultDynamicSecret du chart lit postgres/creds/<app> → il suppose que le rôle Vault (créé à l'étape 5) porte exactement <app>.
L'Application ArgoCD déduit repoURL=.../<app>, path=chart, namespace=<app> du seul nom → le dépôt (étape 1) et le namespace doivent matcher.

✅ 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.

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) :

env vaut prod par défaut, et prod s'élide. Quand env == prod, aucun suffixe n'est ajouté : tous les noms dérivés sont identiques au cas mono-environnement décrit plus haut. Une app existante ne change donc pas (plan à vide).
Les environnements non-prod prennent le suffixe <app>-<env> en kebab-case partout — base, namespace, chemins/rôles/policies Vault, Application ArgoCD, hôte DNS, sous-préfixe d'état GCS — à une exception : le rôle propriétaire PostgreSQL reste en snake-case <app>_<env>_role, pour rester cohérent avec le suffixe _role.
Un seul dépôt et un seul chart servent tous les environnements ; les différences sont superposées via values-<env>.yaml. Un seul rôle JWT de CI (gitea_cicd_<app>) par dépôt couvre tous ses environnements.

Exemple — erp (prod, élidé) vs erp-sandbox :

Système	`erp` (env = prod)	`erp-sandbox` (env = sandbox)
Base PostgreSQL	`erp`	`erp-sandbox`
Rôle propriétaire PG	`erp_role`	`erp_sandbox_role`
Namespace + ServiceAccount	`erp`	`erp-sandbox`
Creds DB dynamiques Vault	`postgres/creds/erp`	`postgres/creds/erp-sandbox`
Secret KV de config	`kvv2/erp/config`	`kvv2/erp-sandbox/config`
Application ArgoCD	`erp`	`erp-sandbox`
Domaine interne	`erp.arcodange.lab`	`erp-sandbox.arcodange.lab`
Dépôt Gitea / chart / JWT CI	`arcodange-org/erp` · chart · `gitea_cicd_erp`	partagés (mêmes valeurs)

Déclaration : postgres/iac/terraform.tfvars et la liste applications côté tools acceptent envs = ["prod", "sandbox"] ; l'omettre revient à ["prod"]. L'Application ArgoCD non-prod se déclare via une clé envs sous l'app dans argocd/values.yaml.

Références croisées

01 · Dépôt Gitea — fixe <app> comme nom de dépôt sous arcodange-org.
02 · Base de données — crée <app> et <app>_role.
03 · Vault plateforme — crée gitea_cicd_<app>, policies <app> / <app>-ops.
04 · Chart Helm — référence <app>, creds/<app>, kvv2/<app>/config.
05 · Terraform de l'app — appelle app_roles avec name=<app>.
06 · Workflows CI — s'authentifie avec gitea_cicd_<app>.
07 · Enregistrement ArgoCD — déclare <app> dans gitea_applications.
09 · Service compagnon — l'exception : un compagnon emprunte l'identité de l'app primaire.

7.3 KiB Raw Blame History