This page describes how to use Google Cloud Deploy to get your application into your intended target runtime environments.
Google Cloud Deploy takes your application through a progression of several deployment targets, in sequence, and this page describes the high-level process.
In the process described on this page, you create a delivery pipeline and define your targets using one or more YAML configuration files. Then you register that pipeline and submit your application as a release whose deployment is managed by that pipeline.
Before you begin
Have a container image to deploy and a Kubernetes manifest that identifies the container image.
You need a continuous integration pipeline, or some other process, to build and place images. Your CI tool can be Cloud Build, Jenkins, or anything that results in container images to provide to your Google Cloud Deploy delivery pipeline.
Create a
skaffold.yaml
configuration file, if you don't already have one, which tells Google Cloud Deploy how to render and deploy your Kubernetes application.Google Cloud Deploy calls
skaffold render
to render the Kubernetes manifests using this file andskaffold apply
to deploy them into your target.The
skaffold.yaml
file must reference the namespace corresponding to a supported version in the first line, as in this example:apiVersion: skaffold/v2beta16
If you don't already have a
skaffold.yaml
file, you can useskaffold init
to generate it.See Using Skaffold in Google Cloud Deploy for more details. Also, Managing manifests in Google Cloud Deploy has more details on using Skaffold and Google Cloud Deploy with manifest-management tools, such as Helm, Kustomize, and kpt.
Make sure your execution service account has the necessary IAM roles and permissions.
Creating your delivery pipeline
Your delivery pipeline describes a progression of deployment targets. You can define those targets in the same file as the delivery pipeline or in one or more separate files.
After you create the delivery pipeline and target definition file or files, you
run gcloud deploy apply
against each of those files to register them as
Google Cloud Deploy resources.
Defining the delivery pipeline and targets
The structure of the delivery pipeline configuration file is described here.
You can call this file anything you want. By convention, a delivery pipeline
config that includes target definitions is
called clouddeploy.yaml
, and one that instead references targets defined in
one or more separate files is named delivery-pipeline.yaml
.
The target can point to a GKE cluster or an Anthos cluster.
Registering the delivery pipeline and targets
To register your delivery pipeline with Google Cloud Deploy, you run
gcloud deploy apply
once for each separate definition file. That is, if
you define three targets in three files, you would run the command four
times—once for the delivery pipeline, and once for each target.
The following command registers a delivery pipeline with its targets defined in the same file.
gcloud deploy apply --file=PIPELINE_CONFIG \
--region=LOCATION
--project=PROJECT
You now have a delivery pipeline that can manage deployment of your releases, and target resources that can be used by any delivery pipeline in the same project and region.
A single-file example
The command in this example registers a delivery pipeline and targets that are all defined in the same file:
gcloud deploy apply --file=clouddeploy.yaml --region=us-central1
An example using separate files
For this example, there are three targets defined in three separate files, so you run four commands:
gcloud deploy apply --file=delivery-pipeline.yaml --region=us-central1 && \
gcloud deploy apply --file=target_dev.yaml --region=us-central1 && \
gcloud deploy apply --file=target_staging.yaml --region=us-central1 && \
gcloud deploy apply --file=target_prod.yaml --region=us-central1
The --region
flag is required unless you've set a default (using gcloud
config set deploy/region [REGION]
. The region must be the same for the delivery
pipeline and all targets that pipeline references.
Editing existing pipelines and targets
You can later edit any delivery pipeline or target config and run gcloud
deploy apply
to update the pipeline or target resource. But those changes
do not affect any existing releases, as they are managed by the original
delivery pipeline.
Requiring manual approval for a deployment
To require manual approval for a given target, include the following property on the target definition:
requireApproval: true
The default is false
. If you omit this property from the delivery-pipeline
config, or provide no value for it, deploying to this target doesn't require
approval. (But the caller trying to promote to the target still needs the
clouddeploy.rollouts.create
IAM permission.)
You can even require manual approval on the first target. When a release is
created, using the CLI, for the first target, the rollout
is created
automatically. If approval is required, Google Cloud Deploy creates the
rollout
, but in a pending-release state until approval is given.
Invoking your delivery pipeline to deploy your application
You can now submit your application to be deployed according to the delivery pipeline you created.
Run your regular continuous-integration (CI) process, creating the deployable artifact or artifacts.
Initiate the delivery pipeline by calling Google Cloud Deploy to create a release.
Run the following command from the directory containing your Skaffold config:
gcloud deploy releases create RELEASE_NAME --delivery-pipeline=PIPELINE_NAME
Where:
RELEASE_NAME
is a name to give to this release. The name must be unique among all releases for this delivery pipeline.You can specify dynamic release names by including
'$DATE'
or'$TIME'
or both. For example, if you invoke this command at 3:07pm UTC,'rel-$TIME'
resolves torel-1507
.'$DATE'
and'$TIME'
must be in single-quotes, and the time is UTC time on the machine where you invoke the command.PIPELINE_NAME
is the name of the delivery pipeline that will manage deployment of this release through the progression of targets. This name must match thename
field in the pipeline definition.
This command uploads a tarball containing your configs to a Cloud Storage bucket and creates the release. Google Cloud Deploy also automatically creates a rollout and deploys your image to the first target defined in the delivery pipeline.
In addition to the parameters shown with this command, you can include either of the following options:
--images=<name=path/name:$IMAGE_SHA>,<name=path/name:$IMAGE_SHA>
A collection of image name to image full-path replacements.
--build_artifacts=<path/file>
A reference to a Skaffold build artifacts output file, which can be passed in to represent the image full path replacements
These two options are mutually exclusive.
Changing the deployment timeout
For deployments to GKE and Anthos target clusters, there are three separate timeouts that affect how long the system waits for Kubernetes to report a stable deployment:
Cloud Build has a timeout of 1 hour on operations that Cloud Build performs for Google Cloud Deploy.
You can change this timeout in the configuration for your execution environment.
Skaffold has a health-check timeout (
deploy.statusCheckDeadlineSeconds
), which is the amount of time, in seconds, to wait for deployments to stabilize.The default is 600 seconds (10 minutes). To use this timeout,
deploy.statusCheck
must be set totrue
. By default, it is. IfstatusCheck
isfalse
, there is no status check, the rollout is marked successful afterkubectl apply
finishes successfully.For Kubernetes resources of
kind: Deployment
, there'sDeployment.spec.progressDeadlineSeconds
, which is the amount of time Kubernetes waits for the Deployment to report as stable.This timeout is applicable to
Deployment
resources only. Here's how these first two timeouts work together:If
Deployment.spec.progressDeadlineSeconds
, in Kubernetes, is unset, then the Skaffold health-check timeout is the effective timeout, whether it's the default or is explicitly set.If
Deployment.spec.progressDeadlineSeconds
, in Kubernetes, is set, then Skaffold ignores its own health-check timeout, and the Kubernetes progress deadline is the effective timeout. However, if the Kubernetes timeout is explicitly set to600
(10 minutes), then Skaffold assumes that it's the default (unset) and ignores it, and the Skaffold timeout is used (if set).If neither timeout is set, then the effective timeout is the Skaffold default of
600
(10 minutes).
Besides
Deployment
s, other Kubernetes resources can have timeouts, which do not influence the stability timeout. If any of these are present, review them to ensure they are not in conflict with the stability timeout.If Skaffold (or Cloud Build) times out, the GKE deployment continues to run. Google Cloud Deploy shows a failure, but it can still succeed or fail on the GKE cluster.
To change your deployment stability timeout:
Ensure that
deploy.statusCheck
is set totrue
inskaffold.yaml
.true
is the default. Whentrue
, Skaffold waits for health checks to report a stable deployment, subject to the timeout value in the next step.In
skaffold.yaml
, setstatusCheckDeadlineSeconds
to the number of seconds you want to wait.deploy: ... statusCheck: true statusCheckDeadlineSeconds: 600 ...
The default is
600
(10 minutes). Skaffold waits this amount of time for a stable deployment. If this time is exceeded before the deployment is stable, the deployment fails.In your Kubernetes manifest, for resources of
kind: Deployment
, setDeployment.spec.progressDeadlineSeconds
to the same value as you set forstatusCheckDeadlineSeconds
.
Promoting a release
When your release is deployed into a target defined in your delivery pipeline, you can promote it to the next target:
gcloud
gcloud deploy releases promote --release=RELEASE_NAME --delivery-pipeline=PIPELINE_NAME
Where:
RELEASE_NAME
is the name of the release you're
promoting.
PIPELINE_NAME
is the name of the delivery pipeline
you're using to manage deployment of this release.
Console
Click your pipeline shown in the list of delivery pipelines.
The Delivery pipeline details page shows a graphical representation of your delivery pipeline's progress.
On the first target in the delivery pipeline visualization, click Promote.
The Promote release dialog is shown. It shows the details of the target you're promoting to.
Click Promote.
If the delivery pipeline or target has changed since the release was created,
Google Cloud Deploy returns a message indicating a possible
mismatch, and prompts
you to confirm the promotion. You can respond n
to the prompt and examine the
differences between the pipeline versions before you proceed. If you choose to
promote anyway, the release is deployed according to the delivery pipeline as it
was defined when the release was created. See
Pipeline instances per release for more
information about pipeline mismatches.
Google Cloud Deploy creates a rollout
for the release into the
destination target, and the release is queued for deployment. When it's
deployed, the delivery pipeline visualization shows that fact:
Approving a promotion
Each target can require approval before any release is deployed to it.
When you promote to a target that requires approval, Google Cloud Deploy
publishes a Pub/Sub message to the cd-approvals
topic.
See Approving or rejecting a rollout for more information on how approvals work.
Deploying manually
During normal use, Google Cloud Deploy deploys your application into each target in the progression, in sequence. But you can also manually deploy your application to any defined target.
You can manually deploy a new or an existing release.
Manually deploying an existing release
If a release is already created, you can simply promote it to the intended target:
gcloud deploy releases promote --release=RELEASE_NAME --delivery-pipeline=PIPELINE_NAME --to-target=TARGET_NAME
Where:
RELEASE_NAME is the name of the release which you're manually promoting to the intended target.
PIPELINE_NAME is the name of the delivery pipeline that describes the automated deployment progression you're overriding.
TARGET_NAME is the name of the target you're manually deploying to.
Manually deploying a new release
By default, when you create a release Google Cloud Deploy automatically deploys it to the first target in the promotion sequence. But you can specify a target other than the first one.
As with the default first target in the progression, Google Cloud Deploy
automatically creates the rollout
for the specified target and deploys the
release there.
To manually deploy a new release, run the following command:
gcloud deploy releases create --release=RELEASE_NAME --delivery-pipeline=PIPELINE_NAME --to-target=TARGET_NAME
Where:
RELEASE_NAME is the name of the release which you're manually promoting to the intended target.
PIPELINE_NAME is the name of the delivery pipeline that describes the automated deployment progression you're overriding.
TARGET_NAME is the name of the target you're manually deploying to.
Effect of manual deployment on the progression
When you manually deploy to a specific target and then promote the release without specifying a target, Google Cloud Deploy promotes it to the correct next target in the progression. This is because the service tracks the furthest target to which a release has been deployed. If the release is already in the last target in the progression, Google Cloud Deploy returns a message indicating there is no further target to promote to.
What's next
- Learn how to manage your delivery pipeline