Variables and Secrets

Terraform Variables and Environment Variables

Using an infrastructure-as-code model, variables are used to customize certain aspects of a configuration for a specific deployment, without having to change the code. In this way, a single configuration can be used in different contexts to create different deployments.

Variables can be anything from ports and IPs to cloud credentials, availability zones, and images.

env0 supports two types of variables:

  • Terraform Variables (also called Input Variables) - These are defined in the Terraform configuration files. Their values are set by env0 when running IaC commands.
  • Environment Variables - These are set by env0 in the shell running IaC commands and Custom Flows.

📘

Built-in Terraform/Terragrunt Environment Variables Support

Terraform and Terragrunt support various environment variables to alter the behavior of the deployment. You can add those as environment variables inside the env0 platform as well, under name and the appropriate value.
See all the supported Terraform environment variables and the relevant Terragrunt environment variables.

For example:
If you wish to perform a state migration you can add the TF_CLI_ARGS_init environment variable and as a valueby adding -migrate-state.
You can read more about TF_CLI_ARGS here.

Terraform Variables and Environment Variables are both managed by the user in env0.

Variables and Scopes in env0

env0 uses hierarchical scopes to manage variables (both Terraform Variables and Environment Variables). You can set variables for an Organization, a Template, a Project, or a specific Environment.

Each scope inherits the variables defined in the higher scopes. Hence, a template will have all the variables that are set for the organization. A project will have all the variables that are set for the organization, or any parent projects it has. And a new Environment will have all the variables that are set for the project, template, and organization.

You can change the value of a variable inherited from a higher scope, but not its name.

The different variable scopes reflect the fact that variables are used for different purposes and might be set by different people.

📘

Example

  • An administrator sets cloud credentials in the Organization scope to apply to all the environments managed in an organization.

  • A DevOps engineer creates a new template. They want to have the option for the user to select from two different machine sizes. Therefore they use the same Terraform configuration, with the instance type set as a variable, and create two templates, each with a different value for the instance size variable.

  • A developer creates a new environment. They don't need to know the credentials, or set the sizes of instances. They choose a template and let env0 use the variables defined in the higher scopes. They can, however, still make further customizations by overriding a Terraform Variable which specifies which port to use.

Variables Value Types

The env0 platform supports several value types of variables:

Free Text

This is the most-common variable value type that holds a plain text value. To accommodate your variable with a value, simply type your desired text or leave it blank. This value type also supports setting it as secrets.

HCL Format

This type allows you to define complex terraform values, similar to what can you define in the .tf file
We support all complex terraform types.
This format is only available under Terraform Variables section.

Examples for HCL values:

{
  name = "John"
  age  = 52
}
[
  "value1", 
  "value2"
]
{
  objects_list = [
    {
      first_field  = "value1"
      second_field = "value2"
    },
    {
      first_field  = "value1"
      second_field = "value2"
  }]
}

JSON Format

This type allows you to define complex terraform values such as JSON format.
We support all complex terraform types.
This format is only available under the Terraform Variables section.

Examples for JSON values:

{
  "list_of_stuff": [
    { "some_field": "value", "other_field": "other value" },
    { "something": "value1", "something_else": "value2" }
  ]
}

Dropdown List

This is a variable value that is configured with a predefined set of options that you can select as a value. This allows you to govern your specific variable with a dropdown of available options that any other organization or user can select from. Dropdown List variables can be re-selected in lesser scopes but can be configured (aka add/remove options) only in their original scope.

To add/remove options of a Dropdown List variable:

  1. Add a new Dropdown List variable.
  2. Click on its value input and a new select dropdown will be opened.
  3. To add an option, type the desired option and click + Add Option button on the opened select's footer.
  4. To remove an existing option,click the Trash icon next to the relevant option.
  5. Don't forget to hit the save button to commit your changes.

Variable Settings

You can configure advanced settings for every variable in our system by opening the advanced settings form -
The rightmost icon in the variable line.

Required Variable

This setting means that you can't start deployment without first setting a value for this variable.

In higher scopes (Organization, Template, Project), "Required" variables can be set without a value. The user will be required to enter a value before a deployment.

Read Only Variable

This setting means you locked this variable for all lower scopes. When configured, none of the lower scopes can override it.

Here’s a good example for using in this setting: When the organization admin wants to enforce using in the same stage and identifier for all environments in the organization, The admin can enable it and no one can override it or delete it.

