Skip to main content

Search the Dev Center

Search tutorials, templates, examples, and more.

Container image pipeline with Pulumi Delivery on Google Cloud

This example lives in the pulumi/examples repository. Check out just this directory to use it:

Get started with this example
git clone --filter=blob:none --sparse https://github.com/pulumi/examples pulumi-examples
git -C pulumi-examples sparse-checkout set gcp-ts-delivery-image-build
cd pulumi-examples/gcp-ts-delivery-image-build

This example uses Pulumi Delivery to build a container image on every push, push it to Google Artifact Registry, and deploy it to Cloud Run in a beta stage. The image is built once: the beta stage deploys the exact image the build stage pushed, by digest, then checks that the service answers.

The pipeline in Pulumi Cloud: a build stage runs the image stack, then the beta stage runs the beta stack and a check Job

The example has three Pulumi projects, all in TypeScript:

  • pipeline/ defines the pipeline: a GitHub source, a build stage and a beta stage. Delivery keeps the pipeline itself up to date from this directory. In the beta stage, a Job runs pipeline/check-url.sh, which calls the service until it answers.
  • image/ creates an Artifact Registry repository, then builds app/ and pushes it, tagged with the commit. It exports the image reference, pinned by digest.
  • beta/ deploys that image to a public Cloud Run service and exports its URL.

Every stack authenticates to Google Cloud through Pulumi ESC with OIDC, so no long-lived credentials are stored anywhere.

Prerequisites#

  1. Install Pulumi, version 3.277.0 or later
  2. Install Node.js, version 26 or later
  3. A Pulumi Cloud organization with Pulumi Delivery available
  4. A Google Cloud project with the Artifact Registry and Cloud Run APIs enabled
  5. A GitHub repository that holds this example, for example a fork of pulumi/examples

