Terraform variables and shell variables both manage values, but operate at different levels. Terraform variables are strongly typed parameters defined within your infrastructure code to make it reusable and customizable, with values passed in via dedicated .tfvars files, command-line flags, or specially named environment variables. In contrast, shell variables are untyped values stored within a command-line session that can be exported as environment variables to configure the behavior of any program, including Terraform, that is run from that session.

Terraform & OpenTofu Variables

Scalr uses input variables the same way they are used in Terraform or OpenTofu OSS, no extra configuration is needed other than having the option to create them directly in the Scalr UI. When variables are set directly in Scalr, Scalr will pass those variables to Terraform as a terraform.tfvars.json or opentofu.tfvars.json file.

Terraform and OpenTofu variables can be marked as sensitive or HCL values as needed:

Alternatively, variable files can be passed in as part of the workspace configuration or at run time. Values defined in the .tfvars files have a higher priority than ones set in the Scalr UI/backend. To enforce values from the Scalr UI/backend users must specify the variable as final in the Scalr Terraform variables section of the workspace.

📘

terraform.tfvars.json and opentofu.tfvars.json name is reserved

terraform.tfvars.json and terraform.tfvars are reserved filenames and cannot be used as Scalr uses that to pass in variables. The same goes for opentofu.tfvars.json and opentofu.tfvars

If variables are passed in at run time, they will only be used for that run. This is great for use cases where you need to specify a temporary value; otherwise, permanent values should be passed in by a file or stored in the workspace UI. Run variables can be passed from the Terraform/Tofu CLI:

terraform plan -var="foo=bar"

Or in the Scalr UI:

Shell Variables

In addition to Terraform input variables, there are use cases for declaring shell variables in the run time environment. Shell variables can be declared in Scalr and are exported into the Terraform runtime environment using export var=value.

• Pass in non-credentials configuration values to providers, such as location (see individual provider docs).
• Set values for Terraform input variables with TF_VAR_{variable_name}={value}, alternatively, the Terraform variable type can also be used.
• Pass in data to be used in scripts executed by provisioners or data "external" {}.
• Set custom parallelism with TF_CLI_ARGS_plan="-parallelism=N" and TF_CLI_ARGS_apply="-parallelism=N" (where N is the desired parallelism value).
• Set the log level with TF_LOG=TRACE
• Set Terraform debug/behavioral variables.

Built-In Variables

The following shell variables are built into the runtime environment for use as needed. All variables below can also be used as TF_VAR variables by adding TF_VAR_before the variable name:

• SCALR_RUN_ID - The ID of the current run.
• SCALR_HOSTNAME - The Scalr hostname.
• SCALR_TERRAFORM_OPERATION - The current Terraform operation (plan or apply).
• SCALR_TERRAFORM_EXIT_CODE - The exit code (0 or 1) of the previous operation (plan or apply) and only available in after hooks.
• SCALR_RUN_IS_DESTROY - If the code is 1, then the run is the equivalent to a terraform destroy. If it is 0, then it is a terraform apply. This is helpful for custom hooks that will execute if the apply is a destroy or not.
• SCALR_RUN_VCS_BRANCH - The branch name of the VCS repo i.e. main
• SCALR_RUN_VCS_COMMIT- The commit hash for a VCS triggered run i.e. e59f09e
• SCALR_RUN_VCS_REPOSITORY - The repository use for a VCS triggered run.
• SCALR_RUN_MODE - This will return the type of run that was executed. Possible values are:
  • apply - Plan & Apply
  • dry - Plan only
  • refresh - Refresh only
  • skip_refresh - Skip refresh
• SCALR_RUN_SOURCE - The source that triggered the run. Possible values are:
  • vcs - The run was triggered by a VCS provider.
  • cli - The run was triggered from the Terraform or OpenTofu CLI.
  • scalr-cli- The run was triggered from the Scalr CLI
  • run-trigger - The run was triggered from the run triggers feature.
  • schedule - The run was triggered based on a schedule being set in the workspace.
  • api- The run was triggered from the Scalr API.
  • configuration version - When the run is triggered based on auto-queue runs being enabled in the workspace and the first CV uploaded triggers a run.
  • ui - for all runs triggered from the UI.
• SCALR_WORKSPACE_NAME- The name of the workspace the run is executing in.
• SCALR_WORKSPACE_ID - The ID of the workspace the run is executing in.
• SCALR_ENVIRONMENT_ID- The ID of the environment the run is executing in.
• SCALR_ENVIRONMENT_NAME- The name of the environment the run is executing in.
• SCALR_RUN_CONTENT_ROOT - The absolute path to the root of the configuration being executed.
• SCALR_IAC_PLATFORM - Indicates if Terraform or OpenTofu is being used to execute the run.
• SCALR_AGENT_ENV - If using self-hosted agents, the path to the file containing custom environment variables, which can be injected into the Scalr Run by hook scripts during execution. Learn more.

