Files

Gabriel Radureau 8330d82225 docs(runbooks): add "new web app" setup runbook under doc/runbooks/

Document, as a tree-docs tree, the end-to-end procedure to stand up a new
web application on the Arcodange platform — a mechanic spread across the
factory, tools and app repos with non-trivial ordering dependencies.

Covers: Gitea repo creation (org-secret inheritance), Postgres DB + owner
role (factory/postgres/iac), platform Vault declaration (gitea_cicd_<app>
+ policies, tools/hashicorp-vault/iac), the app Helm chart (VSO dynamic
secrets via pgbouncer), the app Terraform (app_roles module), the CI
workflows (tofu apply + image build, incl. the copy-pasted role pitfall),
and ArgoCD registration (factory/argocd/values.yaml). Adds a naming-
conventions concept page and an ordered checklist.

Wires the legacy doc/adr "setup hello world web app" item and the factory
README to the runbook. New docs live under doc/ (singular) per the PR #8
convention.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-05-31 17:22:30 +02:00

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

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.

4.6 KiB Raw Blame History