Construire les fondations en code (Pulumi)
Les fondations décrites dans Organiser l'environnement — dossiers, règles d'administration, groupes, réseau partagé, projets — se construisent en IaC, jamais à la main. L'enterprise foundations blueprint de Google va plus loin : les ressources de la fondation ne sont modifiées que par un pipeline, et les humains n'ont que des droits de lecture sur elles. Ce site recommande Pulumi en Python pour l'écrire (voir Choisir un outil d'IaC) ; l'équivalent Terraform, et les modules de Google qui le servent, sont dans Terraform sur Google Cloud.
Pourquoi le code est indispensable ici
- Reproductibilité. La configuration de l'organisation se relit et se reconstruit : un deuxième environnement, une organisation de test ou une filiale reprennent le même code.
- Revue. Une règle d'administration ou un rôle sur un dossier touche des centaines de projets. En code, le changement passe par une pull request et un
pulumi previewrelu avant d'être appliqué. - Dérive.
pulumi preview --refreshcompare l'état réel à l'état voulu et révèle ce qui a été modifié dans la console. - Audit. L'historique Git dit qui a demandé quoi et pourquoi ; les journaux d'audit ne disent que qui a appliqué.
- Project factory. Une équipe demande un projet en ajoutant quelques lignes de configuration ; le pipeline le crée avec son dossier, sa facturation, ses API, ses étiquettes et ses groupes, toujours de la même façon.
Pourquoi Pulumi en Python
- Licence libre. Le moteur, le SDK Python et le fournisseur
gcpsont sous Apache 2.0 ; Terraform est sous BSL. Le CLI, un état dans Cloud Storage et des règles exécutées localement couvrent tout ce qui suit sans service payant. - Même couverture que Terraform. Le fournisseur
pulumi_gcp(version 9.x) est construit à partir du fournisseur Terraformgoogle-beta: mêmes ressources, mêmes arguments, mêmes comportements, y compris les protections contre la suppression. - Le langage du reste du site. Boucles, fonctions, tests unitaires avec
pytest, paquets Python : une project factory est une boucle sur un dictionnaire. - Automation API. Le module
pulumi.automationpilote les stacks depuis un programme Python, par exemple un portail interne qui crée un projet sur demande sans passer par le CLI. - Quand rester en Terraform. Pour reprendre une fondation existante en HCL, ou pour déployer tel quel
terraform-example-foundationou FAST de Cloud Foundation Fabric, les deux fondations de référence de Google.
Découper en projets Pulumi et en stacks
Un projet Pulumi (un dossier avec son Pulumi.yaml) par couche, et une stack par environnement dans les couches qui en ont. Chaque couche publie ses sorties (pulumi.export), que la suivante lit par StackReference.
| Couche | Stacks | Contenu | Exécutée sous | Exporte |
|---|---|---|---|---|
| Amorçage | une seule | Projet prj-b-seed, bucket d'état, clé Cloud KMS, comptes de service des couches, pool Workload Identity Federation |
Un administrateur, une fois | Comptes de service, fournisseur WIF |
| Organisation | une seule | Dossiers, règles d'administration de l'organisation, IAM des groupes, puits agrégé, contacts essentiels | sa-org |
ID des dossiers |
| Réseau | dev, nonprod, prod |
Projet hôte et Shared VPC, sous-réseaux, DNS, connectivité hybride (voir Concevoir le réseau) | sa-reseau |
Réseau, sous-réseaux |
| Projets | dev, nonprod, prod |
Project factory : projets, API, rattachement au Shared VPC, budgets | sa-projets |
ID des projets |
| Applications | une par application et environnement | Cloud Run, bases, buckets, IAM de l'application | Compte de service de l'application | — |
# Couche projets : lire les sorties de la couche organisation (état dans Cloud Storage)
org = pulumi.StackReference("organization/org/org") # organization/PROJET/STACK
dossiers = org.require_output("dossiers") # {"dev": "folders/…", …}
- Rythme et rayon d'action. Les couches hautes changent rarement mais touchent tout ; les applications changent tous les jours. Les séparer réduit la durée de chaque
previewet le périmètre de chaque compte de service. - Un compte de service par couche, limité à son périmètre :
sa-reseaun'a de rôles que sur les projets hôtes,sa-projetssur les dossiers d'environnement et le compte de facturation (roles/billing.user). - Avec un état dans Cloud Storage, la partie organisation du nom de stack est toujours le mot
organization.
L'amorçage
Le bucket d'état et l'identité de la CI doivent exister avant le premier pulumi login : c'est le rôle de quelques commandes gcloud, lancées une fois par un administrateur, dans le dossier d'amorçage.
gcloud projects create prj-b-seed-XXXX --folder=FOLDER_BOOTSTRAP_ID
gcloud billing projects link prj-b-seed-XXXX --billing-account=BILLING_ACCOUNT_ID
gcloud services enable storage.googleapis.com cloudkms.googleapis.com iam.googleapis.com \
iamcredentials.googleapis.com sts.googleapis.com cloudresourcemanager.googleapis.com \
cloudbilling.googleapis.com orgpolicy.googleapis.com --project=prj-b-seed-XXXX
gcloud storage buckets create gs://BUCKET_ETAT --project=prj-b-seed-XXXX --location=EU \
--uniform-bucket-level-access --public-access-prevention
gcloud storage buckets update gs://BUCKET_ETAT --versioning
gcloud kms keyrings create pulumi --location=europe-west1 --project=prj-b-seed-XXXX
gcloud kms keys create etat --keyring=pulumi --location=europe-west1 --purpose=encryption \
--project=prj-b-seed-XXXX
La stack d'amorçage prend ensuite le relais : comptes de service des couches et leurs rôles, pool et fournisseur OIDC pour la CI (voir Déployer sans clé), et le bucket lui-même, repris par pulumi import et marqué protect=True. Les API de gestion (Resource Manager, Cloud Billing, Organization Policy, IAM) sont activées dans le projet d'amorçage, qui porte les comptes de service des pipelines.
État et secrets
pulumi login gs://BUCKET_ETAT
pulumi stack init prod \
--secrets-provider="gcpkms://projects/prj-b-seed-XXXX/locations/europe-west1/keyRings/pulumi/cryptoKeys/etat"
pulumi config set --secret motDePasseBase VALEUR # chiffré par la clé KMS, versionnable dans Git
Cloud Storage (gs://) |
Pulumi Cloud | |
|---|---|---|
| Hébergement | Un bucket de prj-b-seed, dans la région choisie |
Service SaaS de Pulumi |
| Verrou | Fichier de verrou par stack | Transactionnel |
| Reprise après incident | Versions d'objets du bucket ; pas de reprise transparente d'une mise à jour interrompue | Journal transactionnel des points de contrôle |
| Accès | IAM du bucket et de la clé KMS | Équipes et rôles dans Pulumi Cloud |
| Règles (policy packs) | Exécutées localement avec --policy-pack |
Appliquées à des groupes de stacks, packs prêts à l'emploi (éditions payantes) |
| Coût | Stockage et opérations Cloud Storage | Gratuit pour un usage individuel ou open source, éditions payantes pour les équipes |
- Secrets. Avec un état dans Cloud Storage, le fournisseur de secrets par défaut est une phrase de passe à distribuer.
gcpkms://chiffre à la place la clé de données de la stack par une clé Cloud KMS de typeENCRYPT_DECRYPT: la CI et les administrateurs n'ont besoin que deroles/cloudkms.cryptoKeyEncrypterDecryptersur la clé. Les valeurs chiffrées vivent dansPulumi.STACK.yaml, qui se versionne. Une clé détruite rend ces secrets et ceux de l'état illisibles. - Accès au bucket. Seuls les comptes de service des pipelines et un ou deux administrateurs : l'état contient les attributs de toutes les ressources. Pour les secrets applicatifs eux-mêmes, Secret Manager reste la bonne place ; Pulumi n'y crée que le secret, la valeur arrive hors du code.
Une project factory en Python
import pulumi
import pulumi_gcp as gcp
cfg = pulumi.Config()
org_id = cfg.require("orgId")
billing = cfg.require("billingAccount")
suffixe = cfg.require("suffixe") # 4 caractères aléatoires, fixés une fois
env = pulumi.get_stack() # dev, nonprod, prod
code = {"dev": "d", "nonprod": "n", "prod": "p"}[env]
dossier = gcp.organizations.Folder(
f"fldr-{env}",
display_name=f"fldr-{env}",
parent=f"organizations/{org_id}",
opts=pulumi.ResourceOptions(protect=True),
)
gcp.orgpolicy.Policy( # règle propre à l'environnement
f"lieux-{env}",
name=dossier.name.apply(lambda n: f"{n}/policies/gcp.resourceLocations"),
parent=dossier.name,
spec={"rules": [{"values": {"allowed_values": ["in:europe-locations"]}}]},
)
APPLIS = {
"facturation": ["run.googleapis.com", "sqladmin.googleapis.com"],
"catalogue": ["run.googleapis.com", "firestore.googleapis.com"],
}
projets = {}
for appli, apis in APPLIS.items():
projet = gcp.organizations.Project(
f"prj-{code}-{appli}",
project_id=f"prj-{code}-{appli}-{suffixe}",
name=f"{appli}-{env}",
folder_id=dossier.name,
billing_account=billing, # liaison au compte de facturation
labels={"application": appli, "environment": env, "envcode": code},
deletion_policy="PREVENT", # valeur par défaut, écrite pour la relecture
)
for api in apis:
gcp.projects.Service(
f"{appli}-{api.split('.')[0]}",
project=projet.project_id,
service=api,
disable_on_destroy=False,
)
projets[appli] = projet.project_id
pulumi.export("dossier", dossier.name)
pulumi.export("projets", projets)
- Ce qui manque volontairement : le rattachement au Shared VPC (
gcp.compute.SharedVPCServiceProject), les rôles des groupes sur chaque projet (gcp.projects.IAMMember), un budget par projet (gcp.billing.Budget, voir Facturation et budgets). Ils suivent le même modèle, dans la même boucle. - Au-delà de quelques projets, la liste des applications sort du code vers un fichier YAML par équipe, relu en pull request par l'équipe plateforme, ou vers un composant Pulumi (
pulumi.ComponentResource) réutilisé par chaque stack.
Règles avant l'application
Pulumi Policies (aussi appelé CrossGuard, paquet Python pulumi_policy) évalue chaque ressource pendant preview et up, avant tout appel à Google Cloud. Un pack écrit en Python s'applique à des programmes écrits dans n'importe quel langage.
# politiques/__main__.py — pulumi preview --policy-pack ./politiques
from pulumi_policy import EnforcementLevel, PolicyPack, ResourceValidationPolicy
def etiquettes(args, report_violation):
if args.resource_type == "gcp:organizations/project:Project":
manquantes = {"application", "environment"} - set(args.props.get("labels") or {})
if manquantes:
report_violation(f"Étiquettes manquantes : {', '.join(sorted(manquantes))}")
PolicyPack(
name="fondations",
enforcement_level=EnforcementLevel.MANDATORY,
policies=[ResourceValidationPolicy(
name="etiquettes-projet",
description="Chaque projet porte les étiquettes de gouvernance.",
validate=etiquettes,
)],
)
Les règles de Pulumi et les règles d'administration se complètent : les premières refusent tôt, dans la pull request, avec un message clair ; les secondes refusent à l'API, quel que soit l'outil ou la personne.
Pipeline
# .github/workflows/fondations.yml (extrait) : preview sur PR, up à la fusion
on:
pull_request:
push: { branches: [main] }
permissions: { contents: read, id-token: write, pull-requests: write }
jobs:
pulumi:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: google-github-actions/auth@v3
with:
workload_identity_provider: projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER
service_account: sa-projets@prj-b-seed-XXXX.iam.gserviceaccount.com
- uses: actions/setup-python@v7
with: { python-version: "3.13" }
- run: pip install -r requirements.txt
- uses: pulumi/actions@v7
with:
command: ${{ github.event_name == 'pull_request' && 'preview' || 'up' }}
stack-name: prod
cloud-url: gs://BUCKET_ETAT
policyPacks: politiques
comment-on-pr: true
github-token: ${{ secrets.GITHUB_TOKEN }}
- Preview sur la pull request, up à la fusion, sur une branche protégée ; jamais de
pulumi updepuis un poste pour les couches de la fondation. Pour la production, un environnement GitHub avec approbation obligatoire devant l'étapeup. - Deux identités. Un compte de service limité à la lecture des ressources pour les
preview, celui qui a les droits d'écriture réservé à l'upde la branche principale. - Dérive. Un job planifié lance
pulumi preview --refreshavecexpect-no-changes: trueet échoue dès qu'une ressource a été modifiée hors du code. - Sur Google Cloud, le même enchaînement tourne dans Cloud Build, sous le compte de service du déclencheur, sans fédération d'identité.
Pièges
- API activées à terme.
gcp.projects.Servicerend la main avant que l'API soit toujours utilisable dans un projet qui vient d'être créé. Faire dépendre les ressources du service (opts=pulumi.ResourceOptions(depends_on=[service])), et relancer si l'erreur « API has not been used in project » persiste. - Propagation IAM. Un rôle accordé est en général effectif en deux minutes, parfois sept ou plus : un
upqui crée un compte de service, lui donne un rôle et l'utilise aussitôt peut échouer en 403 puis réussir à la relance. - Deux protections, deux niveaux.
protect=Truefait refuser par Pulumi toute suppression ou remplacement de la ressource (le lever demandepulumi state unprotect). Les protections du fournisseur agissent en plus :deletion_policy="PREVENT"par défaut sur un projet,deletion_protection=Truepar défaut sur un dossier. À poser sur les dossiers, les projets hôtes, le bucket d'état et les clés KMS. - Renommer, c'est remplacer. Changer le nom logique d'une ressource dans le code (le premier argument) ou un argument immuable comme
project_idfait supprimer puis recréer la ressource. Pour un renommage dans le code,aliasesgarde le lien avec l'existant. - Supprimer un projet. Avec
deletion_policy="DELETE", le projet part en suppression réversible pendant trente jours, compte encore dans le quota et son ID n'est jamais réutilisable.ABANDONle retire de l'état sans le supprimer. - Quotas de projets. Le compte de service de la project factory crée tous les projets : c'est son quota de création, ou celui de l'organisation, qui s'épuise, ainsi que le nombre de projets liés au compte de facturation. Demander les augmentations avant d'ouvrir la factory aux équipes.
auto_create_network=False. Le fournisseur laisse Google créer le réseaudefaultpuis le supprime, en laissant l'API Compute Engine activée. La règle d'administrationcompute.skipDefaultNetworkCreationévite sa création même.
Alternatives en logiciel libre
- OpenTofu (MPL 2.0) avec terraform-example-foundation (Apache 2.0) : la fondation de référence de Google, en étapes numérotées (
0-bootstrapà5-app-infra), à déployer telle quelle plutôt qu'à réécrire en Pulumi. - Cloud Foundation Fabric et sa fondation FAST (Apache 2.0) : modules HCL minces et étapes d'organisation, de réseau et de project factory pilotées par des fichiers YAML, à cloner dans ses propres dépôts.
- Crossplane (Apache 2.0) : décrit la fondation en ressources Kubernetes réconciliées en continu, et offre aux équipes des « projets » maison par ses compositions.
- SOPS (MPL 2.0) : chiffre des fichiers de configuration YAML ou JSON avec une clé Cloud KMS, pour versionner les secrets d'une IaC qui n'a pas de fournisseur de secrets intégré.
- Open Policy Agent et Conftest (Apache 2.0) : règles Rego évaluées sur la sortie JSON d'un plan ou d'un
preview, là où Pulumi Policies utilise Python.