Define a custom analysis

Cloud Deploy supports analysis jobs that use alerts generated by Google Cloud Observability based on metrics and other data also from Google Cloud Observability. However, you can also extend Cloud Deploy to use other metrics providers. This document describes how to configure and use an analysis job, and the requirements for a custom container that includes the logic to analyze metrics from the provider of your choice.

Note: Cloud Deploy provides sample containers for some metrics providers.

Before you begin

Sign in to your Google Account.

If you don't already have one, sign up for a new account.

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

Verify that you have the permissions required to complete this guide.

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, Cloud Deploy APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable clouddeploy.googleapis.com  compute.googleapis.com

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

Verify that you have the permissions required to complete this guide.

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, Cloud Deploy APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable clouddeploy.googleapis.com  compute.googleapis.com

Required roles

To get the permissions that you need to create and use analysis jobs, ask your administrator to grant you the following IAM roles on the account for your project:

• Cloud Deploy Job Runner (roles/clouddeploy.jobRunner)
• IAM Service Account User (roles/iam.serviceAccountUser)
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

To ensure that the Cloud Deploy service account has the necessary permissions to create and use analysis jobs, ask your administrator to grant the following IAM roles to the Cloud Deploy service account on your project:

Important: You must grant these roles to the Cloud Deploy service account, not to your user account. Failure to grant the roles to the correct principal might result in permission errors.

• IAM Service Account User (roles/iam.serviceAccountUser)
• Cloud Deploy Releaser (roles/clouddeploy.releaser)
• Cloud Deploy Operator (roles/clouddeploy.operator)

For more information about granting roles, see Manage access to projects, folders, and organizations.

Your administrator might also be able to give the Cloud Deploy service account the required permissions through custom roles or other predefined roles.

Configure a custom analysis job

A custom analysis job is the same as an analysis job that uses alerts from Google Cloud Observability, but the custom job uses one or more tasks that reference custom containers and the commands to run on those containers to process data from your metrics provider.

This section describes how to configure a Cloud Deploy analysis job that uses a non-Google Cloud monitoring provider.

The analysis stanza can be used directly inside a deployment strategy config (strategy.standard.analysis, for a standard strategy). If you want to configure analysis per phase, you use a custom canary (strategy.canary.customCanaryDepolyment.phaseConfigs.phaseId.analysis).

strategy:
  standard:
    analysis:
      duration: DURATION
      customChecks:
      - id: CHECK_ID
        frequency: FREQUENCY
        task:
          type: container
          image: IMAGE_NAME
          command: COMMAND
          args: [ARGS]
          env:
            [VAR_NAME: VALUE]

Where:

• DURATION

  Is how long, in seconds, to run the analysis job. After the duration expires, the job is finished. If the analysis fails (the container returns a non-zero exit code), the job finishes (FAILED) before the duration expires.

• CHECK_ID

  Is an ID for the individual check. This ID must be unique within this analysis job

• FREQUENCY

  Is how often, in seconds, to run the individual check.

• IMAGE_NAME

  Is the path and name identifying your container image.

• COMMAND

  Is the command to run on that container, for example a shell script (/bin/bash).

• ARGS

  Is a list of arguments to that command. This is a comma-separated list. If your COMMAND_TO_RUN is "/bin/sh", then one of the arguments here would be -c, and another argument would be the entire command you want to run in the shell you're invoking.

• VAR_NAME

  Is the name of an environment variable to pass to the container. You use environment variables to configure the behavior of the container. That is, the variables and their values tell the container what specifically to monitor in the metrics provider.

  You can use system parameters as environment variables here.

• VALUE

  Is the value of each environment variable. Cloud Deploy does nothing with these environment variables except pass them, with their values, to your container. It's up to your container to use the values in your analysis logic.

Each check in a custom analysis definition includes a task that references a container, the command or commands to run on that container, and any applicable environment variables to pass to that container.

The custom container

For the custom analysis, the container you provide is responsible for analyzing the telemetry, logs, or other data from the metrics provider you use. The Cloud Deploy analysis job waits for the return code from the container.

What the custom container must do

The custom container is responsible for ingesting data from your metrics provider, determining whether the metrics, logs, or other data indicate a properly functioning application, and returning the results to Cloud Deploy.

What the custom container must return

Cloud Deploy doesn't require anything from the custom container, other than that it return a zero or non-zero exit code. If the container returns a non-zero exit code, the analysis fails.

The container can write results to a file named results.json (in JSON format), located in the Cloud Storage bucket provided by Cloud Deploy. The file will contain the metadata, in the form of key-value pairs. This is not required.

Available environment variables

Cloud Deploy also provides and populates the following environment variables in the execution environment. You can use these environment variables as part of your deploy hook, verify job, or custom target render or deploy.

• ANTHOS_MEMBERSHIP

  For targets of type ANTHOS, the fully specified resource name of the Anthos membership.

• CLOUD_RUN_LOCATION

  For targets of type RUN, the region the Cloud Run service is deployed in.

• CLOUD_RUN_PROJECT

  For targets of type RUN, the project in which the Cloud Run service was created.

• CLOUD_RUN_SERVICE

  For targets of type RUN, the name of the Cloud Run service deployed.

• CLOUD_RUN_SERVICE_URLS

  For targets of type RUN, the URL or URLs (comma-separated list) that end users will use to access your service. You can find these in the Cloud Run service details for your service, in the Google Cloud console. The URLs are generated by Cloud Run after your Cloud Run Service or Services have been successfully deployed. Therefore this environment variable is only available in postdeploy hooks and verify jobs.

• CLOUD_RUN_REVISION

  For targets of type RUN, the specific revision of the Cloud Run service.

• GKE_CLUSTER

  For targets of type GKE, the fully specified resource name of the Google Kubernetes Engine cluster, for example projects/p/locations/us-central1/clusters/dev.

• TARGET_TYPE

  The specific runtime type of the target. Either GKE, ANTHOS, or RUN. For custom targets, this won't be set.

• CLOUD_DEPLOY_LOCATION

  The region containing the Cloud Deploy resources.

• CLOUD_DEPLOY_DELIVERY_PIPELINE

  The ID of the delivery pipeline.

• CLOUD_DEPLOY_TARGET

  The ID of the target.

• CLOUD_DEPLOY_PROJECT

  The Google Cloud project number for the project containing the Cloud Deploy resources.

• CLOUD_DEPLOY_PROJECT_ID

  The Google Cloud project ID for the project.

• CLOUD_DEPLOY_RELEASE

  The ID of the release in which the hooks will run.

• CLOUD_DEPLOY_ROLLOUT

  The ID of the rollout that contains the jobs for the hooks.

• CLOUD_DEPLOY_JOB_RUN

  The ID of the job run that represents the current execution of the job.

• CLOUD_DEPLOY_PHASE

  The phase in the rollout that contains the job for the deploy hook, verify job, or custom render or deploy.

What's next

• Try the quickstart: .

• Learn how to set up deploy analysis.

• See the config schema for analysis in the Cloud Deploy configuration reference.

• Learn more about deploy automation.

• Learn more about deployment strategies.