Delivery pipeline and target configuration

The Google Cloud Deploy configuration file or files define the delivery pipeline, the targets to deploy to, and the progression of those targets.

The delivery pipeline configuration file can include target definitions, or those can be in a separate file or files. By convention, a file containing both the delivery pipeline config and the target configs is called clouddeploy.yaml, and a pipeline config without targets is called delivery-pipeline.yaml. But you can give these files any name you want.

Note: your organization might prefer to separate target definitions from the pipeline definition, so that different roles can manage those configurations separately. Google Cloud Deploy supports that practice.

What goes where

Google Cloud Deploy uses two main configuration files:

• Delivery pipeline definition
• Target definition

These can be separate files, or the delivery pipeline and targets can be configured in the same file.

Note: After you define the configuration file or files, you create the delivery pipeline and target resources using the command line, as described in Registering the delivery pipeline and targets.

Structure of a delivery pipeline configuration file

The following configuration includes a target definition:

    apiVersion: deploy.cloud.google.com/v1
    kind: DeliveryPipeline
    metadata:
     name:
     annotations:
     labels:
    description:
    serialPipeline:
     stages:
     - targetId:
       profiles: []
     - targetId:
       profiles: []
     ---

     apiVersion: deploy.cloud.google.com/v1
     kind: Target
     metadata:
      name:
      annotations:
      labels:
     description:
     requireApproval:
     gke:
      cluster: projects/[project_name]/locations/[location]/clusters/[cluster_name]
      internalIp:

     executionConfigs:
     - usages:
       - [RENDER | DEPLOY]
       workerPool:
       serviceAccount:
       artifactStorage:
       executionTimeout:

     ---

This YAML has two main components:

• The main delivery pipeline and progression

  The configuration file can include any number of pipeline definitions.

• The target definitions

  For simplicity, only one target is shown in this example, but there can be any number of them. Also, targets can be defined in a separate file or files.

These components are defined in the rest of this document.

Pipeline definition and progression

In addition to pipeline metadata, such as name, the main pipeline definition includes a list of references to targets in deployment sequence order. That is, the first target listed is the first deployment target. After you've deployed to that target, promoting the release deploys to the next target in the list.

The following are the configuration properties for a delivery pipeline, not including target definitions.

metadata.name

The name field takes a string that must be unique per project and location.

metadata.annotations and metadata.labels

Delivery pipeline configuration can include annotations and labels. Annotations and labels are stored with the delivery pipeline resource after the pipeline has been registered.

For more information, see Using labels and annotations with Google Cloud Deploy.

description

An arbitrary string describing this delivery pipeline. This description is shown in the delivery pipeline details in Google Cloud console.

stages

A list of all targets to which this delivery pipeline is configured to deploy.

The list must be in the order of the delivery sequence you want. For example, if you have targets called dev, staging, and production, list them in that same order, so that your first deployment is to dev, and your final deployment is into production.

Populate each stages.targetId field with the value of the metadata.name field in the corresponding target definition. And under targetId, include profiles:

serialPipeline:
 stages:
 - targetId:
   profiles: []

targetId:

Identifies the specific target to use for this stage of the delivery pipeline. The value is the metadata.name property from the target definition.

profiles

Takes a list of zero or more Skaffold profile names, from skaffold.yaml. Google Cloud Deploy uses the profile with skaffold render when creating the release. Skaffold profiles let you vary configuration between targets while using a single configuration file.

Target definitions

The delivery pipeline definition file can contain target definitions, or you can specify targets in a separate file. You can repeat Target names within a project, but they must be unique within a delivery pipeline.

You can reuse targets among multiple delivery pipelines. However, you can only reference a target once from within a single delivery pipeline's progression.

For GKE targets

The following YAML shows how to configure a target that deploys to a GKE cluster:

     apiVersion: deploy.cloud.google.com/v1
     kind: Target
     metadata:
      name:
      annotations:
      labels:
     description:
     requireApproval:
     gke:
      cluster: projects/[project_name]/locations/[location]/clusters/[cluster_name]
      internalIp:

     executionConfigs:
     - usages:
       - [RENDER | DEPLOY]
       workerPool:
       serviceAccount:
       artifactStorage:
       executionTimeout:

