Terraform sur Google Cloud : état, identités, pipeline
Un Terraform qui tient dans la durée sur Google Cloud repose sur trois décisions prises dès le premier projet : où vit l'état (un bucket Cloud Storage versionné, un état par composant et par environnement), sous quelle identité s'exécutent les plan et les apply (un compte de service emprunté, jamais une clé), et qui a le droit d'appliquer (la CI sur une branche protégée, ou Infrastructure Manager). Tout ce qui suit vaut aussi pour OpenTofu, qui lit la même configuration.
Découpage du code et des états
| Couche | Contenu | Rythme de changement | Qui applique |
|---|---|---|---|
| Amorçage | Projet d'administration, bucket d'état, comptes de service Terraform, pool Workload Identity Federation | Une fois, puis rarement | Un administrateur ; état local migré ensuite vers le bucket |
| Organisation | Dossiers, stratégies d'organisation, IAM d'organisation, journaux centralisés | Rare | Compte de service de l'organisation |
| Réseau | VPC partagé, sous-réseaux, DNS, interconnexions | Rare | Compte de service réseau, limité au projet hôte |
| Projets | Création des projets par une project factory, API activées, budgets | À chaque nouvelle équipe | Compte de service des projets |
| Applications | Cloud Run, bases, buckets, IAM de l'application, par environnement | Fréquent | Compte de service de l'application, un par environnement |
- Un état par composant et par environnement. La recommandation de Google est de ne pas dépasser 100 ressources par état, idéalement quelques dizaines : chaque
planrelit toutes les ressources de l'état. Un dossierenvironments/dev,environments/prod… par service, chacun avec sonbackend.tf, qui instancie un module commun. - Pas d'espaces de travail multiples (workspaces) pour séparer les environnements : un seul backend partagé devient un point de défaillance unique, et le code se remplit de
terraform.workspace == "prod" ? … : …. - Communication entre états par les sorties : la couche réseau exporte l'identifiant du VPC, la couche application le lit avec la source de données
terraform_remote_state. - Versions figées. Chaque module racine fixe la version mineure du fournisseur (
~> 8.4accepte les correctifs 8.4.x) et versionne son.terraform.lock.hcl. Les versions se relisent régulièrement, par exemple avec Dependabot.
Backend et fournisseur
terraform {
required_providers {
google = { source = "hashicorp/google", version = "~> 8.4" }
}
backend "gcs" {
bucket = "PROJECT_ADMIN-tfstate"
prefix = "reseau/prod" # un préfixe par état
impersonate_service_account = "terraform-reseau@PROJECT_ADMIN.iam.gserviceaccount.com"
}
}
provider "google" {
project = var.project_id
region = "europe-west1"
impersonate_service_account = "terraform-reseau@PROJECT_ADMIN.iam.gserviceaccount.com"
default_labels = { gere-par = "terraform" }
}
- Verrouillage. Le backend
gcsverrouille l'état pendant chaque opération, sans table annexe. Le bucket doit exister avantterraform init: on le crée dans la couche d'amorçage, avec un état local qu'on migre ensuite (terraform init -migrate-state). - Versionnage. HashiCorp recommande fortement d'activer Object Versioning sur le bucket d'état, pour récupérer une version après une erreur ; une règle de cycle de vie supprime les versions trop anciennes.
- Chiffrement. Le bucket est chiffré au repos par défaut.
kms_encryption_keychiffre l'état avec une clé Cloud KMS (l'agent de service Cloud Storage doit avoirroles/cloudkms.cryptoKeyEncrypterDecryptersur la clé) ;encryption_keyou la variableGOOGLE_ENCRYPTION_KEYprennent une clé fournie par le client. Un état chiffré par une clé perdue ou détruite est irrécupérable. OpenTofu peut en plus chiffrer le fichier lui-même, côté client, avant son envoi au backend. - Accès au bucket. Seuls la CI et un ou deux administrateurs lisent le bucket : l'état contient les attributs de toutes les ressources, secrets compris.
# Couche d'amorçage : le bucket d'état lui-même
resource "google_storage_bucket" "etat" {
name = "PROJECT_ADMIN-tfstate"
location = "EU"
uniform_bucket_level_access = true
public_access_prevention = "enforced"
versioning { enabled = true }
lifecycle_rule {
condition { num_newer_versions = 20 }
action { type = "Delete" }
}
lifecycle { prevent_destroy = true }
}
Identités
- En local :
gcloud auth application-default loginproduit les identifiants ADC de l'utilisateur, etimpersonate_service_accountfait exécuter les appels sous le compte de service Terraform. L'utilisateur n'a besoin que deroles/iam.serviceAccountTokenCreatorsur ce compte, pas des rôles d'administration eux-mêmes ; les quotas et les droits sont ceux du compte emprunté (voir Authentifier un appel). - En CI hors Google Cloud (GitHub Actions, GitLab CI) : Workload Identity Federation échange le jeton OIDC du pipeline contre un jeton Google, sans clé JSON (voir Déployer sans clé). Si le fournisseur
googleemprunte ensuite un compte de service, le principal fédéré doit avoirroles/iam.serviceAccountTokenCreatorsur ce compte. - En CI sur Google Cloud : Cloud Build s'exécute sous le compte de service choisi pour le déclencheur ; les identifiants sont injectés, rien à télécharger.
- Séparer les pouvoirs. Un compte de service par couche, limité à son périmètre (le compte réseau n'a de droits que sur le projet hôte). Un compte en lecture pour les
plandes pull requests, un compte d'écriture réservé à l'applysur la branche protégée.
Pipeline
Le principe : plan sur chaque pull request, relu par un humain ; apply du plan enregistré après la fusion, jamais d'apply depuis un poste.
# .github/workflows/terraform.yml (extrait)
permissions: { contents: read, id-token: write }
steps:
- uses: actions/checkout@v7
- uses: google-github-actions/auth@v3
with:
workload_identity_provider: projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER
- uses: hashicorp/setup-terraform@v4
- run: terraform init -input=false
- run: terraform plan -input=false -out=tfplan
- if: github.ref == 'refs/heads/main' && github.event_name == 'push'
run: terraform apply -input=false tfplan
- Contrôle de conformité avant l'
apply.gcloud beta terraform vetpréversion (composantterraform-tools) confronte le plan JSON à une bibliothèque de contraintes et renvoie le code 2 en cas de violation :terraform show -json tfplan > tfplan.json, puisgcloud beta terraform vet tfplan.json --policy-library=POLICY_DIR. Conftest ou OPA lisent le même JSON avec des règles Rego. Les stratégies d'organisation restent le garde-fou final, appliqué par l'API quel que soit l'outil. - Avec Infrastructure Manager, la CI ne lance pas Terraform elle-même :
gcloud infra-manager previews createremplace leplan,gcloud infra-manager deployments applyl'apply, sous un compte de service qui porteroles/config.agent. Le moduleim_cloudbuild_workspace(dépôtterraform-google-modules/bootstrap) crée les deux déclencheurs Cloud Build : prévisualisation sur pull request, déploiement à la fusion. La configuration ne doit pas contenir de blocbackend, et Terraform est limité à la version 1.5.7.
Modules de Google
- Cloud Foundation Toolkit (CFT) : les modules de l'organisation GitHub
terraform-google-modules, publiés dans le registre Terraform (terraform-google-modules/project-factory/google,…/network/google), et les blueprints qui les assemblent —terraform-example-foundationpour une fondation d'organisation sécurisée. Ils s'utilisent comme dépendances versionnées. - Cloud Foundation Fabric (dépôt
GoogleCloudPlatform/cloud-foundation-fabric) : des modules plus minces, proches des ressources du fournisseur, et FAST, une fondation d'organisation par étapes. Le dépôt est fait pour être cloné puis repris dans ses propres dépôts, pas référencé comme une bibliothèque.
Reprendre l'existant
import {
id = "projects/PROJECT_ID/global/networks/reseau-principal"
to = google_compute_network.principal
}
- Blocs
import(Terraform 1.5 et plus) : l'import se prévisualise auplanet s'exécute à l'apply.terraform plan -generate-config-out=genere.tfécrit les blocsresourcecorrespondants, à relire. Le format de l'idest donné dans la section Import de chaque ressource du fournisseur.terraform import ADRESSE IDfait la même chose ressource par ressource, hors revue. - préversion Export en masse :
gcloud beta resource-config bulk-export --project=PROJECT_ID --resource-format=terraform --path=DOSSIER(composantconfig-connector, API Cloud Asset) produit le HCL de tout un projet, un dossier ou une organisation ;gcloud beta resource-config list-resource-typesliste les types couverts. - Infrastructure Manager :
--import-existing-resourcessurdeployments applyimporte une ressource au lieu d'échouer sur un conflit 409, pour les types pris en charge. - Google recommande de n'importer qu'avec une approbation explicite, et de recréer plutôt qu'importer quand c'est peu coûteux : une ressource importée garde une configuration dont on ne connaît pas toujours l'origine.
Pièges
- Secrets dans l'état.
google_service_account_key,tls_private_keyou un mot de passe passé àgoogle_sql_userfinissent en clair dans l'état ;sensitivene les masque qu'à l'affichage. Les arguments write-only (password_wodegoogle_sql_user,secret_data_wodegoogle_secret_manager_secret_version) ne sont jamais écrits dans l'état, mais demandent Terraform 1.11 ou plus. Sinon, créer le secret dans Secret Manager par Terraform et y ajouter la valeur hors de Terraform. - API activées à terme.
google_project_servicerend la main avant que l'API soit toujours utilisable : la ressource suivante échoue avec « API has not been used in project … or it is disabled », surtout dans un projet qui vient d'être créé. Relancer, ou faire dépendre les ressources de l'activation.disable_on_destroy = falseévite qu'undestroycoupe une API dont d'autres dépendent. - Propagation IAM. Une liaison de rôle s'applique en général en deux minutes, parfois sept ou plus : un
applyqui crée un rôle puis l'utilise aussitôt peut échouer en 403 et réussir à la relance. - Ressources IAM exclusives.
google_project_iam_policyetgoogle_project_iam_bindingréécrivent toute la stratégie ou tout le rôle, et retirent au passage les rôles posés par Google pour ses agents de service. Préférergoogle_project_iam_member, qui ajoute une liaison sans toucher aux autres (voir IAM). - Protections contre la suppression, à deux niveaux.
deletion_protectiondu fournisseur (vrai par défaut sur les clusters GKE et les instances Cloud SQL) bloque seulement Terraform ;deletion_protection_enabledd'une instance Cloud SQL protège côté Google, contre la console etgcloudaussi.google_projectportedeletion_policy = "PREVENT"par défaut. Pour le reste,lifecycle { prevent_destroy = true }. - Le bucket d'état dans le projet qu'il gère. Un
destroydu projet emporte l'état qui le décrivait. Le bucket vit dans le projet d'administration de la couche d'amorçage.
Alternatives en logiciel libre
- OpenTofu (MPL 2.0) : même HCL, même fournisseur
google, même backendgcs; il chiffre en plus l'état côté client, avec une clé Cloud KMS par son fournisseur de clésgcp_kms. - Atlantis (Apache 2.0) : exécute
plansur chaque pull request etapplysur commentaire, en publiant le résultat dans le fil ; serveur et identité sont à héberger soi-même. - Terragrunt (MIT) : génère les blocs
backendetproviderpar environnement et enchaîne les états dépendants. - TFLint (MPL 2.0) et son jeu de règles Google (MPL 2.0) : détecte avant le
planles valeurs que l'API refuserait, comme un type de machine inexistant. - Trivy et Checkov (Apache 2.0) : analyse statique du code HCL (bucket public, chiffrement absent, rôle primitif), en complément des règles Rego évaluées par Conftest (Apache 2.0) sur le plan.
- Infracost (Apache 2.0) : estime en pull request l'écart de coût mensuel introduit par le plan, ressources Google Cloud comprises.
- Tofu Controller (Apache 2.0) : exécute OpenTofu depuis Flux, avec détection et correction périodique de la dérive, pour ceux qui veulent un modèle GitOps sans quitter HCL.