Pulumi GCP en Python
Commandes du CLI Pulumi (version 3.264) et appels du fournisseur pulumi_gcp (version 9.37), construit à partir du fournisseur Terraform google-beta. Imports supposés : import pulumi, import pulumi_gcp as gcp.
CLI : projet, état, configuration
| Objectif | Syntaxe | Résultat |
|---|---|---|
| Créer un projet Python pour GCP | pulumi new gcp-python --name reseau --stack dev |
Pulumi.yaml, __main__.py, requirements.txt et environnement virtuel |
| Garder l'état dans Cloud Storage | pulumi login gs://BUCKET_ETAT |
Un fichier d'état par stack dans le bucket ; pulumi login --local pour ~/.pulumi |
| Créer une stack, secrets par Cloud KMS | pulumi stack init prod --secrets-provider="gcpkms://projects/PROJECT_ID/locations/REGION/keyRings/KR/cryptoKeys/KEY" |
Sans ce fournisseur, une phrase de passe à distribuer (PULUMI_CONFIG_PASSPHRASE) |
| Changer de stack | pulumi stack select prod, pulumi stack ls |
La stack active est rappelée par pulumi stack |
| Fixer projet et région du fournisseur | pulumi config set gcp:project PROJECT_ID, pulumi config set gcp:region REGION |
Écrit dans Pulumi.STACK.yaml ; valeurs par défaut de toutes les ressources |
| Valeur de configuration de l'application | pulumi config set tailleMachine e2-medium |
Lue par pulumi.Config().require("tailleMachine") |
| Valeur secrète | pulumi config set --secret motDePasse VALEUR |
Chiffrée dans Pulumi.STACK.yaml, versionnable ; lue par require_secret |
| Valeur structurée | pulumi config set --path 'reseau.cidr' 10.0.0.0/20 |
Lue par require_object("reseau") |
| Voir les changements prévus | pulumi preview --diff |
Création, modification, remplacement par ressource ; rien n'est appliqué |
| Détecter la dérive | pulumi preview --refresh --expect-no-changes |
Code de sortie non nul si l'état réel s'écarte du code : un contrôle de CI |
| Appliquer | pulumi up ; en CI pulumi up --yes --skip-preview |
Crée, modifie ou remplace les ressources |
| Cibler une ressource | pulumi up --target 'URN' (URN de pulumi stack --show-urns) |
Seule cette ressource est traitée ; ajouter --target-dependents au besoin |
| Forcer un remplacement | pulumi up --target-replace 'URN' |
Supprime puis recrée (ou l'inverse) la ressource |
| Relire l'état réel | pulumi refresh --yes |
Met l'état à jour d'après le cloud, sans toucher aux ressources |
| Tout détruire | pulumi destroy --yes (--exclude-protected pour épargner les ressources protégées) |
Ressources supprimées ; --remove supprime aussi la stack |
| Lire une sortie | pulumi stack output url, pulumi stack output --json --show-secrets |
Valeurs exportées par pulumi.export |
| Reprendre une ressource existante | pulumi import gcp:storage/bucket:Bucket etat BUCKET_ETAT |
Ajoute la ressource à l'état, marquée protégée, et affiche le code Python correspondant |
| Oublier une ressource sans la supprimer | pulumi state delete 'URN' |
Sort de l'état ; la ressource reste dans le cloud |
| Débloquer une stack après une interruption | pulumi cancel |
Libère le verrou ; puis pulumi refresh pour réaligner l'état |
Programme : ressources et options
| Objectif | Syntaxe | Résultat |
|---|---|---|
| Lire la configuration | cfg = pulumi.Config() ; cfg.require("region"), cfg.get_int("replicas") or 1, cfg.require_secret("motDePasse") |
require_secret renvoie un Output secret, masqué partout |
| Lire la configuration du fournisseur | gcp.config.project, gcp.config.region |
Valeurs de gcp:project et gcp:region |
| Nom de la stack, du projet Pulumi | pulumi.get_stack(), pulumi.get_project() |
Pour nommer et étiqueter selon l'environnement |
| Protéger contre la suppression | opts=pulumi.ResourceOptions(protect=True) |
up et destroy refusent de supprimer la ressource |
| Imposer un ordre | opts=pulumi.ResourceOptions(depends_on=[api_run]) |
Pour une dépendance que les entrées ne portent pas (activation d'API avant usage) |
| Rattacher à un composant | opts=pulumi.ResourceOptions(parent=self) |
Arborescence lisible, options héritées |
| Travailler dans un autre projet | autre = gcp.Provider("prod", project="PROJECT_ID_2", region="REGION") puis opts=pulumi.ResourceOptions(provider=autre) |
Un fournisseur par projet ou par compte de service (impersonate_service_account=) |
| Étiquettes sur toutes les ressources | gcp.Provider(..., default_labels={"env": "prod", "equipe": "data"}) |
Fusionnées avec les labels de chaque ressource |
| Ignorer un champ modifié ailleurs | opts=pulumi.ResourceOptions(ignore_changes=["template.containers[0].image"]) |
Le déploiement applicatif change l'image sans que up la remette |
| Remplacer en supprimant d'abord | opts=pulumi.ResourceOptions(delete_before_replace=True) |
Nécessaire quand le nom est unique (compte de service, bucket nommé) |
| Renommer sans recréer | opts=pulumi.ResourceOptions(aliases=[pulumi.Alias(name="ancien-nom")]) |
La ressource garde son identité dans l'état |
| Garder la ressource à la suppression | opts=pulumi.ResourceOptions(retain_on_delete=True) |
Retirée de l'état, conservée dans le cloud |
Sorties (Output)
| Objectif | Syntaxe | Résultat |
|---|---|---|
| Transformer une valeur calculée | bucket.url.apply(lambda u: f"{u}/data") |
Nouvel Output ; la fonction s'exécute quand la valeur est connue |
| Combiner plusieurs sorties | pulumi.Output.all(sa.email, projet.project_id).apply(lambda a: f"{a[0]} dans {a[1]}") |
Un seul Output à partir de plusieurs |
| Concaténer des chaînes | pulumi.Output.concat("serviceAccount:", sa.email) |
Raccourci pour construire un membre IAM |
| Formater | pulumi.Output.format("gs://{0}/in", bucket.name) |
Équivalent de str.format |
| Marquer comme secret | pulumi.Output.secret(valeur) |
Chiffré dans l'état, masqué dans les journaux |
| Publier une sortie | pulumi.export("url", service.uri) |
Lisible par pulumi stack output et par StackReference |
| Lire les sorties d'une autre stack | ref = pulumi.StackReference("organization/reseau/prod") ; ref.require_output("subnet_id") |
Avec un état Cloud Storage, l'organisation est toujours organization |
str(bucket.name)ou un f-string sur unOutputproduit un texte d'avertissement, pas la valeur : passer parapply,concatouformat. Et ne jamais créer une ressource dans unapply: elle n'apparaît pas danspreview.
Ressources courantes
| Objectif | Syntaxe | Résultat |
|---|---|---|
| Activer une API | gcp.projects.Service("run", service="run.googleapis.com", disable_on_destroy=False) |
API laissée active si la ressource est retirée du code |
| Bucket | gcp.storage.Bucket("data", location="EU", uniform_bucket_level_access=True, public_access_prevention="enforced", versioning={"enabled": True}) |
Nom = nom logique + suffixe aléatoire, sauf name= explicite |
| Compte de service | gcp.serviceaccount.Account("app", account_id="sa-app", display_name="Application") |
.email pour les liaisons IAM |
| Rôle sur le projet | gcp.projects.IAMMember("app-bq", project=PROJECT_ID, role="roles/bigquery.dataViewer", member=sa.member) |
Ajoute une liaison sans toucher aux autres ; IAMBinding et IAMPolicy sont exclusifs |
| Rôle sur un bucket | gcp.storage.BucketIAMMember("lecture", bucket=bucket.name, role="roles/storage.objectViewer", member=sa.member) |
Droit limité à ce bucket |
| Service Cloud Run | gcp.cloudrunv2.Service("api", location=REGION, template={"containers": [{"image": IMAGE}], "service_account": sa.email}, ingress="INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER") |
.uri : URL du service ; deletion_protection vaut True par défaut |
| Autoriser l'appel d'un service Cloud Run | gcp.cloudrunv2.ServiceIamMember("invoker", name=svc.name, location=REGION, role="roles/run.invoker", member=appelant.member) |
Appel authentifié par l'identité de l'appelant |
| Réseau VPC en mode personnalisé | gcp.compute.Network("vpc", auto_create_subnetworks=False, routing_mode="GLOBAL") |
Aucun sous-réseau créé automatiquement |
| Sous-réseau | gcp.compute.Subnetwork("app", network=vpc.id, region=REGION, ip_cidr_range="10.10.0.0/20", private_ip_google_access=True, secondary_ip_ranges=[{"range_name": "pods", "ip_cidr_range": "10.20.0.0/16"}]) |
Plage secondaire pour les pods GKE |
| Instance Cloud SQL | gcp.sql.DatabaseInstance("pg", database_version="POSTGRES_16", region=REGION, settings={"edition": "ENTERPRISE", "tier": "db-custom-2-7680", "availability_type": "REGIONAL", "ip_configuration": {"ipv4_enabled": False, "private_network": vpc.id}}) |
Sans edition, PostgreSQL 16 et plus passe en ENTERPRISE_PLUS, qui refuse les types db-custom-* ; deletion_protection vaut True par défaut ; accès privé à préparer sur le VPC |
| Base et utilisateur Cloud SQL | gcp.sql.Database("app", instance=pg.name), gcp.sql.User("app", instance=pg.name, password=cfg.require_secret("motDePasse")) |
Mot de passe secret dans l'état |
| Dataset BigQuery | gcp.bigquery.Dataset("ventes", dataset_id="ventes", location="EU", default_table_expiration_ms=90 * 24 * 3600 * 1000) |
dataset_id sans tiret ; tables expirées après 90 jours par défaut ; la suppression échoue si des tables existent, sauf delete_contents_on_destroy=True |
| Secret (sans sa valeur) | gcp.secretmanager.Secret("db", secret_id="db-password", replication={"auto": {}}) |
La valeur arrive hors du code, par la console ou la CI |
| Dépôt Artifact Registry | gcp.artifactregistry.Repository("images", repository_id="images", format="DOCKER", location=REGION) |
Adresse REGION-docker.pkg.dev/PROJECT_ID/images |
Composants et tests
class ServiceApp(pulumi.ComponentResource):
def __init__(self, name: str, image: str, region: str, opts=None):
super().__init__("memoria:app:ServiceApp", name, None, opts)
enfant = pulumi.ResourceOptions(parent=self)
self.sa = gcp.serviceaccount.Account(f"{name}-sa", account_id=f"sa-{name}", opts=enfant)
self.service = gcp.cloudrunv2.Service(
f"{name}-run", location=region, deletion_protection=False,
template={"containers": [{"image": image}], "service_account": self.sa.email},
opts=enfant,
)
self.register_outputs({"uri": self.service.uri})
app = ServiceApp("catalogue", image="REGION-docker.pkg.dev/PROJECT_ID/images/catalogue:1.0", region="REGION")
pulumi.export("uri", app.service.uri)
# test_infra.py — lancé par pytest, sans appel au cloud
import pulumi
class Mocks(pulumi.runtime.Mocks):
def new_resource(self, args: pulumi.runtime.MockResourceArgs):
return f"{args.name}-id", args.inputs # ID et état simulés
def call(self, args: pulumi.runtime.MockCallArgs):
return {}, None
pulumi.runtime.set_mocks(Mocks(), project="test", stack="dev", preview=False)
import infra # module du programme, importé après set_mocks
@pulumi.runtime.test
def test_bucket_prive():
def verifier(args):
pap, ubla = args
assert pap == "enforced" and ubla
return pulumi.Output.all(infra.bucket.public_access_prevention,
infra.bucket.uniform_bucket_level_access).apply(verifier)
Mettre
pulumi preview --diffdans la CI de chaque pull request etpulumi up --yesaprès fusion : la revue porte sur le plan, pas seulement sur le code (voir Construire les fondations en code).
Contexte : Choisir un outil d'IaC, Construire les fondations en code, Bonnes pratiques IAM, Concevoir le réseau.