Using Cloud Deploy notifications

This page describes how to use Cloud Deploy service notifications, including how to subscribe to them.

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

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

  • To extend Cloud Deploy with supplemental business logic.

Available topics

Cloud Deploy publishes messages to the following set of Google Pub/Sub topics:

  • clouddeploy-resources

    When there is an operation (create, update, delete) against any Cloud Deploy core resource (automation, custom target type, delivery pipeline, job run, release, rollout, target).

  • clouddeploy-operations

    • When Cloud Deploy renders the Skaffold configuration.
    • When Cloud Deploy deploys to a target (Start, Succeed, Failure, Terminated (job run), Cancelled (rollout)).

  • clouddeploy-approvals

    • When Cloud Deploy needs an approval (or rejection) of a rollout.
    • When a rollout has been approved or rejected.

  • clouddeploy-advances

    • When a Cloud Deploy rollout has been advanced from one phase to the next.
    • When a rollout is ready to be advanced.

You can use a push or pull model for your Pub/Sub subscriptions.

Receive Cloud Deploy service notifications

To receive Cloud Deploy service notifications:

  1. Enable the Cloud Deploy API:

    Enable the Cloud Deploy API

    The Cloud Deploy Service Agent service account is automatically added to your project when you first call the Cloud Deploy API. This service account enables you to receive Cloud Deploy service notifications using Pub/Sub.

    The service account name has the following format, where project-number is your project number:

     service-project-number@gcp-sa-clouddeploy.iam.gserviceaccount.com

    If you still don't see the Cloud Deploy Service Agent service account on your IAM page, or you can't receive Pub/Sub notifications, add this service account to your project:

    1. Open the IAM page in the Google Cloud console:

      Open the IAM page

    2. Click Add.

    3. Add the following principal, where project-number is your project number:

      service-project-number@gcp-sa-clouddeploy.iam.gserviceaccount.com

    4. Select Service Management > Cloud Deploy Service Agent as your role.

    5. Click Save.

  2. Enable the Pub/Sub API:

    Enable the Pub/Sub API

  3. Create the Pub/Sub topic or topics, based on which notification types you want to receive:

    gcloud pubsub topics create clouddeploy-resources
gcloud pubsub topics create clouddeploy-operations
gcloud pubsub topics create clouddeploy-approvals
gcloud pubsub topics create clouddeploy-advances

    To learn more about managing Pub/Sub topics, see Managing topics and subscriptions.

Subscribe to Cloud Deploy service notifications

You have several of options for subscribing to notifications. For example, you can push messages to an endpoint, or write a Python app for polling your subscription.

To learn how to set up Pub/Sub subscriptions for Cloud Deploy service notifications, read the Pub/Sub Subscriber Guide. You can also learn about Pub/Sub Client Libraries, which make developing subscriber applications easier.

Field values

This section lists possible values for fields in the Cloud Deploy Pub/Sub messages.

For Action

In these notifications, the possible values for Action are as follows.

  • For resources

    • Create
    • Update
    • Delete

  • For operations:

    • Start
    • Succeed
    • Failure
    • Terminated
    • Cancelled

  • For approvals:

    • Required
    • Approved
    • Rejected

  • For advances:

    • Required
    • Advanced

For ResourceType

And the possible values for ResourceType are as follows:

  • DeliveryPipeline
  • Target
  • Release
  • Rollout
  • JobRun

Sample messages

The following examples show several types of Pub/Sub messages from Cloud Deploy topics.

Delivery pipeline create

The following is an example of a Pub/Sub message published to clouddeploy-resources in response to creation of a new deliveryPipeline:

