About custom targets

This document describes how custom targets work in Cloud Deploy.

Cloud Deploy includes built-in support for various runtime environments as targets. But the list of supported target types is finite. With custom targets, you can deploy to other systems besides the supported runtimes.

A custom target is a target that represents an arbitrary output environment other than a runtime that Cloud Deploy supports.

The page Create a custom target describes the process of defining a custom target type and implementing it as a target in a delivery pipeline.

What goes into a custom target?

Each custom target consists of the following components:

• Custom actions, defined in skaffold.yaml

  These are similar to how you define deploy hooks. In the skaffold.yaml file, you define customActions, where each custom action identifies a container image to use, and commands to run on that container.

  In this way, the custom target is simply a custom-defined action or set of actions.

  For any custom target type, you configure a custom render action and a custom deploy action. These actions consume values provided by Cloud Deploy and must fulfill a set of required outputs.

  The custom render action is optional, but you must create one unless your custom target will work correctly if rendered by skaffold render, which is the default for Cloud Deploy.

• A custom target type definition

  The CustomTargetType is a Cloud Deploy resource that identifies the custom actions (separately defined in your skaffold.yaml) that targets of this type use for release render and rollout deploy activities.

• A target definition

  The target definition for a custom target is the same as for any target type, except that it includes the customTarget property, whose value is the name of the CustomTargetType.

With those components in place, you can use the target as you would any target, referencing it from your delivery pipeline progression, and making full use of Cloud Deploy features, such as promotion and approvals, and rollbacks.

An example

The quickstart Define and use a custom target type creates a custom target type that includes simple commands to run on a container image—one command for render and one for deploy. The commands, in this case, just add text to the required output files for render and deploy.

For more examples, see Custom target examples.

Required inputs and outputs

Any custom target type defined for Cloud Deploy must satisfy requirements for input and output, for both render and deploy. This section lists what inputs and outputs are required, and how they're provided.

Cloud Deploy provides the required inputs, for both render and deploy, as environment variables. The following sections list these inputs, as well as the outputs that your custom render and deploy actions must return.

Deploy parameters as environment variables

In addition to the environment variables listed in this section, Cloud Deploy can pass to your custom containers any deploy parameters you've set.

Learn more.

Inputs to render actions

For custom render actions, Cloud Deploy provides the following inputs, as environment variables. For multi-phase rollouts (canary deployments), Cloud Deploy provides these variables for each phase.

• CLOUD_DEPLOY_PROJECT

  The Google Cloud project number for the project in which the custom target is created.

• CLOUD_DEPLOY_PROJECT_ID

  The Google Cloud project ID for the project.

• CLOUD_DEPLOY_LOCATION

  The Google Cloud region for the custom target type.

• CLOUD_DEPLOY_DELIVERY_PIPELINE

  The name of the Cloud Deploy delivery pipeline referencing the custom target type.

• CLOUD_DEPLOY_RELEASE

  The name of the release for which the render operation is invoked.

• CLOUD_DEPLOY_TARGET

  The name of the Cloud Deploy target that uses the custom target type.

• CLOUD_DEPLOY_PHASE

  The rollout phase to which the render corresponds.

• CLOUD_DEPLOY_REQUEST_TYPE

  For the custom render action, this is always RENDER.

• CLOUD_DEPLOY_FEATURES

  A comma-separated list of Cloud Deploy features which the custom container must support. This variable is populated based on features configured in your delivery pipeline.

  If your implementation doesn't support the features in this list, we recommend that it fail during rendering.

  For standard deployments, this is empty. For canary deployments, the value is CANARY. If the value provided by Cloud Deploy is CANARY, your render action is invoked for each phase in the canary. The canary percentage for each phase is provided in the CLOUD_DEPLOY_PERCENTAGE_DEPLOY environment variable.

