Managing your delivery pipeline

This page describes how you can manage your delivery pipelines, including the following tasks:

  • Viewing information about pipelines, releases, rollouts, and targets
  • Using notifications with your pipelines
  • Approving and rejecting rollouts

Before you begin

This page assumes you have one or more Google Cloud Deploy delivery pipelines in use or ready to be put into use.

Because Google Cloud Deploy uses Skaffold to render and deploy manifests, if you're not familiar with Skaffold you can learn the basics by trying the Skaffold Quickstart.

Viewing and editing delivery pipelines

You can see a list of all your Google Cloud Deploy delivery pipelines for all your projects. You can list them from the command line, and you can view the list in Google Cloud Console.

Viewing a list of delivery pipelines

Console

In the Cloud Console, navigate to the Google Cloud Deploy Delivery pipelines page to view of list of your available delivery pipelines.

Open the Delivery pipelines page

The list of delivery pipelines is shown in Cloud Console.

Delivery pipelines page in Google Cloud Console, showing list of pipelines

Delivery pipelines that have been configured but not registered with the Google Cloud Deploy service are not shown.

gcloud

The following command returns a list of all delivery pipelines in the current project.

gcloud beta deploy delivery-pipelines list

You should see an output similar to the following:

$ gcloud beta deploy delivery-pipelines list --region=$REGION
---
createTime: '2021-05-03T16:03:11.687046682Z'
description: main application pipeline
etag: a9721c6cf665fcc7
name: projects/try-cd-dev6/locations/us-central1/deliveryPipelines/my-demo-app-1
serialPipeline:
  stages:
  - targetId: qsdev
  - targetId: qsprod
uid: f0b8148d5ddf4071964803e278acb1da
updateTime: '2021-05-03T16:03:12.780948171Z'

As shown in this output, the command returns only one pipeline, with two targets.

Viewing delivery-pipeline details

For an existing delivery pipeline, you can view pipeline details, including pipeline metadata and the progression of targets.

Console

  1. In the Cloud Console, navigate to the Google Cloud Deploy Delivery pipelines page to view of list of your available delivery pipelines.

    Open the Delivery pipelines page

    The list of delivery pipelines is shown in Cloud Console.

    List of delivery
pipelines

    Delivery pipelines that have been configured but not registered with the Google Cloud Deploy service are not shown.

  2. Click the Name of the delivery pipeline whose details you want to view.

Cloud Console shows a visualization of the delivery pipeline, as well as pipeline metadata and status:

Delivery pipeline
details page, with visualization of the pipeline

You can click the Targets tab to see details of the targets that this delivery pipeline uses:

Delivery pipeline
details page, with visualization of the pipeline

gcloud

The following command returns details of the specified delivery pipelines:

gcloud beta deploy delivery-pipelines describe <pipeline-name> --region=<region>

You should see an output similar to the following:

$ gcloud beta deploy delivery-pipelines describe my-demo-app-1 --region=us-central1
Delivery Pipeline:
  createTime: '2021-05-03T16:03:11.687046682Z'
  description: main application pipeline
  etag: a9721c6cf665fcc7
  name: projects/try-cd-dev6/locations/us-central1/deliveryPipelines/my-demo-app-1
  serialPipeline:
    stages:
    - targetId: qsdev
    - targetId: qsprod
  uid: f0b8148d5ddf4071964803e278acb1da
  updateTime: '2021-05-03T16:03:12.780948171Z'
Targets:
- Target: qsdev
- Target: qsprod

As shown in this output, the command returns the details for the one pipeline. Note the two stages and the two corresponding Targets.

Rolling back a deployment

To roll back your deployed application using Google Cloud Deploy is to roll out the last successfully deployed release to the indicated target.

When you roll back a target, Google Cloud Deploy creates a new rollout resource, which includes a reference to the good rollout resource you're rolling back to.

To roll back, run the following command from the directory containing your delivery pipeline:

gcloud beta deploy targets rollback TARGET_NAME \
   --delivery-pipeline=PIPELINE_NAME \
   --release=RELEASE_NAME \
   --rollout-id=ROLLOUT_ID

In the above command, release and rollout-id are optional.

Use release to identify a specific release to roll back to. If you omit this option, then Google Cloud Deploy uses the last known good release to the specified target.

