Deploying your application

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 and skaffold 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 use skaffold 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.

1. Run your regular continuous-integration (CI) process, creating the deployable artifact or artifacts.

2. 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 to rel-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 the name 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 timeouts

By default, the Skaffold health-check timeout (deploy.statusCheckDeadlineSeconds) is 600 seconds (10 minutes). This value is the amount of time, in seconds, to wait for deployments to stabilize.

If deploy.statusCheck is true (the default), Skaffold waits for health checks to report a stable deployment, and this timeout is the amount of time that Skaffold waits. If the deadline is exceeded before the deployment is stable, the deployment fails.

This setting is in the skaffold.yaml configuration file that you use with Google Cloud Deploy.

deploy:
  ...
  statusCheck: true
  statusCheckDeadlineSeconds: 600
  ...

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 deploy releases promote --release=RELEASE_NAME --delivery-pipeline=PIPELINE_NAME

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