You can define environment variables for Workflows at deployment time. For example, you can create a workflow that is dynamically configured depending on the environment to which it is deployed. Or, you can create a workflow that can be reused as a template and configured according to separately maintained environment variables.
Environment variables are set as arbitrary key and value string pairs that are accessible by your workflow at runtime. They are stored in the Workflows backend, are scoped to the workflow execution, and are immutable during the execution of a workflow.
All environment variables are bound to a deployment of a workflow, and can only be set or changed with a deployment. Creating or changing an environment variable requires a successful deployment. If a deployment fails for any reason, any changes to environment variables are not applied.
You can add, update, or remove user-defined environment variables using the Google Cloud CLI.
Reserved names
The built-in environment variables defined for Workflows are reserved and can't be set.
Note that you can't use the following when defining environment variables for Workflows:
| Key | Description |
|---|---|
Empty ('') |
Keys can't be an empty string. |
GOOGLE_ |
Keys can't contain the prefix GOOGLE_. |
WORKFLOWS_ |
Keys can't contain the prefix WORKFLOWS_. |
Set environment variables
You can define new variables or replace existing variables when deploying a workflow. To make additive changes, in this document, see Update environment variables instead.
Console
In the Google Cloud console, go to the Workflows page:
On the Workflows page, click Create.
On the Create workflow page, complete the appropriate fields to configure your workflow definition.
In the Environment variables (optional) section, click Add variable.
In the Name 1 field, specify the variable name.
In the Value 1 field, specify the variable value.
To add another variable, click Add variable.
Click Next.
After defining your workflow, to deploy it, click Deploy.
gcloud
To set an environment variable, use the --set-env-vars flag:
gcloud workflows deploy WORKFLOW_NAME \
--set-env-vars KEY1=VALUE1
Replace the following:
WORKFLOW_NAME: the ID of your workflow.KEY1=VALUE1: the environment variable name and its value; for example,MONTH=January.
Terraform
To create a workflow, use the
google_workflows_workflow resource
and modify your main.tf file as shown in the sample. For more information,
see
Create a workflow by using Terraform.
Use the user_env_vars argument to associate an environment variable with
the workflow revision.
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.
Set multiple environment variables
To set multiple environment variables, use a comma-separated list:
gcloud workflows deploy WORKFLOW_NAME \
--set-env-vars KEY1=VALUE1,KEY2=VALUE2
Escape comma characters
Since the comma character (,) is used to delimit environment variables, if
your variable values include commas, you must specify a different delimiter
character, for example, @:
gcloud workflows deploy WORKFLOW_NAME \
--set-env-vars ^@^KEY1=VALUE1,VALUE2,VALUE3@KEY2=VALUE2
Store variables in a file
To store your variables in a file (for example, under source control), use a
YAML file and the --env-vars-file flag:
gcloud workflows deploy WORKFLOW_NAME \
--env-vars-file FILE_PATH
Replace FILE_PATH with the path to a local YAML file
that lists the definitions for your environment variables. Note that the
variable names and values must be strings. All existing environment variables
are removed by Workflows before the new environment variables
are added.
For example, the contents of the YAML file might be the following:
KEY1: "value1" KEY2: "value2"
For more information about the deploy command, see
gcloud workflows deploy.
Access environment variables
To access an environment variable, make a call to the
sys.get_env() function in an
expression, passing the name of the environment variable as a parameter. The
name of the environment variable must be passed as a string.
For example, the following workflow assigns the value of the environment
variable KEY1 to a workflow variable called keyValue, and then outputs that
value:
main:
steps:
- init:
assign:
- keyValue: ${sys.get_env("KEY1")}
- returnResult:
return: ${keyValue}
Update environment variables
You can update user-defined environment variables for existing workflows. This is a non-destructive approach that changes or adds environment variables, but doesn't delete variables.
Console
In the Google Cloud console, go to the Workflows page.
Click the name of the workflow you want to update.
The Workflow details page appears.
To edit an existing environment variable, do either of the following:
Click the Details tab.
- Beside Environment variables, click the icon.
- Make your changes.
- To deploy the updated workflow, click Save.
Click Edit.
- In the Environment variables (optional) section, make your changes.
- To deploy the updated workflow, click Next and then Deploy.
gcloud
To update a variable, use the --update-env-vars flag:
gcloud workflows deploy WORKFLOW_NAME \
--update-env-vars KEY1=VALUE1
To update multiple environment variables, use a comma-separated list:
gcloud workflows deploy WORKFLOW_NAME \
--update-env-vars KEY1=VALUE1,KEY2=VALUE2
Delete environment variables
You can delete user-defined environment variables for existing workflows.
Console
In the Google Cloud console, go to the Workflows page.
Click the name of the workflow you want to update.
The Workflow details page appears.
To delete an existing environment variable, do either of the following:
Click the Details tab.
- Click the appropriate .
- Beside the environment variable that you want to delete, click the icon.
- To deploy the updated workflow, click Save.
Click Edit.
- Beside the environment variable that you want to delete, click the icon.
- To deploy the updated workflow, click Next and then Deploy.
gcloud
If you want to selectively remove environment variables, use the
--remove-env-vars flag:
gcloud workflows deploy WORKFLOW_NAME \
--remove-env-vars KEY1,KEY2
Alternatively, you can clear all previously set environment variables with the
--clear-env-vars flag:
gcloud workflows deploy WORKFLOW_NAME \
--clear-env-vars
Best practices
As a best practice, we recommend that you don't depend on or modify any environment variables that you haven't set explicitly. If you modify environment variables other than those that you have set explicitly, it might lead to unintended consequences.
Managing secrets
Environment variables can be used to configure workflows, but are not recommended as a way to store and consume secrets such as database credentials or API keys. These sensitive values should be stored separately from both your source code and environment variables, and not inadvertently sent to logs.
For storing secrets, we recommend that you review the best practices for secret management, and follow the instructions to use Secret Manager with Workflows.
Naming conventions
As a general rule, we recommend that environment variable keys consist solely of
uppercase letters, digits, and underscores (_), and that they don't begin with
a digit. Consider prefixing your user-defined environment variables with a
unique key to avoid conflicts with other variables.
Size limits
A maximum of 20 user-defined environment variables can be defined. Each
definition string (KEY=value) is limited to 4 KiB.