Regular Expression Validation (only for Free Text variables)

You can define a regular expression that value should match. If you set the regular expression in upper scope, you can keep the value empty - the validation will be enforced in lower scope.

Variables Description

Variables have an optional description that is editable only at the scope in which they are created, and viewable in lower scopes. Unlike values, the description cannot be overridden.

1597

Load Variables From Terraform Code

On a Terraform Variables scope, clicking on Load Variables From Code will load the variables from your Terraform code directory. All will be at default values.

Note that loaded variables will not be saved until the Save button is clicked, and only string- type variables will be loaded, as is generally done in Terraform Variables.

👍

Complex value

All the default complex values will be loaded by env0 JSON format. You will be able to edit them as JSON files.

Secrets

For security reasons, some variables needed for flow execution should not be exposed to user executing flows. This is known as Secrets Management. The most common use case for secrets management is cloud credentials.

In env0, secrets are variables that are marked as sensitive. A sensitive variable has its value masked after you save it. If you'd like to change an existing sensitive variable, simply click on the masked value to clear it, type in the new secret value, and then click save.

Like other variables, secrets are inherited and can be defined in any scope.

📘

Secrets in a Self-Hosted Agent

If your organization manages self-hosted agents, you can control whether users are allowed to store sensitive data within env0 by the policy.

Additionally, you can reference a variable from an external secret manager in one of the following ways:

  1. AWS Secret Manager
  2. GCP Secret Manager
  3. Azure Key Vault
  4. HashiCorp Vault

You can read more on how to configure it here

Manage Variables

To manage variables at the organization scope, select the Variables tab on the main screen. This shows a list of the organization's Environment Variables and Terraform Variables. You can edit their names or values, and add new ones.

Don't forget to save any changes before leaving the page, or they will be lost.

To manage variables at the Template level, go to the Template tab and select the template you are interested in. Click Settings, then select the Variable tab. Here you can modify variables for the template.

At the environment level, you can set the variables just before deployment. When you create a new environment or redeploy, you’ll get a pop-up with environment details to fill in. Select the Variable section and modify the variables for that specific environment.

For an environment that already exists, you edit the variables settings by redeploying (or queuing) a new deployment or under the Variables section (the latter can only be done if the environment has no running deployment).

📘

Note

  • Changes to variables in a higher scope will change the variables in all inheriting scopes.
  • Changes to variables in an existing environment will not take effect until the environment is redeployed. When env0 runs a deployment, it stores the variable names to be used in undeploy so changes for an Active environment will not affect the destroy process.
  • If a user does not have the RUN APPLY permission (like in the Planner project role), any variable changes they make when running a plan, will only be saved to the environment if the plan is approved. If the plan is canceled or the deployment fails, the proposed variable changes will not be saved. For a user with RUN APPLY permission, changes will be saved once the deployment is queued.

Variable Precedence

When using a combination of TF_VAR_* and ENV0_TERRAFORM_CONFIG_FILE_PATH option as described here, and with Terraform Variables in the UI, you might wonder which variable will actually be used.

env0's Terraform Variables (created in the UI) are actually loaded into an env0.auto.tfvars.json file during run-time and ENV0_TERRAFORM_CONFIG_FILE_PATH uses the -var-file flag for plan and apply.

With this information, along with the Variable Definition Precedence, essentially this will be the order of precedence, with later sources taking precedence over earlier ones:

  • Environment Variables: TF_VAR_*
  • env0 UI Terraform Variables: env0.auto.tfvars.json
  • variable files specified through ENV0_TERRAFORM_CONFIG_FILE_PATH

If you also use Custom Flow to manage variables, then you could create your own auto.tfvars and make sure it is named alphabetically ahead or behind env0.auto.tfvars.json if you want your values to get overwritten by env0 or override env0, respectively. For example, if you created a file acme.auto.tfvars.json, variables would get overwritten by env0's UI tf vars.

Ansible Variables

Currently, there's no way to set Ansible variables via the UI.
However, you can set Ansible variables by setting any environment variable prefixed by ANSIBLE_VAR_.

Any variable added to that prefixed would be parsed and added to the --extra-vars flag.

More about it here.

📝

Additional Content


What’s Next

env0 also has special categories of secrets that it needs for actually running, including