Projet 07 : un « service Terraform managé » qui tourne sur votre machine

Oui, c'est possible. Ce projet monte en local, avec Docker, l'équivalent complet du circuit d'entreprise GitHub → service Terraform managé → cloud, puis le teste de bout en bout, automatiquement.

Résultat vérifié sur une installation partant de zéro : 24 vérifications, 0 échec, et la simulation est rejouable. Le journal de référence est dans docs/execution-reference.txt.

Sommaire

1. Architecture
2. Prérequis
3. Démarrage en 3 commandes
4. Ce que fait l'installation, étape par étape
5. La simulation automatique : 3 scénarios
6. Refaire le parcours à la main, dans le navigateur
7. Comprendre chaque fichier de configuration
8. Les pièges rencontrés pendant la mise au point, et leurs solutions
9. Passer au réel : GitHub + Google Cloud
10. Aide-mémoire des commandes Atlantis
11. Dépannage
12. Nettoyage

1. Architecture

  Navigateur / scripts (votre machine)
        │ localhost:3000          │ localhost:4141           │ localhost:9001
        ▼                         ▼                          ▼
 ┌──────────────┐  webhook  ┌──────────────┐  état S3   ┌──────────────┐
 │    Gitea     │ ────────▶ │   Atlantis   │ ─────────▶ │    MinIO     │
 │  (≈ GitHub)  │ ◀──────── │ (≈ service   │  + verrou  │ (≈ Cloud     │
 │ acme/infra-  │ commentai-│   managé)    │  .tflock   │   Storage)   │
 │    demo      │ res, clone│ terraform +  │            │ bucket       │
 └──────────────┘           │ conftest     │            │ tfstate      │
                            └──────────────┘            └──────────────┘
          réseau Docker privé « tfsvc_default » : gitea:3000, atlantis:4141, minio:9000

Les personnages (comptes Gitea créés automatiquement) :

Le circuit : PR ouverte → Gitea envoie un webhook → Atlantis clone la branche, lance terraform init + plan → contrôle les politiques (Conftest) → publie plan et résultat dans la PR → l'apply n'est accepté que si la PR est approuvée et que les politiques passent → l'état est écrit dans MinIO, sous verrou.

2. Prérequis

• Docker et Docker Compose v2 (docker compose version)
• Python 3, git, curl (déjà présents sur la plupart des Linux)
• Accès Internet pour télécharger 3 images : gitea/gitea, ghcr.io/runatlantis/atlantis, minio/minio (environ 1 Go). L'image Atlantis embarque déjà Terraform et Conftest.
• Ports libres : 3000 (Gitea), 4141 (Atlantis), 9000/9001 (MinIO). Ils sont modifiables dans .env.

Versions testées : Gitea 28.0, Atlantis 0.48.0 (Terraform 1.16.3, Conftest 0.70), MinIO 2025-09.

3. Démarrage en 3 commandes

cd 07-terraform-service-local
./scripts/setup.sh              # installe et configure tout (environ 1 à 2 min, plus le téléchargement des images)
python3 scripts/scenario.py     # simule le circuit complet et vérifie chaque étape (environ 3 à 5 min)

Puis ouvrez :

• Gitea : http://localhost:3000 (alice, mot de passe dans .env : ALICE_PASSWORD) → acme/infra-demo → Pull requests
• Atlantis : http://localhost:4141 (verrous en cours, historique)
• Console MinIO : http://localhost:9001 (MINIO_ROOT_USER / MINIO_ROOT_PASSWORD de .env) → bucket tfstate

Pour tout supprimer : ./scripts/teardown.sh.

4. Ce que fait l'installation, étape par étape

Fichier : scripts/setup.sh. Il peut être relancé sans risque (idempotent).

Vérifier à la main :

docker compose ps                                   # 3 services "Up (healthy)"
curl -s localhost:4141/healthz                      # {"status":"ok"}
docker compose logs atlantis | grep "Atlantis started"

5. La simulation automatique : 3 scénarios

Fichier : scripts/scenario.py. Il joue les personnages via l'API Gitea, attend les réponses d'Atlantis dans les PR, et vérifie chaque résultat : il s'arrête à la première anomalie.