• CLOUD_DEPLOY_PERCENTAGE_DEPLOY

  The percentage of deployment associated with this render operation. If the CLOUD_DEPLOY_FEATURES environment variable is set to CANARY, your custom render action is called for each phase, and this variable is set to the canary percentage for each phase. For standard deployments and for canary deployments that have reached the stable phase, this is 100.

• CLOUD_DEPLOY_STORAGE_TYPE

  The storage provider. Always GCS.

• CLOUD_DEPLOY_INPUT_GCS_PATH

  The Cloud Storage path for the render-file archive written when the release was created.

• CLOUD_DEPLOY_OUTPUT_GCS_PATH

  The Cloud Storage path where the custom render container is expected to upload artifacts to be used for deployment. Note that the render action must upload a file named results.json containing the results of this render operation. For more information, see Outputs from render action.

Outputs from render action

Your custom render action must provide the information described in this section. The information must be included in the results file, named results.json, located in the Cloud Storage bucket provided by Cloud Deploy.

• Rendered configuration file or files

• A results.json file, containing the following information:

  • An indication of the success or failure state of the custom action.

    Valid values are SUCCEEDED and FAILED.

  • (Optional) any error messages that are generated by the custom action.

  • The Cloud Storage path for the rendered configuration file or files.

    The path for all the rendered configuration files is the full URI. You populate it partly using the value of the CLOUD_DEPLOY_OUTPUT_GCS_PATH provided by Cloud Deploy.

    You must provide the rendered configuration file, even if it's empty. The contents of the file can be anything, in any format, as long as it's consumable by your custom deploy action. We recommend this file be human readable, so that you and other users in your organization can view this file in the release inspector.

  • (Optional) a map of any metadata you want to include

    Your custom target creates this metadata. This metadata is stored on the release, in the custom_metadata field.

If you need to examine the results.json file, for example for debugging, you can find the Cloud Storage URI to it in the Cloud Build logs.

Example render results file

The following is a sample results.json file output from a custom render action:

