Skill Terraform pour Claude

Guidance diagnostique d'abord pour Terraform et OpenTofu. Le fichier principal est un workflow ; la profondeur se charge à la demande dans les références.

Contrat de réponse

Toute réponse Terraform/OpenTofu doit inclure :

1. Hypothèses et version minimale — runtime (terraform ou tofu), version exacte, providers, backend d'état, chemin d'exécution (local/CI/Cloud/Atlantis), criticité de l'environnement. Énoncez explicitement les hypothèses d'état si l'utilisateur ne les a pas fournies.
2. Catégorie de risque traitée — une ou plusieurs de : churn d'identité, exposition de secrets, rayon d'explosion, dérive CI, lacunes de conformité, corruption d'état, risque de mise à jour de provider, angles morts de test.
3. Remédiation choisie et compromis — ce qui a été choisi, ce qui a été échangé, pourquoi.
4. Plan de validation — commandes exactes (fmt -check, validate, plan -out, vérification de politique) adaptées au runtime et au niveau de risque.
5. Notes de restauration — pour tout changement destructif ou mutant d'état : comment annuler, quelles preuves conserver.

Ne recommandez jamais un apply direct en production sans un artefact plan examiné et une approbation.

Ne lancez jamais terraform destroy (ciblé ou complet) sans d'abord exécuter terraform plan -destroy et montrer à l'utilisateur chaque ressource qui sera supprimée — incluant les dépendants implicites tirés via des locals ou for_each. Obtenez une confirmation explicite avant de procéder. N'utilisez jamais -auto-approve sur destroy.

Workflow

1. Capturez le contexte d'exécution — runtime+version, provider(s), backend, chemin d'exécution, criticité de l'environnement.
2. Diagnostiquez le(s) mode(s) de défaillance en utilisant la table de routage ci-dessous. Si l'intention s'étend sur plusieurs catégories, chargez les deux références.
3. Chargez uniquement le(s) fichier(s) de référence correspondant(s) — ne préchargez pas la profondeur que la tâche ne nécessite pas.
4. Proposez une correction avec contrôles de risque — pourquoi cela traite le mode, ce qui pourrait encore mal tourner, garde-fous (tests/approbations/restauration).
5. Générez des artefacts — HCL, blocs de migration (moved, import), changements CI, règles de politique.
6. Validez avant de finaliser — exécutez les commandes de validation adaptées au niveau de risque.
7. Émettez le Contrat de réponse à la fin.

Diagnostiquer avant de générer

Quand utiliser cette Skill

Activez quand : création ou examen de configurations ou modules Terraform/OpenTofu, mise en place ou débogage de tests, structuration de déploiements multi-environnements, implémentation d'IaC CI/CD, choix de patterns de modules ou organisation d'état, configuration ou migration de backends d'état distants.

N'utilisez pas pour : questions de syntaxe HCL basiques que Claude connaît déjà, référence API de provider (lien vers les docs), questions de plateforme cloud non liées à Terraform/OpenTofu.

Principes fondamentaux

Hiérarchie des modules

Flux : ressource → module de ressource → module d'infrastructure → composition.

Disposition des répertoires

environments/   # prod/ staging/ dev/  — configurations par environnement
modules/        # networking/ compute/ data/ — modules réutilisables
examples/       # minimal/ complete/ — docs + fixtures d'intégration

Séparez les environnements des modules. Utilisez examples/ à la fois comme documentation et fixtures de test. Gardez les modules petits et responsabilité unique.

Voir Module Patterns pour les principes d'architecture, conventions de nommage, contrats variable/sortie.

Conventions de nommage (résumé)

• Noms de ressources descriptifs (aws_instance.web_server, pas aws_instance.main)
• Réservez this pour les ressources singleton véritables uniquement
• Préfixez les variables avec le contexte (vpc_cidr_block, pas cidr)
• Fichiers standards : main.tf, variables.tf, outputs.tf, versions.tf

Voir Module Patterns: Variable Naming et Code Patterns: Block Ordering pour les exemples.

Ordre des blocs (résumé)

Blocs de ressources : count/for_each en premier → arguments → tags → depends_on → lifecycle. Blocs de variables : description → type → default → validation → nullable → sensitive.

Voir Code Patterns: Block Ordering & Structure pour les règles complètes et exemples.

Stratégie de test

Matrice de décision : Quelle approche de test ?

Règles de test natif (1.6+)

Avant d'écrire le code de test : validez les schémas de ressources via Terraform MCP pour que les assertions ciblent les attributs réels.

