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:
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.
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.
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.
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.
-
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 thegcloud 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.
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.
Deploy Parameters placeholders can't be used for Helm configuration values, but must be passed by convention.
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, andfrom-param:
tells Cloud Deploy that adeploy-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.
Parameters for Helm chart values
If you are rendering a Helm chart that accepts
configuration values,
and you want to set those values using deploy parameters, the deploy parameters
must have names that match the Helm configurations values that you want to set.
All deploy parameters are passed to Helm as --set
arguments at render time,
with no modification of your skaffold.yaml
required.
For example, if your skaffold.yaml
is installing a Helm chart that takes a
configuration parameter of webserver.port
to specify which port the web server
would be starting on, and you want to set this dynamically from a deploy
parameter, you would need to create a deploy parameter with the
name webserver.port
with the value you want for the web server port.
Therefore if you are not only referencing Helm templates in your skaffold.yaml
,
but also authoring them, you can utilise the
standard Helm variable syntax
of {{ .Values.VAR_NAME }}
in your Helm templates.
For example, if we have a deploy parameter of webserver.port
configured,
we could utilise it like so:
apiVersion: apps/v1
kind: Deployment
metadata:
name: webserver
spec:
replicas: 3
selector:
matchLabels:
app: webserver
template:
metadata:
labels:
app: webserver
spec:
containers:
- name: webserver
image: gcr.io/example/webserver:latest
ports:
- containerPort: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.
name: web
env:
- name: WEBSERVER_PORT
value: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.
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.
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
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 twovalues
, 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.
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
, thevalues
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.
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 ofexample1
, andenvvar2
is set to a default ofexample2
.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:
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}
.When you create a release, include the
--deploy-parameters
option on thegcloud 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.
Deploy parameters with custom targets
You can use any deploy parameter as an environment variable in custom targets. When doing so, use the syntax specified for custom targets.
Deploy parameters intended as inputs for custom targets can start with
customTarget/
, for example customTarget/vertexAIModel
. If you use this
prefix, use the following syntax when you reference a deploy parameter as an
environment variable:
CLOUD_DEPLOY_customTarget_[VAR_NAME]
Where VAR_NAME
is the name following the slash in the
deploy parameter name. For example, if you define a
deploy parameter named customTarget/vertexAIModel
, reference it as
CLOUD_DEPLOY_customTarget_vertexAIModel
.
Deploy parameters with deploy hooks
You can use any deploy parameter as an environment variable in deploy hooks.
Deploy parameters with deployment verification
You can use any deploy parameter as an environment variable in deployment verification.
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
).
From the main Cloud Deploy page, click the delivery pipeline that includes the release you want to see.
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.