Use rollout-id to assign an identifier to the generated rollout. If you omit this, Google Cloud Deploy generates an id for the generated rollout.

Rolling back even further

You can roll back manually to an earlier release than the last successfully deployed one.

Simply run gcloud beta deploy releases promote with the earlier release and include the--to-target option set to the target in which you want to roll back your release.

Using notifications with your delivery pipeline

Google Cloud Deploy uses Pub/Sub to publish notifications for two purposes:

  • To let you integrate Google Cloud Deploy with third-party tools and other Google tools, such as tools for workflow ticketing or test infrastructure.

  • To extend Google Cloud Deploy with supplemental business logic.

See Subscribing to Google Cloud Deploy notifications for further instructions.

Managing approvals for a delivery pipeline

You can require approval for any target, and you can approve or reject releases into that target.

Approvals can be managed programmatically by integrating your workflow management system (such as ServiceNow), or other system, with Google Cloud Deploy using Pub/Sub and the Google Cloud Deploy API.

Requiring approval

To require approval on any target, set requireApproval to true in the target configuration:

     apiVersion: deploy.cloud.google.com/v1beta1
     kind: Target
     metadata:
      name:
     description:
     requireApproval: true

See Delivery pipeline configuration for further details.

When a rollout is pending approval, users or systems that subscribe to the cd-approvals Pub/Sub topic receive notification and can then approve or reject the rollout.

Approving or rejecting a rollout

Any user or service account with the role roles/clouddeploy.approver can approve a Google Cloud Deploy rollout to a target that requires approval.

Your integrated workflow management system, having received an approval-required notification using service notifications, can approve or reject the rollout using the Google Cloud Deploy API.

Approving or rejecting manually

Console

  1. In the Cloud Console, navigate to the Google Cloud Deploy Delivery pipelines page to view of list of your available delivery pipelines.

    Open the Delivery pipelines page

    The list of delivery pipelines is shown in Cloud Console. Delivery pipelines that have been configured but not registered with the Google Cloud Deployservice are not shown.

  2. Click the name of the delivery pipeline.

    The pipeline visualization is shown. If approval is pending, and if you have the roles/clouddeploy.approver role, or equivalent permissions, the visualization includes a Review link.

    Delivery pipeline
visualization, with approval pending

  3. Click Review.

    A list is shown of rollouts pending approval.

    Rollouts for this
pipeline, with approval pending

  4. Click Review.

    The Approve rollout screen is shown.

    Details of the
rollout with approval pending

    The Manifest diff tab shows any changes to the rendered manifest from the currently deployed version (if any) to the one you're now approving (or rejecting).

  5. Click Approve or Reject.

    If you approve, your application is deployed into the target. If you reject, the application is not deployed, and can't be approved later unless re-promoted.

gcloud

A user with the roles/clouddeploy.approver role can manually approve or reject a rollout. To approve:

gcloud beta deploy rollouts approve rollout-name --delivery-pipeline=pipeline-name

To reject:

gcloud beta deploy rollouts reject rollout-name --delivery-pipeline=pipeline-name

Changing a delivery pipeline that's already in use

To change your delivery pipeline, simply edit the delivery-pipeline definition.

However, you might not see the results you expect, because of how Google Cloud Deploy treats the relationship between pipelines and targets and the releases they manage.

Each release and rollout resource is permanently associated with the pipeline as it was defined when the release was created. If you change a delivery pipeline configuration (including target definitions) after a release is created, that release is now mismatched from the definitions.

Preserving resources in this way ensures they function consistently across the targets and they're not disrupted by configuration changes. However this behavior might not be what you intend, in which case you can create a new release to deploy using the updated pipeline.

Google Cloud Deploy returns warnings if there's such a mismatch and you try to perform certain actions, such as promote the release.

For more information, see Pipeline instances per release.

Deleting delivery pipelines

If you have a delivery pipeline without any subresources (releases or rollouts), you can delete it by running the following command:

gcloud beta deploy delivery-pipelines delete PIPELINE_NAME

If the pipeline you want to delete has any releases or rollouts associated with it, you need to include the--force flag in order to delete the pipeline and those subresources:

gcloud beta deploy delivery-pipelines delete PIPELINE_NAME --force

What's next