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.
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.
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: []
strategy:
standard:
verify:
- targetId:
profiles: []
strategy:
standard:
verify:
---
apiVersion: deploy.cloud.google.com/v1
kind: Target
metadata:
name:
annotations:
labels:
description:
multiTarget:
targetIds: []
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 | DEPLOY | VERIFY]
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.
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
Includes properties for specifying a deployment strategy. The only supported
strategy is standard:
.
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
.
The following delivery pipeline configuration is valid:
serialPipeline:
stages:
- targetId:
profiles: []
- targetId:
profiles: []
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.
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:
multiTarget:
targetIds: []
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.
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, 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 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 | DEPLOY | VERIFY]
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 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.
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
orDEPLOY
or both, plusVERIFY
if verification is 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 both rendering, deployment, and verification, you would configure it as follows:usages: - RENDER - DEPLOY - VERIFY
If verification is enabled on the pipeline stage, and you don't specify
VERIFY
in ausages
stanza, Google Cloud Deploy uses the default execution environment for verification. However, if there is a custom execution environment forRENDER
orDEPLOY
or both, you must specify one forVERIFY
.VERIFY
can be in the sameusages
asRENDER
orDEPLOY
, or in its own.You can't specify
usages.VERIFY
unless eitherRENDER
orDEPLOY
or both are specified in a custom execution environment.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
workerPool
s (one forRENDER
and one forDEPLOY
). 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
orDEPLOY
) for this target.artifactStorage
The Cloud Storage bucket to use for this operation (
RENDER
orDEPLOY
) 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"
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
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.