{
  "ackId":   "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUQBQgUBXx9cEFMdVhddmhRDRlyfWByY11AAgVMVnldURsHaE5tdR_Wg6LHS0NVaF4TBgpGVX5fXx0IYVtedi_m7r_2wPXOXkAvOYXL6Mtpe735h9xvZiM9XxJLLD5-IzRFQV5AEkwoAURJUytDCypYEU4EISE-MD5FUw",
  "message": {
    "attributes": {
      "Action": "Create",
      "Resource": "projects/120123456789/locations/us-central1/deliveryPipelines/etest",
      "ResourceType": "DeliveryPipeline",
      "Location": "us-central1",
      "DeliveryPipelineId": "etest",
      "ProjectNumber": "120123456789",

    },
    "messageId": "2407836004659723",
    "publishTime": "2021-05-17T21:24:48.204Z"
  }
}

Render start

The following is an example of a Pub/Sub message published to clouddeploy-operations to notify that a release has been rendered:

{
  "ackId": "U0RQBhYsXUZIUTcZCGhRDk9eIz81IChFFwYIFAV8fXBBTHVeXHRoUQ0Zcn1gcmNfR1MLFlN5WFEaB2hObXUfioKix0tDVWheEwYKRVZ3W1kdBGFVXH0v_qD5rMP1zl5AKDnZyujLaXudkqxfZiM9XxJLLD5-PTNFQV5AEkw2BkRJUytDCypYEU4EISE-MD5F",
  "message": {
    "attributes": {
      "Action": "Start",
      "Resource": "projects/120123456789/locations/us-central1/deliveryPipelines/etest/releases/f2",
      "ResourceType": "Release"
      "Location": "us-central1",
      "DeliveryPipelineId": "etest",
      "ProjectNumber": "120123456789",
      "ReleaseId": "f2",
    },
    "messageId": "2407805942699908",
    "publishTime": "2021-05-17T21:28:04.201Z"
  }
}

Approval required

The following is an example of a Pub/Sub message published to clouddeploy-approvals to notify that a rollout requires approval:

{
   "ackId": "RVNEUAYWLF1GSFE3GQhoUQ5PXiM_NSAoRRILUxNRXHQBWhBpWF8aB1ENGXJ8ZnxtCRBVU0FWf1VbEQ16bVxti6C2rERfQXduWhQJBkBXd11aHQhoXF9dotnkpeTv2kFwYSuN8_7mSH_Mo6AYZiA9XBJLLD5-IzZFQV5AEkwoA0RJUytDCypYEU4EISE-MD4",
   "message": {
     "attributes": {
       "Action": "Required",
       "Rollout": "projects/120123456789/locations/us-central1/deliveryPipelines/etest/releases/f2/rollouts/rollout-123"
       "ReleaseId": "f2",
       "RolloutId": "rollout-123",
       "TargetId": "prod",
       "Location": "us-central1",
       "ProjectNumber": "120123456789",
     },
     "messageId": "2407845492165003",
     "publishTime": "2021-05-17T21:31:25.143Z"
   }
 }

Rollout advance

The following is an example of a Pub/Sub message published to clouddeploy-advances to notify that a rollout has been advanced from one phase to the next:

{
  "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUSAwVPAihdeTFXKkFZdWhRDRlyfWB9bV4UUFZMV38OURoHaE5tdR_z4ILjS0NVbVkQBApEUHldXhkEa1RcfC-a0fmv1OzMV0AvOaCoyO9pe77r3NluZiM9XhJLLD5-Jz1FQV5AEkwsCERJUytDCypYEU4EISE-MD5FUw",
  "message": {
    "attributes": {
      "Action": "Advanced",
      "Location": "us-central1",
      "PhaseId": "stable",
      "ProjectNumber": "120123456789",
      "ReleaseId": "rollout-123",
      "Rollout": "projects/120123456789/locations/us-central1/deliveryPipelines/etest/releases/f2/rollouts/rollout-123",
      "RolloutId": "rollout-123",
      "TargetId": "prod"
    },
    "messageId": "7335813725293809",
    "publishTime": "2023-04-03T15:16:30.425Z"
  }
}

In this message, PhaseId identifies the phase that the rollout has been advanced to.

What's next