Configure tasks

This document describes how to configure tasks in Cloud Deploy. A task is a unit of work that can be used as a deploy hook, for deployment verification, for deploy analysis, or for a custom render or custom deploy in a custom target type.

You can configure a task on the delivery pipeline (as part of the strategy) or the custom target type render or deploy.

With tasks, you can use system parameters by templating them into your task configuration.

Define a task

You can define a task in your delivery pipeline configuration or as part of a custom target type definition. The following YAML shows the task stanza used in either case:

  task:
    type: container
    image: IMAGE
    command: [COMMANDS_TO_RUN]
    args: [LIST_OF_ARGS]
    env:
    - KEY1:VAL1
    - KEY2:VAL2
    ...

For the task configuration:

• type

  Specifies the kind of task being configured. Only container is supported.

• image

  Is the path to the container image.

• command

  Is the command or commands to run on the container.

• args

  Is a collection of arguments to the command.

• env

  Is a collection of environment variables to be provided to the running container.

Note: When you define tasks in a delivery pipeline configuration, you create a list of one or more tasks. When you're configuring a custom target type, you create only one task.

System Parameters as task environment variables

Cloud Deploy offers system-generated parameters that you can use as environment variables in your tasks, using the env field in the container task. The templated parameters can be present in the key or value fields of an env map entry.

Here are a couple of example use cases:

• Passing in the Cloud Run service name, service URL, and revision name as environment variables.

  task:
    type: container
    image: my-image
    command: ["/bin/bash"]
    env:
    - RUN_SERVICE_NAME : "${{ render.metadata.cloud_run.service.name }}"
    - RUN_SERVICE_URL: "${{ rollout.metadata.cloud_run.service_url }}"
    - RUN_REVISION_NAME: "${{ render.metadata.cloud_run.revision.name }}"
  

• Using multiple parameters in a single entry.

  task:
    type: container
    image: my-image
    command: ["/bin/bash"]
    env:
    - DEPLOY_PARAMS_KEY : "${{ deploy_params['FOO'] }}-with-${{ deploy_params['BAR'] }}"
    - "${{ project.id }}_${{ location }}" : "${{ target.id }}"
  

Available system parameters

Cloud Deploy provides the following system parameters that you can use in your tasks configuration using this format:

${{ parameter }}

Note: Cloud Deploy will attempt to evaluate instances of ${{ }} in any task environment variable. If you want to escape this evaluation, then prepend another $ to the template expression, like this:

$${{ }}.

The following is the list of parameters available for templating:

Name	Definition
location	The region containing the Cloud Deploy resources. Available at release creation.
project.num	The Google Cloud project number for the project containing the Cloud Deploy resources. Available at release creation.
project.id	The Google Cloud project ID for the project. Available at release creation.
delivery_pipeline.name	The fully specified resource name of the delivery pipeline. Available at release creation.
delivery_pipeline.id	The ID of the delivery pipeline. Available at release creation.
target.name	The fully specified resource name of the target. Available at release creation.
target.id	The ID of the target. Available at release creation.
release.name	The fully specified resource name of the release. Available at release creation.
release.id	The ID of the release. Available at release creation.
rollout.name	The fully specified resource name of the rollout. Available at rollout creation.
rollout.id	The ID of the rollout. Available at rollout creation.
job.id	The ID of the job being executed. Available at rollout creation.
phase.id	The phase in the rollout that contains the job for the tasks. Available at rollout creation.
job_run.name	The fully specified resource name of the job run that represents the current execution of the job. Available at rollout creation.
job_run.id	The ID of the job run that represents the current execution of the job. Available at rollout creation.
deploy_params	A map of the deploy parameters associated with the target. Example: deploy_params['KEY'] Trying to access a key that doesn't exist results in an empty string. Available at release creation.
For targets of type RUN:
cloud_run.project	The project in which the Cloud Run service was created. Available at release creation.
cloud_run.location	The region the Cloud Run service is deployed in. Available at release creation.
render.metadata.cloud_run.service.name	The name of the Cloud Run service deployed. Available after the render operation has completed.
render.metadata.cloud_run.service.id	The ID of the Cloud Run service deployed. Available after the render operation has completed.
rollout.metadata.cloud_run.service.url	The URL 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. Available after the deploy operation has completed.
render.metadata.cloud_run.revision.name	The full name of the revision of the Cloud Run service being deployed. Available after the render operation has completed.
render.metadata.cloud_run.revision.id	The revision ID of the Cloud Run service being deployed. Available after the render operation has completed.
rollout.metadata.cloud_run.previous_revision.name	The full name of the previous revision of the Cloud Run service being deployed. Available after the deploy operation has completed.
rollout.metadata.cloud_run.previous_revision.id	The previous revision ID of the Cloud Run service being deployed. Available after the deploy operation has completed.
For targets of type GKE:
gke.cluster.name	The fully specified resource name of the GKE cluster. Available at release creation.
gke.cluster.id	The ID of the GKE cluster. Available at release creation.
gke.cluster.project	The project ID/number of the GKE cluster. Available at release creation.
gke.cluster.location	The location of the GKE cluster. Available at release creation.
For targets of type ANTHOS:
anthos.membership.project	The project ID/number of the GKE Enterprise cluster. Available at release creation.
anthos.membership.location	The location of the GKE Enterprise cluster. Available at release creation.
anthos.membership.name	The fully specified resource name of the GKE Enterprise membership. Available at release creation.
anthos.membership.id	The ID of the GKE Enterprise membership. Available at release creation.
For Kubernetes targets (targets of type GKE and ANTHOS):
render.metadata.kubernetes.deployment	The name of the deployment being updated. This is not set if there is more than one deployment in the manifests. Available after the render operation has completed.
render.metadata.kubernetes.canary_deployment	The name of the canary deployment in an automated canary. For the stable phase, this is the same as render.metadata.kubernetes.deployment, because there is no canary in the stable phase. For the other phases, this is the same as render.metadata.kubernetes.deployment with -canary on the end. Available after the render operation has completed.
render.metadata.kubernetes.namespace	The namespace of the resources being deployed. This is not set if there's more than one namespace in the manifests. Available after the render operation has completed.
For targets of type CUSTOM_TARGET_TYPE:
render.metadata.custom	A map of the render metadata from a custom render. Example: render.metadata.custom['KEY'] Trying to access a key that doesn't exist results in an empty string. Available after the render operation has completed.
rollout.metadata.custom	A map of the rollout metadata from a custom deploy. Example: rollout.metadata.custom['KEY'] Trying to access a key that doesn't exist results in an empty string. Available after the deploy operation has completed.

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

• Learn how to run deploy hooks using tasks
• Learn how to verify your deployment using tasks
• Learn about custom targets