Setting up the pipeline#

  1. Give Pulumi Cloud access to your repository. Install the Pulumi GitHub App on your GitHub organization if it isn’t installed yet, then check that it can read the repository that holds this example: in Pulumi Cloud, go to Settings > Version control, open the GitHub installation, choose Configure repository access, and add the repository on GitHub.

  2. Create an ESC environment that logs in to Google Cloud with OIDC. Follow Configuring OIDC for Google Cloud, then expose the credentials to the programs:

    values:
    gcp:
    login:
    fn::open::gcp-login:
    project: <project-number>
    oidc:
    workloadPoolId: <pool-id>
    providerId: <provider-id>
    serviceAccount: <service-account-email>
    environmentVariables:
    GOOGLE_PROJECT: <project-id>
    GOOGLE_OAUTH_ACCESS_TOKEN: ${gcp.login.accessToken}

    GOOGLE_PROJECT must be the project ID, not the project number: Artifact Registry rejects project numbers. The service account needs these roles in the project: roles/artifactregistry.admin to create the repository and push the image, roles/run.admin to deploy the Cloud Run service and make it public, and roles/iam.serviceAccountUser on the service’s runtime account, which is the Compute Engine default service account because the beta stack doesn’t set one.

    The service account trusts each ESC environment by its exact name. If you reuse a workload identity pool and service account that already exist, grant this environment’s subject roles/iam.workloadIdentityUser on the service account, following Configuring OIDC for Google Cloud.

  3. Create the image and beta stacks, and import the environment into each one. Delivery only updates stacks that already exist.

    The project names in the three Pulumi.yaml files, the stack references in pipeline/index.ts and the Artifact Registry repository ID in image/index.ts are fixed. A second deployment in the same Pulumi organization, or in the same Google Cloud project and location, must change them first, or it fails with a 409 “already exists” error. Use your names in the commands below.

    Terminal window
    cd image
    pulumi stack init <org>/gcp-ts-delivery-image-build-image/image
    pulumi config env add <project>/<environment> --yes
    cd ../beta
    pulumi stack init <org>/gcp-ts-delivery-image-build-beta/beta
    pulumi config env add <project>/<environment> --yes
    cd ..
  4. Commit the two stack files. Delivery runs every program from your repository, so each stack’s Pulumi.<stack>.yaml must be in git. In a fork of pulumi/examples, these files are ignored, so add them with -f:

    Terminal window
    git add -f image/Pulumi.image.yaml beta/Pulumi.beta.yaml
    git commit -m "Add stack files for the Delivery example"
    git push
  5. Create the pipeline stack, point it at your repository, and tell Delivery where the pipeline program lives, then commit and push everything:

    Terminal window
    cd pipeline
    pulumi install
    pulumi stack init <org>/gcp-ts-delivery-image-build-pipeline/pipeline
    pulumi config set repository <owner>/<name>
    pulumi config set branch <branch>
    pulumi config set path <path>
    pulumi config set location <location>
    pulumi config set --path 'delivery:source.url' https://github.com/<owner>/<name>
    pulumi config set --path 'delivery:source.branch' <branch>
    pulumi config set --path 'delivery:source.directory' <path>/pipeline
    git add -f Pulumi.pipeline.yaml
    git commit -m "Point the Delivery pipeline at this repository"
    git push

    repository is your repository, as <owner>/<name>, and branch is the branch to watch. location is the Artifact Registry and Cloud Run location, for example europe-west2. path is this example’s directory within the repository, for example gcp-ts-delivery-image-build. The example must live in a subdirectory: the pipeline starts runs for pushes that match <path>/**. With the example at the repository root (path of .), pushes update the pipeline but start no run.

    pulumi install installs the pipeline’s dependencies, including the Delivery SDK, @pulumi/delivery, from npm.

  6. Register the pipeline:

    Terminal window
    pulumi delivery register

    Registration previews an update of the pipeline stack and asks you to confirm it. It ends with warning: update has awaiting resources. That is expected: the first stage waits for a run. For the same reason, the pipeline stack’s update history shows the update as failed. Registration fails if the checkout has uncommitted changes or the commit is not on the branch in delivery:source.

  7. Let the pipeline open the ESC environment. Registration creates a service principal, named “Delivery gcp-ts-delivery-image-build-pipeline pipeline”, and gives it write access to the pipeline, image and beta stacks. The stacks run as that principal, so it also needs to open the environment they import. In Pulumi Cloud, open the environment, go to Settings, then Access, choose Add Principal, then Service Principal, pick the pipeline’s service principal and give it Environment Open.

    Or from the command line:

    Terminal window
    ORG=<org> # your Pulumi organization
    ENV_PROJECT=<project> # the environment you created above
    ENV_NAME=<environment>
    PIPELINE="Delivery gcp-ts-delivery-image-build-pipeline pipeline"
    # Every call here is scoped to the organization.
    org_api() { local op=$1; shift; pulumi api "$op" -F orgName="$ORG" "$@"; }
    # The access calls name the kind of entity in a context object.
    type_wrap() { printf '{"__type":"%s"}' "$1"; }
    # The service principal Delivery generated for the pipeline, by name.
    # Delivery cuts names longer than 64 characters, so a cut-off name also matches.
    LOGIN=$(org_api ListOrganizationMembers -F type=service-principal \
    | jq -r --arg name "$PIPELINE" '.members[].user | select(.servicePrincipalKind == "delivery" and (.name == $name or ((.name | length) == 64 and (.name as $n | $name | startswith($n))))) | .githubLogin')
    [ -n "$LOGIN" ] || { echo "No service principal named: $PIPELINE" >&2; }
    # The built-in permission set that lets a principal open an environment.
    OPEN_ID=$(org_api ListRolesByOrgIDAndUXPurpose -F uxPurpose=set \
    | jq -r '.roles[] | select(.name == "Environment Open") | .id')
    # Let the pipeline open the environment.
    ENV_ID=$(org_api GetEnvironmentMetadata_esc_environments -F projectName=$ENV_PROJECT -F envName=$ENV_NAME \
    | jq -r .id)
    [ -n "$LOGIN" ] && org_api UpdateEntityAssignment -F id=$ENV_ID -F "context=$(type_wrap PermissionExpressionEnvironment)" \
    -F userId=$LOGIN -F permissionSetId=$OPEN_ID
  8. Start the first run: push a change to a file in this example, or choose Start a run on the pipeline in Pulumi Cloud, under Delivery in your organization. Registration does not start a run.

  9. Watch the run in Pulumi Cloud. The build stage pushes the image, and the beta stage deploys it to Cloud Run and checks that it answers. The run records the app’s URL as the beta-url artifact of the release. From now on, every push that changes files in this example starts a new run.

Cleaning up#

Destroy the stacks in reverse order, then remove them:

Terminal window
cd pipeline && pulumi destroy && pulumi stack rm
cd ../beta && pulumi destroy && pulumi stack rm
cd ../image && pulumi destroy && pulumi stack rm

Destroying the beta stack deletes the Cloud Run service. Destroying the image stack deletes the Artifact Registry repository and every image in it. Destroying the pipeline stack removes the pipeline’s service principal and its access to the environment.

If you created the ESC environment only for this example, remove it with pulumi env rm <project>/<environment>, along with any Google Cloud OIDC resources you created for it.

Related

The infrastructure platform for humans and agents.