Configuration schema reference

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. Other resource definitions, such as automations and deploy policies, can also be in the same file as a delivery pipeline or target definition.

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 is the structure of a delivery pipeline configuration, including properties for target definitions. Some target properties are not included here. See Target definitions for all target configuration properties.

# Delivery pipeline config
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:
       predeploy:
         tasks: []
       verify:
         tasks: []
       analysis:
       postdeploy:
         tasks: []
   deployParameters:
   - values:
     matchTargetLabels:
 - targetId:
   profiles: []
   strategy:
   deployParameters:
---

# Target config
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:
 dnsEndpoint:
 internalIp:
 proxyUrl:
#
# or:
anthosCluster:
 membership:
#
# or:
run:
 location:
#
# or:
customTarget:
  customTargetType:
#
# (End runtimes. See documentation in this article for more details.)
#
executionConfigs:
- usages:
  - [RENDER | PREDEPLOY | DEPLOY | VERIFY | POSTDEPLOY | ANALYSIS]
  workerPool:
  serviceAccount:
  artifactStorage:
  executionTimeout:
  verbose:
---

# Custom target type config
apiVersion: deploy.cloud.google.com/v1
kind: CustomTargetType
metadata:
  name:
  annotations:
  labels:
description:
tasks:
  render:
  deploy:
---

# Automation config
apiVersion: deploy.cloud.google.com/v1
kind: Automation
metadata:
  name:
  labels:
  annotations:
description:
suspended:
serviceAccount:
selector:
  targets:
    -  id: [TARGET_ID]
       labels:
         [LABEL_KEY]:[LABEL_VALUE]
rules:
- [RULE_TYPE]:
  id:
  [RULE-SPECIFIC_CONFIG]

This YAML has three 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.

  • Custom target type definitions

    Custom targets, require a custom target type definition. As with targets and automations, custom target types can be defined in the same file as the delivery pipeline, or in separate file.

  • Automation definitions

    You can create any deploy automations in the same file as your delivery pipeline and targets, or in a separate file or files. For simplicity, only one Automation is shown here, but you can create as many as you want.

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 includes only the following elements:

strategy:
  standard:
    verify:
      tasks: []
    analysis:

The verify property lets you reference one or more tasks to execute to verify your deployment. If configured, the verify tasks will run sequentially, immediately after the 'deploy' job.

The verify property is optional. If not specified, there will be no verify job in the resulting rollouts.

The analysis stanza is optional, for use with Cloud Deploy analysis.

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:
        tasks: []
      analysis:

For Cloud Run targets, AutomaticTrafficControl must be true unless you're configuring a custom canary.

For GKE and GKE attached clusters targets

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

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