Scénario 1 : un changement conforme, de bout en bout

Scénario 2 : un changement non conforme est arrêté

C'est le point clé d'un service managé : une approbation humaine ne suffit pas à contourner une règle de l'entreprise. Seul bob, propriétaire des politiques, pourrait accorder une dérogation tracée (atlantis approve_policies).

Scénario 3 : deux PR sur le même projet → verrou

Le verrou garantit que le plan approuvé est celui qui sera appliqué : personne ne peut modifier la même infrastructure entre-temps.

Extrait du journal de référence (complet ici) :

[07] alice relance « atlantis apply -p dev » → Atlantis applique LE plan approuvé
     ✔ Apply réussi :
       │ Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
[10] alice propose un bucket en us-central1, sans label cost_center, dans envs/prod
     ✔ …mais les politiques ÉCHOUENT :
       │ FAIL - … : label obligatoire 'cost_center' manquant
       │ FAIL - … : localisation 'us-central1' interdite (UE uniquement)
━━━ BILAN : toutes les vérifications sont passées ━━━

6. Refaire le parcours à la main, dans le navigateur

Le meilleur moyen de comprendre est de faire le scénario 1 vous-même :

1. Connexion : http://localhost:3000 avec alice (mot de passe : grep ALICE_PASSWORD .env).
2. Modifier le code : acme/infra-demo → dossier envs/dev → Nouveau fichier photos.tf :

   module "photos" {
     source   = "../../modules/gcs_bucket_sim"
     name     = "acme-dev-photos"
     location = "EU"
     labels   = { owner = "media-team", env = "dev", cost_center = "cc-2002" }
   }

   Choisissez « Créer une nouvelle branche pour ce commit et démarrer une PR ».
3. Ouvrir la PR : en quelques secondes, atlantis-bot commente le plan puis le résultat des politiques.
4. Tenter l'apply : commentez atlantis apply -p dev → refus (pas d'approbation).
5. Approuver : déconnectez-vous, connectez-vous en bob, ouvrez la PR → Fichiers modifiés → Revue → Approuver.
6. Appliquer : en alice, commentez atlantis apply -p dev → « Apply complete! ».
7. Voir l'état : console MinIO (http://localhost:9001) → tfstate/dev/terraform.tfstate → onglet Versions (chaque apply crée une version : c'est votre sauvegarde).
8. Voir les verrous : http://localhost:4141 → liste des verrous. Puis atlantis unlock et Fusionner.

Variante « politique » : refaites l'étape 2 avec location = "us-east1" : Atlantis affichera Policy Check Failed avec le motif exact.

Les liens publiés par Gitea pointent vers http://gitea:3000/… (adresse interne au réseau Docker). Pour les ouvrir tels quels depuis le navigateur, ajoutez 127.0.0.1 gitea à /etc/hosts, ou remplacez gitea par localhost dans l'URL.

7. Comprendre chaque fichier de configuration

7.1 docker-compose.yml : les 3 services

7.2 atlantis/repos.yaml : la politique du service (côté serveur)

repos:
  - id: /.*/
    apply_requirements: [approved, mergeable]   # pas d'apply sans PR approuvée et fusionnable
    allow_custom_workflows: false               # un dépôt ne peut pas injecter ses propres commandes
    policy_check: true                          # politiques obligatoires
policies:
  owners: { users: [bob] }                      # seule la sécurité peut accorder une dérogation
  policy_sets:
    - { name: socle-entreprise, path: /policies, source: local }

Pourquoi côté serveur : si ces règles étaient dans le dépôt, une PR pourrait les assouplir. Ici, elles s'imposent à tous les dépôts.

7.3 infra-repo/atlantis.yaml : la configuration côté dépôt

Elle déclare les projets (dev = envs/dev, prod = envs/prod) et quand planifier (when_modified : les .tf du dossier et des modules). Chaque projet a son état et son verrou.

7.4 policies/baseline.rego : les règles de l'entreprise