metadata.name

The name of this target. This name must be globally unique.

metadata.annotations and metadata.labels

Target configuration supports Kubernetes annotations and labels, but Google Cloud Deploy does not require them.

Annotations and labels are stored with the target resource. For more information, see Using labels and annotations with Google Cloud Deploy.

description

This field takes an arbitrary string that describes the use of this target.

requireApproval

Whether promotion to this target requires manual approval. Can be true or false.

This property is optional. The default is false.

gke

For GKE clusters only, the resource path identifying the cluster where your application will be deployed:

gke:
  cluster: projects/[project_name]/locations/[location]/clusters/[cluster_name]

• project_name

  The Google Cloud project in which the cluster lives.

• location

  The location where the cluster lives. For example, us-central1. The cluster can also be zonal (us-central1-c).

• cluster_name

  The name of the cluster, as it appears in your list of clusters in Google Cloud console.

Here's an example:

gke:
  cluster: projects/cd-demo-01/locations/us-central1/clusters/prod

See executionConfigs, in this article, for descriptions of the execution environment properties.

internalIp

Whether or not the specified GKE cluster uses a private IP address. This property is optional. By default, Google Cloud Deploy uses the publicly available IP address for the cluster. If there's a private IP address and you want to use it, set this to true.

For Anthos targets

Preview

This product is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA products might have limited support, and changes to pre-GA products might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Target configuration for deploying to an Anthos cluster is the similar to configuring a target for a GKE target, except that the property is anthosCluster.membership, instead of gke.cluster, the resource path is different, and internalIp is not applicable.

anthosCluster:
  membership: projects/[project_name]/locations/global/memberships/[membership_name]

• project_name

  The Google Cloud project in which the Anthos cluster lives.

• /location/global/

  The location where the cluster is registered. global, in all cases.

• membership_name

  The name of the Anthos cluster membership.

Here's an example:

anthosCluster:
  membership: projects/cd-demo-01/locations/global/memberships/prod

For more information about deploying to Anthos clusters, see Deploying to Anthos user clusters.

executionConfigs

A set of fields to specify a non-default execution environment for this target.

Note: all configuration properties under executionConfigs are optional. You don't need to specify an execution environment if you can use the default worker pool, service account, and storage bucket.

• usages

  Either RENDER or DEPLOY or both, indicating which of those operations to perform for this target using this execution environment. To indicate that a custom execution environment is to be used for both rendering and deployment, you would configure it as follows:

  usages:
  - RENDER
  - DEPLOY
  

• workerPool

  Configuration for the worker pool to use. This takes a resource path identifying the Cloud Build worker pool to use for this target. For example:

  projects/p123/locations/us-central1/workerPools/wp123.

  To use the default Cloud Build pool, omit this property.

  A given target can have two workerPools (one for RENDER and one for DEPLOY). When configuring the default pool, you can specify an alternate service account or storage location or both.

• serviceAccount

  The name of the service account to use for this operation (RENDER or DEPLOY) for this target.

• artifactStorage

  The Cloud Storage bucket to use for this operation (RENDER or DEPLOY) for this target, instead of the default bucket.

• executionTimeout

  Optional. Sets the timeout, in seconds, for operations that Cloud Build performs for Google Cloud Deploy. By default this is 3600 seconds (1 hour).
  Example: executionTimeout: "5000s"

Note: If you specify a configuration for either RENDER or DEPLOY, you must do so for the other, even if one uses default values (only the usages: property).

Alternative supported syntax

The executionConfigs configuration described in this document is new. The previous syntax is still supported:

executionConfigs:
- privatePool:
    workerPool:
    serviceAccount:
    artifactStorage:
  usages:
  - [RENDER | DEPLOY]
- defaultPool:
    serviceAccount:
    artifactStorage:
  usages:
  - [RENDER | DEPLOY]

What's next

• Find out more about how Google Cloud Deploy works.

• Learn how to set up a delivery pipeline for your application.

• Learn how to manage your manifests.

• Avoid mismatches between your release and your delivery pipeline by learning about pipeline instances.