Setting Shell & Terraform Variables

Both Terraform and shell variables can be set at multiple scopes. Broader scopes are inherited by narrower ones, and a variable defined at a narrower scope overrides the same key from a broader scope unless the broader variable is marked final. Scopes from broadest to narrowest:

• Account: applies to every workspace in the account.
• Environment: applies to every workspace in the environment. Inherits from the account.
• Variable sets: account-scoped, named groups of variables that are linked to specific workspaces. Override account and environment values, but lose to the workspace itself.
• Workspace: applies only to that workspace. Overrides all broader scopes.
• Run: set on an individual run. Overrides everything else, but is not reused on subsequent runs.

Variables marked as final at any scope cannot be overridden at a narrower scope. Variables marked as sensitive have their value masked in the Scalr UI, API, provider results, and Terraform/OpenTofu plan and state output.

Variable Sets

📘

API only

Variable sets are currently managed through the Scalr API. UI support is not yet available.

A variable set is a named, account-scoped group of Terraform or shell variables. Sets are linked to workspaces explicitly, and the variables in a linked set are injected into every run on that workspace alongside the workspace's own variables.

Use a variable set when the same group of variables needs to apply to many workspaces without being redefined at each scope.

How a set reaches a workspace

A variable set lives at the account. Before it can be linked to a workspace, it must be made accessible to that workspace's environment in one of two ways:

• Per-environment: link the set to specific environments via the set's environments relationship.
• Shared: set is-shared to true to make the set available in every environment in the account. A shared set cannot also have explicit environment links.

Once access is granted, the set is linked to individual workspaces via POST /workspaces/{id}/relationships/var-sets. The workspace link is what injects variables into runs. Removing the workspace link stops the set from contributing variables on subsequent runs; runs that have already completed are unaffected.

Variables in a set

Each entry in a set has the same shape as a workspace or environment variable:

• key: variable name. Immutable after creation.
• value: variable value. Encrypted at rest when sensitive is true.
• category: terraform or shell. Immutable after creation.
• hcl: treat the value as HCL. Terraform category only.
• sensitive: mask the value in the API and run output. Once true, it cannot be reverted to false, and the value can no longer be read back through the API.
• final: marks the variable as final, with the same semantics as classic final variables.
• description: optional.

A variable's parent set is specified through the var-set relationship at creation.

Precedence

A workspace-scoped variable with the same key as one in a linked set takes precedence over the set. A run-time variable overrides everything below it.

When two variable sets linked to the same workspace define the same key and category, the set whose name is alphabetically first wins. Resolution is deterministic across runs, and renaming a set changes the winner. The uniqueness key is key + category: a terraform variable and a shell variable with the same name in different sets do not conflict and both apply.

API reference

• Variable sets: create, list, update, and delete sets and manage environment links.
• Variable set variables: create, list, update, and delete variables inside a set.
• Workspace variable sets: link a set to a workspace, list sets applied to a workspace.

Import Terraform & OpenTofu Variables

Terraform or OpenTofu variables files that end in .tfvars can be imported into a workspace via the import options on the variables page. This is most commonly used if the variables file is not in the same location as the code and not uploaded as part of the working directory.

Scalr will parse the code and automatically sets the sensitive or HCL flags on the variables where needed. By default, Scalr does not update values for variables that already exist in a workspace, but you can select the update option to do so:

Validation

If validation is built into the Terraform or OpenTofu code, Scalr will validate the variable when it is being created or updated. For example, if there is an OS type variable that can either be "Windows" or "Linux", the variable would be the following:

variable "os_type" {
  description = "Operating System to use for the VM"
  type = string

  validation {
    condition     = contains(["Windows", "Linux"], var.os_type)
    error_message = "The os_type must be either 'Windows' or 'Linux'."
  }
}

If a user tries to enter anything other than the values in the condition in the UI, Scalr will provide the defined error message.

All validation will still be checked during the plan and apply as well. This is intended to improve the user experience and catch any validation errors earlier on.

Sensitive Variables

By default, sensitive variables are masked in the UI, logs, and all outputs. If an environment admin needs to disable the masking of sensitive variables to help with troubleshooting, they can do so in the environment settings. This will only disable the masking of the outputs in the Terraform/Tofu logs.

Examples

Example: Account scope

Account scope variables are created at the account scope and automatically shared with all environments and workspaces.

Click on the variable to access the configuration details. Make sure to “Save” after any changes to variables.

Example: Environment scope

Environment scope variables are created and assigned within the environments tab at the account scope. Once they are created and assigned to the environment, all workspaces in the environment will inherit the variable:

Variables can be overridden by creating a new variable of the same name at a lower scope. An overridden variable is shown as a group with the lowest scope, and therefore applicable value is visible. The variable can be ungrouped using the button on the right so that the variable can be edited or deleted.

Example: Workspace scope

Workspace scope variables are assigned within the variables tab at the workspace scope.