Écrites en Rego (langage d'OPA), évaluées par Conftest sur le plan JSON :

1. localisation UE uniquement ;
2. labels obligatoires owner, env, cost_center ;
3. pas de bucket public.

Chaque règle deny renvoie un message clair, affiché dans la PR.

7.5 infra-repo/envs/*/main.tf : le backend d'état

backend "s3" {
  bucket       = "tfstate"
  key          = "dev/terraform.tfstate"     # un état par environnement
  endpoints    = { s3 = "http://minio:9000" }
  use_lockfile = true                          # verrou natif (fichier .tflock), Terraform >= 1.10
  ...
}

En production sur Google Cloud : backend "gcs" { bucket = "acme-tfstate-prod", prefix = "dev" }. Le verrou est natif, l'objet .tflock étant créé par écriture conditionnelle.

7.6 infra-repo/modules/gcs_bucket_sim : la ressource simulée

terraform_data enregistre la configuration d'un bucket (nom, localisation, labels, public) sans appeler de cloud. Pour passer en réel, on remplace ce bloc par google_storage_bucket avec les mêmes variables. Les politiques, les PR, les verrous et l'état fonctionnent à l'identique.

8. Les pièges rencontrés pendant la mise au point, et leurs solutions

Ces problèmes sont apparus réellement pendant les tests. Ils sont corrigés dans les fichiers, mais les connaître vous fera gagner des heures.

9. Passer au réel : GitHub + Google Cloud

La mécanique reste la même ; seules les briques changent.

Exemple : Atlantis sur Cloud Run (extrait, à adapter) :

gcloud run deploy atlantis --image ghcr.io/runatlantis/atlantis:latest --region europe-west1 \
  --service-account atlantis-runner@acme-iac.iam.gserviceaccount.com \
  --set-secrets ATLANTIS_GH_TOKEN=atlantis-gh-token:latest,ATLANTIS_GH_WEBHOOK_SECRET=atlantis-webhook:latest \
  --set-env-vars ATLANTIS_REPO_ALLOWLIST=github.com/acme/*,ATLANTIS_ATLANTIS_URL=https://atlantis.acme.example \
  --min-instances 1 --max-instances 1     # Atlantis garde ses verrous localement : une seule instance

Atlantis est mono-instance par défaut (verrous dans une base locale BoltDB). Pour la haute disponibilité : backend de verrous Redis (ATLANTIS_LOCKING_DB_TYPE=redis) et stockage partagé. C'est l'une des raisons pour lesquelles les grandes entreprises choisissent souvent un service managé (HCP Terraform, Spacelift…) ou une plateforme interne.

Et avec Gemini Enterprise : le dépôt infra-gemini-enterprise (chapitre 26 du guide Terraform) se branche exactement comme infra-demo. Atlantis planifie envs/recette et envs/prod, la politique vérifie par exemple « localisation eu », « Model Armor en FAIL_CLOSED », « connecteurs en FEDERATED », et l'image Atlantis doit contenir gcloud et curl pour les réglages REST du socle (image personnalisée FROM ghcr.io/runatlantis/atlantis).

10. Aide-mémoire des commandes Atlantis

À écrire en commentaire de la PR :

11. Dépannage

12. Nettoyage

./scripts/teardown.sh      # supprime conteneurs, volumes (dépôts, états, verrous) et .env

Fichiers

07-terraform-service-local/
├── docker-compose.yml          ← Gitea + MinIO + Atlantis
├── atlantis/repos.yaml         ← règles du service (côté serveur)
├── policies/baseline.rego      ← politiques de l'entreprise (Conftest / OPA)
├── infra-repo/                 ← contenu du dépôt acme/infra-demo poussé dans Gitea
│   ├── atlantis.yaml           ← projets dev / prod
│   ├── envs/dev/main.tf · envs/prod/main.tf   ← backend d'état + modules
│   └── modules/gcs_bucket_sim/ ← « bucket GCS » simulé
├── scripts/
│   ├── setup.sh                ← installation complète (idempotente)
│   ├── scenario.py             ← simulation pas à pas avec vérifications
│   └── teardown.sh             ← tout supprimer
└── docs/execution-reference.txt← journal d'une exécution réussie depuis zéro

Sources : Atlantis · Atlantis : configuration côté serveur · Atlantis : politiques · Gitea : configuration · Gitea #39557 (règle de sortie des webhooks en v28) · Terraform : backend S3, use_lockfile