Pass parameters to your deployment

Using Cloud Deploy, you can pass parameters for your release, and those values are provided to the manifest or manifests before those manifests are applied to their respective targets. This substitution is done after manifests are rendered, as the final step in the Cloud Deploy render operation. Values are provided to all manifests identified in your skaffold.yaml file that contain the corresponding placeholders.

All you need to do is include placeholders in your manifest, and set the values for those placeholder in either your Cloud Deploy delivery pipeline or target configuration, or when you create a release.

This article describes how to make that happen.

Why use deploy parameters?

A typical use for this would be to apply different values to manifests for different targets in a parallel deployment. But you can use deploy parameters for anything that requires post-render key-value pair substitution in your manifest.

How it works

The following steps describe the general process for configuring deploy parameters and providing values:

1. You configure deploy parameterization, as described here.

   This includes the following:

   • Add the placeholders to your manifest.

   • Add values for those placeholders.

     There are three ways to do this, described here.

2. When you create a release, your manifest is rendered.

   If you start with a templated manifest, values are applied now for template variables. If you start with a raw manifest, it remains unchanged. This rendering is done by Skaffold.

   However, you can have additional variables in your manifest for which values aren't applied at render time. These are the deploy parameters described in this document.

   At release creation, all deploy parameters are compiled into a dictionary, which is used to substitute values before the manifests are applied.

   Note: If a given deploy parameter (key) is assigned more than one value, the release fails.

3. After rendering, Cloud Deploy substitutes values for deploy parameters.

   These are the values you configured in the first step.

   The rendering process already applied values to manifest templates, replacing some values, and adding labels specific to Cloud Deploy. But the values for these deploy parameters are substituted after rendering. The differences between manifest templates and deploy parameters are described here.

4. The manifest is applied to the target runtime, to deploy your application.

   This includes the values substituted at render time, and the values for any deploy parameters

Different ways to pass values

You can provide parameters, and values for those parameters in three ways:

• In the delivery pipeline definition

  You provide the parameter and its value in the definition for a stage in the delivery pipeline progression. The parameter is passed to the target represented by that stage. If that stage references a multi-target, the values set here are used for all child targets.

  This method lets you replace a value for all releases within a given pipeline, for all affected targets. The parameters defined for a stage identify a label, and the corresponding target for that stage must have a matching label.

• In the target definition

  You configure the parameter and its value in the definition for the target itself. This method lets you replace a value for that target for all releases.

• On the command line, when you create a release

  You include the parameter and its value using the --deploy-parameters flag on the gcloud deploy releases create command.

  This method lets you replace a value at release creation time, applying that value to that manifests of all affected targets.

Configuration for these is explained in more detail here.

Can I use more than one of these methods?

Yes, you can include deploy parameters in the pipeline stage, in the target config, and on the command line. The result is that all the parameters are accepted and added to the dictionary. However, if a specific parameter is passed in more than one place, but with different values, the gcloud deploy releases create command fails with an error.

Deploy parameters with custom targets

You can use any deploy parameter as environment variables in custom targets. When doing so, use the syntax specified for custom targets.

How is this different from manifest templates

Deploy parameters, as described in this article, are distinguished from placeholders in a templated manifest by the syntax. But if you're wondering why you would need deploy parameters instead of just using the standard techniques for templated manifests, the following table shows the different purposes:

Technique	Substitution time	Applies to
Manifest template	Rendering phase	Specific release; specific target
On command line	Post-rendering	Specific release; all targets
On delivery pipeline	Post-rendering	All releases; specific targets (by label)
On target	Post-rendering	All releases; specific target

This document is about deploy parameters only (on command line, pipeline, and target), not templated manifests.

Limitations

• For each type of parameter, you can create a maximum of 25 parameters.

• A child target can additionally inherit up to 25 parameters from its parent multi-target, up to a maximum of 100 parameters on the targets, including those set on the pipeline stage.

