Pulumi Google Cloud (GCP) Provider

9.19.0 · active · verified Mon Apr 13

The `pulumi-gcp` Python package provides a robust interface for defining, deploying, and managing Google Cloud Platform resources using infrastructure-as-code principles. It leverages the Pulumi CLI and Python language to offer programmatic control over GCP services. Currently at version 9.19.0, it is actively maintained with frequent releases that often include updates to align with upstream Terraform provider changes and new GCP features.

Warnings

breaking Pulumi GCP Provider v9.0.0 introduced several breaking changes. Key changes include: `gcp.alloydb.Cluster` now defaults `deletionProtection` to `true`. The import behavior for `gcp.storage.Bucket` labels changed; labels are no longer directly imported to the `labels` field but appear in `effectiveLabels` and must be explicitly set. `gcp.tpu.Node` was removed in favor of `gcp.tpu.V2Vm`. Several resource fields received increased validation. `gcp.storage.Notification` topic format requires a full resource path.
Fix: Review the official 'GCP 9.0 Migration Guide' on the Pulumi Registry. Explicitly set `deletionProtection` where needed. Manually manage `gcp.storage.Bucket` labels post-import. Migrate `gcp.tpu.Node` to `gcp.tpu.V2Vm`. Update resource configurations to comply with new validation rules and format requirements.
breaking Pulumi GCP Provider v8.0.0 introduced changes primarily related to deletion protection and labeling. The `deletionProtection` field was added with a default of `true` for several resources (e.g., `gcp.cloudrunv2.Service`, `gcp.organizations.Project`) to prevent accidental deletion. The `template.containers[].ports` field in `gcp.cloudrunv2.Service` changed from a list to an object type. A new default provisioning label `goog-pulumi-provisioned` is now added to all resources, appearing in `pulumiLabels` and `effectiveLabels` outputs.
Fix: Consult the 'GCP 8.0 Migration Guide'. Explicitly configure `deletionProtection` to `false` if you intend for resources to be destroyable. Adjust `cloudrunv2.Service` port configurations. To opt out of the default label, set `pulumi config set gcp:addPulumiAttributionLabel false`.
breaking Pulumi GCP Provider v7.0.0 introduced a significant rework of label handling. The `labels` field became non-authoritative, managing only the labels defined in your Pulumi configuration. New output-only fields `pulumiLabels` (merges config labels with global defaults) and `effectiveLabels` (all labels on the GCP resource) were added. This can lead to unexpected diffs on upgrade, but these are typically safe 'output-only' changes.
Fix: Refer to the 'GCP 7.0 Migration Guide'. Understand the new label semantics: if you rely on all GCP-managed labels appearing in your Pulumi state, you now need to inspect `effectiveLabels`. While direct label changes often don't require code modification for Python, be aware of the new output fields and their impact on diffs.
gotcha The Pulumi GCP provider relies on the Google Cloud SDK (`gcloud CLI`) being installed and authenticated on the machine where Pulumi commands are run. Lack of proper authentication (e.g., `gcloud auth application-default login`) or incorrect project configuration can lead to authentication errors or resources being deployed to an unintended project.
Fix: Ensure `gcloud CLI` is installed and updated. Run `gcloud auth application-default login` to authenticate. Set the target GCP project using `pulumi config set gcp:project <YOUR_PROJECT_ID>` or by providing it as an argument to resources where applicable.
gotcha Unexpected resource recreation or 'perpetual diffs' can occur, especially after provider updates or due to subtle API changes in GCP's underlying services. This can result in `pulumi up` always showing changes even if the user's code has not changed.
Fix: Check the Pulumi GCP GitHub Issues for known bugs or 'awaiting-upstream' issues that match your symptoms. Consult migration guides for recent major versions, as 'spurious diffs' fixes are often implemented. If a resource perpetually updates, inspect the `pulumi preview --diff` output carefully to understand the exact difference Pulumi perceives. Sometimes, refreshing the state (`pulumi refresh`) can resolve minor inconsistencies.

Install

pip install pulumi_gcp Install with pip
pulumi new gcp-python Create new Pulumi GCP Python project

Imports

gcp
```
import pulumi_gcp as gcp
```
The Pulumi GCP provider is installed as `pulumi_gcp` and conventionally aliased as `gcp` for brevity and clarity when referencing resources.
storage
```
from pulumi_gcp import storage
```
Specific modules for resource types (e.g., `storage`, `compute`, `sql`) are imported from `pulumi_gcp`.

Quickstart

This quickstart program creates a Google Cloud Storage bucket. Before running, ensure you have the Pulumi CLI installed, are authenticated to GCP via `gcloud auth application-default login`, and have run `pulumi new gcp-python` to set up a project. You may need to set the `gcp:project` configuration value using `pulumi config set gcp:project <YOUR_GCP_PROJECT_ID>` or set the `GCP_PROJECT_ID` environment variable.

import pulumi
from pulumi_gcp import storage
import os

# Configure the GCP project ID (replace with your project ID or set via pulumi config)
# pulumi config set gcp:project my-gcp-project-id
project_id = os.environ.get('GCP_PROJECT_ID') or pulumi.Config('gcp').get('project')

# Create a GCP Storage Bucket
# Note: Bucket names must be globally unique.
bucket = storage.Bucket(
    'my-unique-bucket-name',
    project=project_id, # Ensure project_id is configured or passed
    location='US-CENTRAL1', # Specify a region or multi-region
    uniform_bucket_level_access=True # Recommended best practice for security
)

# Export the bucket's self_link and URL
pulumi.export('bucket_self_link', bucket.self_link)
pulumi.export('bucket_url', bucket.url)

view raw JSON →