Delivery pipeline and target configuration

The 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.

What goes where

Cloud Deploy uses two main configuration files:

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

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:
suspended:
serialPipeline:
 stages:
 - targetId:
   profiles: []
# Deployment strategies
# One of:
#   standard:
#   canary:
# See the strategy section in this document for details.
   strategy:
     standard:
       verify:
       predeploy:
         actions: []
       postdeploy:
         actions: []
   deployParameters:
   - values:
     matchTargetLabels:
 - targetId:
   profiles: []
   strategy:
   deployParameters:
---

apiVersion: deploy.cloud.google.com/v1
kind: Target
metadata:
 name:
 annotations:
 labels:
description:
multiTarget:
 targetIds: []
deployParameters:
requireApproval:
#
# Runtimes
# one of the following runtimes:
gke:
 cluster:
 internalIp:
#
# or:
anthosCluster:
 membership:
#
# or:
run:
 location:
# (End runtimes. See documentation in this article for more details.)
#
executionConfigs:
- usages:
  - [RENDER | PREDEPLOY | DEPLOY | VERIFY | POSTDEPLOY]
  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 Cloud Deploy.

description

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

suspended

A Boolean, which if true suspends the delivery pipeline such that it can't be used to create, promote, roll back, or redeploy releases. Also, if the delivery pipeline is suspended, you can't approve or reject a rollout created from that pipeline.

The default is false.

serialPipeline

The beginning of the definition of a serial-progression delivery pipeline. This stanza is required.

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: []
   strategy:
     standard:
       verify:

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.

strategy.standard.verify set to true enables deployment verification on the target. If no deployment strategy is specified, the standard deployment strategy is used, with verification set to false.

profiles

Takes a list of zero or more Skaffold profile names, from skaffold.yaml. 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.

strategy

Includes properties for specifying a deployment strategy. The following strategies are supported:

  • standard:

    The application is deployed fully to the specified target.

    This is the default deployment strategy. If you omit strategy, Cloud Deploy uses the standard deployment strategy.

  • canary:

    In a canary deployment, you deploy a new version of your application progressively, replacing the already running version by percentage-based increments (for example, 25%, then 50%, then 75%, then fully.)

The deployment strategy is defined per target. For example, you might have a canary strategy for your prod target, but a standard strategy (no strategy specified) for your other targets.

For more information, see Use a deployment strategy.

strategy configuration

This section shows the configuration elements for strategy, for each supported runtime.

Standard deployment strategy

The standard strategy requires only following elements:

strategy:
  standard:
    verify: true|false

The verify property is optional. The default is false, meaning, there will be no verify phase for the resulting rollouts.

You can omit the strategy element for a standard deployment strategy.

Canary deployment strategy

The following sections describe configuration for a canary deployment strategy, for each runtime that Cloud Deploy supports.

For Cloud Run targets
strategy:
  canary:
    runtimeConfig:
      cloudRun:
        automaticTrafficControl: true | false
    canaryDeployment:
      percentages: [PERCENTAGES]
      verify: true | false
For GKE and Anthos targets

The following YAML shows how to configure a deployment strategy for a GKE or Anthos target, using service-based networking:

      canary:
        runtimeConfig:
          kubernetes:
            serviceNetworking:
              service: "SERVICE_NAME"
              deployment: "DEPLOYMENT_NAME"
              disablePodOverprovisioning: true | false
        canaryDeployment:
          percentages: [PERCENTAGES]
          verify: true | false

The following YAML shows how to configure a deployment strategy for a GKE or Anthos target, using Gateway API:

      canary:
        runtimeConfig:
          kubernetes:
            gatewayServiceMesh:
              httpRoute: "HTTP_ROUTE_NAME"
              service: "SERVICE_NAME"
              deployment: "DEPLOYMENT_NAME"
              routeUpdateWaitTime: "WAIT_TIME"
        canaryDeployment:
          percentages: ["PERCENTAGES"]
          verify: true | false

Notice in this example routeUpdateWaitTime. This is included because Gateway API splits traffic using an HTTPRoute resource, and sometimes there is a delay propagating changes made to the HTTPRoute. In such cases requests may be dropped, because traffic is being sent to resources that are unavailable. You can use routeUpdateWaitTime to cause Cloud Deploy to wait after applying HTTPRoute changes, if you observe this delay.

The following YAML shows how to configure a custom or custom-automated canary deployment strategy. Runtime-specific configuration, in the runtimeConfig section, is omitted for custom canary, but included in automated and custom automated canary configuration.

strategy:
       canary:
         # Runtime configs are configured as shown in the
         # Canary Deployment Strategy section of this document.
         runtimeConfig:

         # Manual configuration for each canary phase
         customCanaryDeployment:
           - name: "PHASE1_NAME"
             percent: PERCENTAGE1
             profiles: [ "PROFILE1_NAME" ]
             verify: true | false
           - …
           - name: "stable"
             percent: 100
             profiles: [ "LAST_PROFILE_NAME" ]
             verify: true|false

verify

Optional boolean indicating whether or not to support deployment verification for this target. The default is false.