{
  "resultStatus": "SUCCEEDED",
  "manifestFile": "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/manifest.yaml",
  "failureMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

Inputs to deploy actions

For custom deploy actions, Cloud Deploy provides the following inputs, as environment variables:

• CLOUD_DEPLOY_PROJECT

  The Google Cloud project number for the project in which the custom target is created.

• CLOUD_DEPLOY_PROJECT_ID

  The Google Cloud project ID for the project.

• CLOUD_DEPLOY_LOCATION

  The Google Cloud region for the custom target type.

• CLOUD_DEPLOY_DELIVERY_PIPELINE

  The name of the Cloud Deploy delivery pipeline referencing the target that uses the custom target type.

• CLOUD_DEPLOY_RELEASE

  The name of the release for which the deploy operation is invoked.

• CLOUD_DEPLOY_ROLLOUT

  The name of the Cloud Deploy rollout that this deploy is for.

• CLOUD_DEPLOY_TARGET

  The name of the Cloud Deploy target that uses the custom target type.

• CLOUD_DEPLOY_PHASE

  The rollout phase to which the deploy corresponds.

• CLOUD_DEPLOY_REQUEST_TYPE

  For the custom deploy action, this is always DEPLOY.

• CLOUD_DEPLOY_FEATURES

  A comma-separated list of Cloud Deploy features which the custom container must support. This variable is populated based on features configured in your delivery pipeline.

  If your implementation doesn't support the features in this list, we recommend that it fail during rendering.

  For standard deployments, this is empty. For canary deployments, the value is CANARY. If the value provided by Cloud Deploy is CANARY, your render action is invoked for each phase in the canary. The canary percentage for each phase is provided in the CLOUD_DEPLOY_PERCENTAGE_DEPLOY environment variable.

• CLOUD_DEPLOY_PERCENTAGE_DEPLOY

  The percentage of deployment associated with this deploy operation. If the CLOUD_DEPLOY_FEATURES environment variable is set to CANARY, your custom deploy action is called for each phase, and this variable is set to the canary percentage for each phase. Your deploy action must run for each phase.

• CLOUD_DEPLOY_STORAGE_TYPE

  The storage provider. Always GCS.

• CLOUD_DEPLOY_INPUT_GCS_PATH

  The Cloud Storage path where the custom renderer wrote the rendered configuration files.

• CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

  The Cloud Storage path to the rendered Skaffold configuration.

• CLOUD_DEPLOY_MANIFEST_GCS_PATH

  The Cloud Storage path to the rendered manifest file.

• CLOUD_DEPLOY_OUTPUT_GCS_PATH

  The path to the Cloud Storage directory where the custom deploy container is expected to upload deploy artifacts. For more information, see Outputs from deploy action.

Outputs from deploy action

Your custom deploy action must write a results.json output file. This file must be located in the Cloud Storage bucket provided by Cloud Deploy (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

The file must include the following:

• An indication of the success or failure state of the custom deploy action.

  The following are the valid statuses:

  • SUCCEEDED

  • FAILED

  • SKIPPED (for canary deployments where canary phases are skipped to go straight to stable.)

• (Optional) a list of deploy artifact files, in the form of Cloud Storage paths

  The path is the full URI. You populate it partly using the value of the CLOUD_DEPLOY_OUTPUT_GCS_PATH provided by Cloud Deploy.

  Files listed here are populated in job run resources as deploy artifacts.

• (Optional) a failure message, if the custom deploy action is unsuccessful (returning a FAILED state)

  This message is used to populate the failure_message on the job run for this deploy action.

• (Optional) a skip message, to provide additional information if the action returns a SKIPPED status.

• (Optional) a map of any metadata you want to include

  Your custom target creates this metadata. This metadata is stored on the job run and on the rollout, in the custom_metadata field.

If you need to examine the results.json file, for example for debugging, you can find the Cloud Storage URI for it in the Cloud Build release render logs.

Example deploy results file

The following is a sample results.json file output from a custom deploy action:

{
  "resultStatus": "SUCCEEDED",
  "artifactFiles": [
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file1.yaml",
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file2.yaml"
  ],
  "failureMessage": "",
  "skipMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

Further information about custom actions

Here are some things to keep in mind when setting up and using custom target types.

Executing the custom actions

Your custom render and deploy actions run in the Cloud Deploy execution environment. You can't configure your custom actions to run on a Google Kubernetes Engine cluster.

Using remote, reusable Skaffold configs

As described in this document, you configure your custom action in the skaffold.yaml file provided at release creation. But you can also store Skaffold configs in a Git repository or in a Cloud Storage bucket and reference them from your custom target type definition. This lets you use custom actions defined and stored in a single, shared location, instead of including the custom actions with each releases's skaffold.yaml file.

Custom targets and deployment strategies

Custom targets are fully supported for standard deployments.

Cloud Deploy supports canary deployments as long as the custom renderer and deployer support the canary feature.

You must use custom canary configuration. Automated and custom-automated canaries are not supported.

Custom targets and deploy parameters

You can use deploy parameters with custom targets. You can set them on the delivery pipeline stage, on the target that uses a custom target type, or on the release.

Deploy parameters are passed to your custom render and deploy containers, as environment variables, in addition to those already provided.

Custom target examples

The cloud-deploy-samples repository contains a set of sample custom target implementations. The following samples are available:

• GitOps

• Vertex AI

• Terraform

• Infrastructure Manager

• Helm

Each sample includes a quickstart.

These samples are not a supported Google Cloud product, and are not covered by a Google Cloud support contract. To report bugs or request features in a Google Cloud product, contact Google Cloud support.

What's next

• Now that you know about custom targets, find out how to configure and use them.

• Try the quickstart: Define and use a custom target type.

• Learn more about configuring Cloud Deploy targets.

• Learn about Cloud Deploy execution environments.