Deploying your application

Preview

This product is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA products might have limited support, and changes to pre-GA products might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

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 defines your local development and build process.

  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

Defining your delivery pipeline

1. Create your delivery pipeline configuration file.

   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 a separate file or files containing those target definitions is named delivery-pipeline.yaml.

   The structure of the delivery pipeline configuration file is described here. Deployment targets can be defined in the same file or in a separate file or files.

2. Register your delivery pipeline with Google Cloud Deploy to create the delivery pipeline resource:

   gcloud beta deploy apply --file=PIPELINE_CONFIG
   

   Where PIPELINE_CONFIG is the name (including path) of your delivery pipeline configuration file.

   For simplicity in this example, we've defined the targets in the same file as the delivery pipeline, but you can define targets in separate files. You create the target resources using gcloud beta deploy apply the same as you did here with the pipeline. If you specify --region for the pipeline or any of the targets, you must specify the same region for all of them.

   You can later edit the pipeline config and re-apply it to update the pipeline resource, but those changes do not affect any existing releases being managed by the original delivery pipeline.

You now have a delivery pipeline resource that can manage deployment of your releases.

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

   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.

Note: optionally, you can include --source=SOURCE_PATH to specify the location of the skaffold.yaml file. The default is the current directory.

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.

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

Note: you can also include --to-target=TARGET_NAME to specify a destination target. If you omit --to-target, the release is promoted to the next target in the promotion sequence.

Console

1. Open the Delivery pipelines page.

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

   

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

4. 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 beta 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 beta 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