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:

  • Tasks, that define how to render and deploy for your custom target type

    Your implementations of the custom render and custom deploy consume values provided by Cloud Deploy and must fulfill a set of required outputs.

    The custom render is optional, but you must create one unless your custom target will work correctly if rendered with the Cloud Deploy built-in renderers.

  • A custom target type definition

    The CustomTargetType is a Cloud Deploy resource that identifies the tasks 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 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 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 custom renders

For custom renders, 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, 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 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 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 must upload a file named results.json containing the results of this render operation. For more information, see Outputs from custom render.

Outputs from custom render

Your custom render 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 (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

  • Rendered configuration file or files

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

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

      Valid values are SUCCEEDED and FAILED.

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

    • 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. We recommend this file be human readable, so that you and other users in your organization can view this file in the