• command = plan — rapide, pour les valeurs dérivées d'entrée uniquement
• command = apply — requis pour les valeurs calculées (ARNs, noms générés) et les blocs imbriqués de type set
• Les blocs de type set ne peuvent pas être indexés avec [0] — utilisez les expressions for ou matérialisez via command = apply
• Types de set courants : règles de chiffrement S3, transitions de cycle de vie, instructions de politique IAM

Voir Testing Frameworks pour les pipelines d'analyse statique, patterns de tests natifs, intégration Terratest, mock providers, et la liste de vérification complète des erreurs LLM.

Count vs For_each — Règle rapide

Ne utilisez jamais l'index de liste comme identité de longue durée — supprimer un élément du milieu réordonne chaque adresse après lui. Pour la matrice de décision, le playbook de migration sécurisée, les patterns de bloc moved, et les cas d'échec connus lors du plan, voir Code Patterns: count vs for_each.

Locals pour la gestion des dépendances

Utiliser try() dans un local pour préférer l'attribut d'une ressource conditionnelle à son parent est un pattern spécialisé mais de haute valeur — il force un ordre de suppression correct sans depends_on explicite. Usage courant : VPC + associations CIDR secondaires + subnets.

Voir Code Patterns: Locals for Dependency Management pour le pattern complet et l'exemple travaillé.

Développement de modules

Disposition standard :

my-module/
├── README.md       # Documentation d'utilisation
├── main.tf         # Ressources principales
├── variables.tf    # Entrées typées avec descriptions
├── outputs.tf      # Valeurs de sortie
├── versions.tf     # required_version + required_providers
├── examples/
│   ├── minimal/
│   └── complete/
└── tests/
    └── module_test.tftest.hcl   # ou Go pour Terratest

Contrats de variables : toujours description, toujours type explicite, utilisez validation pour les contraintes complexes, utilisez sensitive = true pour les secrets, préférez optional() avec défauts typés (1.3+) à map(any) non typé.