• The key name is limited to a maximum of 63 characters, and the following regular expression:

  ^[a-zA-Z0-9]([-A-Za-z0-9_.]{0,61}[a-zA-Z0-9])?$
  

  One exception to this is when you're using a deploy parameter as an environment variable in a custom target, you must use a slash between the keyword customTarget and the variable name (customTarget/VAR_NAME). See Required inputs and outputs for the supported syntax.

• The prefix CLOUD_DEPLOY_ is reserved, and cannot be used for a key name.

• You can't have two keys of the same name applied to the same target.

• The value can be empty, but has a maximum of 512 characters.

Configure deploy parameters

This section describes how to configure deploy parameter values that will be applied to your Kubernetes manifest, your Cloud Run service, or your Helm template.

Besides configuring those key-value pairs, you need to add the placeholder or placeholders to your manifest, as described in this section.

Add placeholders to your manifest

In your Kubernetes manifest (for GKE) or service YAML (for Cloud Run), you add placeholders for any values you want to substitute after rendering.

Syntax

For releases that aren't using the Helm renderer with Skaffold, use the following syntax for your placeholders:

[PROPERTY]: [DEFAULT_VALUE] # from-param: ${VAR_NAME}

In this line...

• PROPERTY:

  Is the configuration property in your Kubernetes manifest or Cloud Run service YAML.

• DEFAULT_VALUE

  Is a value to use if there are no values provided for this property on the command line or in the pipeline or target config.

• # from-param:

  Uses a comment character to set off the Cloud Deploy deploy-parameters directive, and from-param: tells Cloud Deploy that a deploy-parameters placeholder follows.

• ${VAR_NAME}

  Is the placeholder to substitute. This must match the key of a key-value pair provided in the delivery pipeline or target config, or upon release creation.

Helm-specific syntax

If you're using the Helm renderer with Skaffold, use the following syntax in your Helm template to add placeholders:

[PROPERTY]:  {{ .Values.VAR_NAME }} 

Add a parameter to the pipeline stage

You can add key-value pairs to a stage in the delivery pipeline progression. This is useful for parallel deployments, to distinguish among child targets.

1. Add the placeholders to your Kubernetes manifest or Cloud Run service, as described here.

   Here's an example:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
    name: nginx-deployment
    labels:
      app: nginx
   spec:
    replicas: 1 # from-param: ${deploy_replicas}
    selector:
      matchLabels:
        app: nginx
    template:
      metadata:
        labels:
          app: nginx
      spec:
        containers:
        - name: nginx
          image: nginx:1.14.2
          ports:
          - containerPort: 80
   

2. Configure your delivery pipeline to include deployParameters for the applicable pipeline stage.

   The following YAML is the configuration for a pipeline stage whose target is a multi-target, which in this case has two child targets:

   serialPipeline:
    stages:
      - targetId: dev
        profiles: []
      - targetId: prod  # multi-target
        profiles: []
        deployParameters:
          - values:
              deploy_replicas: 1
              log_level: "NOTICE"
            matchTargetLabels: # optional, applies to all resources if unspecified; AND'd
              my-app: "post-render-config-1"
          - values:
              deploy_replicas: 2
              log_level: "WARNING"
            matchTargetLabels: # optional, applies to all resources if unspecified; AND'd
              my-app: "post-render-config-2"
   

   In this delivery pipeline configuration, the deployParameters stanza includes two values, each of which has the following:

   • The variable name, which is the same name as the variable you set in the manifest

   • A value for that variable

   • One or more labels (optional) to match against target-specific labels

     If you don't specify a label, in a matchTargetLabels stanza, that value is used for all targets in the stage.

3. If you included matchTargetLabels , you also must include labels on the targets, to match them. In this way, you identify which value to assign to which child target.

   The target must match all labels set in the values stanza.

   If you omit matchTargetLabels, the values you set on the pipeline are applied to all child targets. But if you set more than one value for the same parameter, the release will fail.