Enabling deployment verification also requires a verify stanza in the skaffold.yaml. If you don't provide this property, the verify job will fail.

deployParameters

Allows you to specify key value pairs to pass values to manifests for label-matched targets, when using deploy parameters.

You can also include this on targets.

Deploy parameters set on a delivery pipeline use labels to match targets:

deployParameters:
- values:
    someKey: "value1"
  matchTargetLabels:
    label1: firstLabel
- values:
    someKey: "value2"
  matchTargetLabels:
    label2: secondLabel

In this example, there are two values provided for the key, and for each value, there is a label. The value is applied to the manifest for any target that has a matching label.

predeploy and postdeploy jobs

These allow you to reference custom actions (defined separately, in skaffold.yaml) to run before the deploy job (predeploy) and after the verify job, if present (postdeploy). If there's no verify job, the postdeploy job runs after the deploy job.

Deploy hooks are configured under strategy.standard or strategy.canary as follows:

serialPipeline:
  stages:
  - targetId: 
    strategy:
      standard:
        predeploy:
          actions: [ACTION_NAME]
        postdeploy:
          actions: [ACTION_NAME]

Where ACTION_NAME is the name configured in skaffold.yaml for customActions.name.

You can configure predeploy and postdeploy jobs under any strategy (standard, canary, for example).

For more information about configuring and using pre- and post-deploy hooks, see Run hooks before and after deploying.

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:
     deployParameters:
     multiTarget:
      targetIds: []

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

     executionConfigs:
     - usages:
       - [RENDER | PREDEPLOY | DEPLOY | VERIFY | POSTDEPLOY]
       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 Cloud Deploy does not require them.

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

description

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

deployParameters

You can include deploy parameters on any target, along with values. Those values are assigned to the corresponding keys in your manifest, after rendering.

The deployParameters stanza takes key-value pairs, as shown:

deployParameters:
  someKey: "someValue"
  someOtherKey: "someOtherValue"

If you set deploy parameters on a multi-target, the value is assigned to the manifest for all of that multi-target's child targets.

multiTarget.targetIds: []

This property is optional, and is used to configure a multi-target to be used for parallel deployment.

The value is a comma-separated list of child targets. Child targets are configured as normal targets, and don't include this multiTarget property.

requireApproval

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

This property is optional. The default is false.

When you configure parallel deployment, you can require approval on the multi-target only—not on child targets.

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

Omit the gke property when configuring a multi-target. The GKE cluster is configured instead inside the corresponding child target.

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, 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 Cloud Run targets

The following YAML shows how to configure a target that deploys to a Cloud Run service:

     apiVersion: deploy.cloud.google.com/v1
     kind: Target
     metadata:
      name:
      annotations:
      labels:
     description:
     multiTarget:
      targetIds: []

     requireApproval:
     run:
      location: projects/[project_name]/locations/[location]

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

metadata.name

The name of this target. This name must be unique per region.

metadata.annotations and metadata.labels

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

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

description

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

multiTarget.targetIds: []

This property is optional, and is used to configure a multi-target to be used for parallel deployment.

The value is a comma-separated list of child targets. Child targets are configured as normal targets, and don't include this multiTarget property.

requireApproval

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

This property is optional. The default is false.

When you configure parallel deployment, you can require approval on the multi-target only—not on child targets.

run

For Cloud Run services only, the location where the service will be created:

run:
  location: projects/[project_name]/locations/[location]

  • project_name

    The Google Cloud project in which the service will live.

  • location

    The location where the service will lives. For example, us-central1.

Omit the run property when configuring a [multi-target]. The location of the Cloud Run service is configured instead inside the corresponding child target.

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

For Anthos targets

Target configuration for deploying to an Anthos cluster is 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

Omit the anthosCluster property when configuring a [multi-target]. The Anthos cluster is configured instead inside the corresponding child target.

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.

  • usages

    Either RENDER or DEPLOY or both, plus PREDEPLOY, VERIFY, or POSTDEPLOY if verification or deploy hooks are enabled on the target. These indicate 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 predeploy hook, render, deploy, postdeploy hook, and verification, you would configure it as follows:

    usages:
- RENDER
- PREDEPLOY
- DEPLOY
- VERIFY
- POSTDEPLOY

    If verification is enabled on the pipeline stage, and you don't specify VERIFY in a usages stanza, Cloud Deploy uses the default execution environment for verification. Predeploy and postdeploy hooks work the same way.

    However, if there is a custom execution environment for RENDER and DEPLOY, you must specify one for VERIFY, PREDEPLOY, OR POSTDEPLOY if they're configured on the delivery pipeline.VERIFY, PREDEPLOY, and POSTDEPLOY can be in the same usages as RENDER or DEPLOY, or in separate usages.

    You can't specify usages.VERIFY, usages.PREDEPLOY, or usages.POSTDEPLOY unless RENDER and DEPLOY are specified in the same or separate custom execution environments.

  • 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 Cloud Deploy. By default this is 3600 seconds (1 hour).
    Example: executionTimeout: "5000s"

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]

When you're configuring an executionConfigs stanza for a multi-target, each child target can inherit that execution environment from that multi-target.

What's next