Contrats de sorties : toujours description, marquez les sorties sensibles, exposez des sous-ensembles stables (pas d'objets provider entiers).

Voir Module Patterns pour les patterns de contrat complets, liste de vérification de publication de module, et liste de vérification des erreurs LLM.

CI/CD

Étapes du pipeline : validate → test → plan → apply (avec protection d'environnement).

Contrôle des coûts : mock providers sur validation PR, intégration cloud réelle uniquement sur main ou programmée, taggez les ressources de test, nettoyage automatique.

Prévention de la dérive : épinglez le runtime et les providers, committez .terraform.lock.hcl, appliquez l'artefact plan examiné de l'étape plan (ne relancez pas plan dans le job d'apply), exécutez l'étape politique/sécurité sur chaque chemin vers apply.

Voir CI/CD Workflows pour les modèles GitHub Actions, GitLab CI et Atlantis plus la liste de vérification des erreurs LLM.

Sécurité et conformité

Vérifications essentielles :

trivy config .
checkov -d .

Ne pas : stocker les secrets dans les variables ou .tfvars, utiliser le VPC par défaut, ignorer le chiffrement, ouvrir les groupes de sécurité à 0.0.0.0/0, utiliser les blocs ingress/egress inline dans aws_security_group.

Faire : sourcer les secrets d'un gestionnaire de secrets cloud (AWS Secrets Manager / Azure Key Vault / GCP Secret Manager) ou utiliser des arguments write_only sur 1.11+, créer des VPCs dédiés, appliquer le chiffrement au repos et TLS, groupes de sécurité avec privilèges minimums, utiliser des ressources aws_vpc_security_group_{ingress,egress}_rule séparées (p. ex. AWS provider v5+).

Marquer une variable sensitive = true masque l'affichage uniquement — la valeur vit toujours en état. Utilisez write_only / *_wo sur 1.11+, ou gardez le matériel secret entièrement hors de Terraform via des recherches d'exécution.

Voir Security & Compliance pour les pipelines trivy/checkov, durcissement des fichiers d'état, mappages de conformité, et la liste de vérification des erreurs LLM.

Gestion d'état

Ne utilisez jamais l'état local en équipes ou en production. Les backends distants fournissent le verrouillage automatique, le chiffrement, le versioning, la journalisation d'audit, et la collaboration sécurisée.

Choix d'un backend distant

Exemple AWS (Azure azurerm / GCP gcs / syntaxe TF Cloud : voir State Management: Choosing a Remote Backend) :

terraform {
  backend "s3" {
    bucket        = "my-terraform-state"
    key           = "prod/vpc/terraform.tfstate"
    region        = "us-east-1"
    encrypt       = true
    use_lockfile  = true   # Verrouillage S3 natif, 1.10+
  }
}

Sur Terraform < 1.10, utilisez dynamodb_table = "terraform-state-lock" à la place de use_lockfile. Azure Storage, GCS et Terraform Cloud offrent tous un verrouillage intégré - voir la référence State Management pour la syntaxe. Pour choisir entre les backends et leurs modèles de verrouillage, voir Choosing a Remote Backend.

Organisation d'état

Divisez l'état quand : différentes équipes, différents rythmes de mise à jour, ou >500 ressources. Combinez quand : ressources étroitement couplées, <100 ressources, même cycle de vie.

Voir State Management pour le verrouillage, la migration, l'isolation multi-équipes, la récupération d'urgence, et la liste de vérification des erreurs LLM.

Gestion des versions

Committez .terraform.lock.hcl intentionnellement. Gardez les mises à jour de provider/runtime dans une PR séparée des changements fonctionnels. Voir Code Patterns: Version Management pour la syntaxe de contrainte et le workflow de mise à jour.

Fonctionnalités Terraform modernes (1.0+)

Avant d'émettre une fonctionnalité, vérifiez le plancher du runtime. Voir Code Patterns: Feature Guard Table pour la table complète avec les patterns d'erreur LLM courants par fonctionnalité.

Guidance spécifique au runtime

• Terraform 1.0-1.5 (OpenTofu démarre à 1.6) : Terratest pour l'intégration, analyse statique + validation plan uniquement (pas de tests natifs).
• 1.6+ : test natif terraform test / tofu test disponible — migrez les tests unitaires simples, gardez Terratest pour l'intégration complexe.
• 1.7+ : mock providers réduisent les coûts de test — mock pour les tests unitaires, exécutions réelles pour l'intégration finale.
• 1.10+ : le fichier de verrou S3 natif (use_lockfile) est le défaut correct pour les nouvelles configurations — le verrouillage DynamoDB n'est plus requis.
• 1.11+ : les arguments write_only pour la gestion des secrets gardent les credentials hors de l'état.
• Terraform vs OpenTofu : tous deux supportés. Pour les licences, gouvernance, et delta de fonctionnalités, voir Quick Reference: Terraform vs OpenTofu.

Code Intelligence (terraform-ls)

Navigation sémantique pour HCL. terraform-ls est optionnel ; sans lui, chaque ligne ci-dessous dégénère en rg fourni + repli Read.

Couche terraform-ls auto-contenue d'une discipline de code-intelligence générique - appliquez les lignes ci-dessous directement. Compagnon recommandé : le plugin code-intelligence (même marketplace antonbabenko/agent-plugins) porte la discipline générique (ancrage de position, portail de dégradation, format de divulgation, anti-shim fantôme) et expédie /code-intelligence:doctor pour la préparation. S'il est installé, déférez à son protocole générique ; cette skill reste entièrement auto-contenue sans lui.

✅ Supportés : goToDefinition, findReferences, documentSymbol, hover, workspaceSymbol. ❌ Non supportés : goToImplementation, hiérarchie d'appel, renommer provider. N'appelez pas ces éléments puis rapportez leur absence comme une constatation.

• ✅ Prérequis : terraform/tofu local sur PATH, terraform init exécuté ; le démarrage à froid peut nécessiter une nouvelle tentative.
• ✅ Les appels LSP sont ancrés par position (file:line:character) - ancrez avec rg d'abord, jamais nom-symbole uniquement.
• ❌ Ne prétendez pas « LSP cassé, utilisant rg » jusqu'à ce que le Degradation Gate passe ; divulguez toute substitution d'outil sur la première ligne.

Profondeur : Code Intelligence.

Fichiers de référence

Divulgation progressive — essentiels ici, profondeur à la demande :

• Testing Frameworks — analyse statique, tests natifs, Terratest, mock providers
• Module Patterns — structure, contrats variable/sortie, règles terraform_remote_state, liste de vérification de publication
• CI/CD Workflows — GitHub Actions, GitLab CI, Atlantis, contrôle des coûts
• Security & Compliance — trivy/checkov, gestion des secrets, mappages de conformité
• State Management — backends, verrouillage, migration, multi-équipes, récupération
• Code Patterns — ordre des blocs, deep dive count/for_each, fonctionnalités modernes, gestion des versions, locals
• Code Intelligence - capacités terraform-ls, appels ancrés par position, renommage manuel, portail de dégradation
• Quick Reference — pense-bête de commandes, organigrammes, dépannage

Licence

Apache License 2.0. Voir LICENSE pour les conditions complètes.

Copyright © 2026 Anton Babenko