After each manifest is rendered, Cloud Deploy adds the value for each variable into the rendered manifest.

Add a parameter to the target configuration

You can add key-value pairs to a target. If you're using deploy parameters to distinguish among multiple child targets, configure them on those child targets, not on the multi-target.

1. Configure your Kubernetes manifest or Cloud Run service definition using a parameter in place of the value you want to set at deploy time.

   Here's an example:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
    name: nginx-deployment
    labels:
      app: nginx
   spec:
    selector:
      matchLabels:
        app: nginx
    template:
      metadata:
        labels:
          app: nginx
      spec:
        containers:
        - name: nginx
          image: nginx:1.14.2
          env:
          - name: envvar1
            value: example1 # from-param: ${application_env1}
          - name: envvar2
            value: example2 # from-param: ${application_env2}
   

   In this manifest, the parameter envvar1 is set to a default of example1, and envvar2 is set to a default of example2.

2. Configure your targets to include deployParameters.

   For each parameter you're including, you identify the following:

   • The key name, which is the same name as the key (variable) you set in the manifest.

   • A value for that key. If you don't provide a value, the default value set in the manifest is used.

   The following YAML is the configuration for two targets. Each target includes a deployParameters stanza setting a value. Each target also includes a label, to be matched with deploy parameters configured on a pipeline stage.

   apiVersion: deploy.cloud.google.com/v1beta1
   kind: Target
   metadata:
     name: prod1
     labels:
       my-app: "post-render-config-1"
   description: development cluster
   deployParameters:
     application_env1: "newValue1"
   ---
   
   apiVersion: deploy.cloud.google.com/v1beta1
   kind: target
   metadata:
     name: prod2
     labels:
       my-app: "post-render-config-2"
   description: development cluster
   deployParameters:
     application_env1: "newValue2"
   

When the release is created, but after the manifests are rendered, Cloud Deploy adds these values to the rendered manifests if they include the associated keys.

Pass a parameter at release creation

Follow these steps to pass parameters and values to the release:

1. Configure your Kubernetes manifest or Cloud Run service definition using a parameter in place of the value you want to set at deploy time.

   Here's an example:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
    name: nginx-deployment
    labels:
      app: nginx
   spec:
    selector:
      matchLabels:
        app: nginx
    template:
      metadata:
        labels:
          app: nginx
      annotations:
        commit: defaultShaValue # from-param: ${git-sha}
      spec:
        containers:
        - name: nginx
          image: nginx:1.14.2
   

   In this example, the commit SHA is set as a variable called ${git-sha}. A value for this is passed at release creation, using the --deploy-parameters= option, as seen in the next step.

   Syntax for this variable is $ plus the variable name in braces. In this example, it's ${git-sha}.

2. When you create a release, include the --deploy-parameters option on the gcloud deploy releases create command.

   --deploy-parameters takes a comma-separated list of key-value pairs, where the key is the placeholder you added to the manifest.

   The command will look similar to this:

   gcloud deploy releases create test-release-001 \
   --project=my-example-project \
   --region=us-central1 \
   --delivery-pipeline=my-params-demo-app-1 \
   --images=my-app-image=gcr.io/google-containers/nginx@sha256:f49a843c290594dcf4d193535d1f4ba8af7d56cea2cf79d1e9554f077f1e7aaa \
   --deploy-parameters="git-sha=f787cac"
   
   

When the release is created, but after manifest rendering, Cloud Deploy provides the values to the rendered manifests if they include the associated keys.

View all parameters for a release

You can view the parameters that have been set for a given release. They're displayed in a table on the Release details page and on the command line (gcloud deploy releases describe).

1. From the main Cloud Deploy page, click the delivery pipeline that includes the release you want to see.

2. On the Release details page, select the Artifacts tab.

All deploy parameters that have been set for this release are shown in a table, with the variable name and value in one column, and the affected target or targets in the other column.

What's next

• Try the quickstart: Use deploy parameters.

• Find out more about using parallel deployments.