Runs

A run is the result of executing a Terraform or OpenTofu deployment in a workspace. There are two types of runs, runs that include an apply and runs that exclude an apply, referred to as a dry run. All runs for a given workspace will be displayed in the runs tab. For VCS-driven runs, a commit hash is provided, which can be clicked on to help users understand what changes were made to the code prior to the deployment for the entire history of the workspace. CLI runs will be noted as CLI-driven with the username of the person who created the run. No matter what the entry point for a run is, they will follow this workflow:

Run Dashboards

The runs dashboard, which exists at the account, environment, and workspace scope, serves as a central dashboard for all runs across all workspaces. From this page, runs can be canceled in bulk or approved/discarded as needed. A use case for the bulk cancellation is to reprioritize runs (i.e. you have an emergency change going in that cannot wait on prior runs to finish).

Click through demo:

The permissions to view the runs page can be controlled through theruns-queue:read in the IAM roles.

Run Output

The output of a plan can be displayed in two different ways, the standard console output or through the smart plan output referred to as a visual plan.

The visual plan is useful when you have hundreds or thousands of resources and you need to quickly filter on the action that is occurring in the plan:

Dry Runs

Scalr will automatically kick off dry runs when a PR is opened against a branch that is linked to a Scalr workspace or if a user runs a Terraform or OpenTofu plan through the CLI. If it is a VCS-driven run, Scalr will report the checks back to your VCS provider.

The "main" check seen below is a cumulative check across all workspaces that are connected to this repo and the working directory (if applicable). This check can be used to create a branch policy to ensure only successful dry runs are merged. There will only be a successful green check if all runs are successful.

Github has a slight different output in that you can see an overall summary for the pull request as well as a per workspace report (see more on enabling this here):

📘

Note

VCS driven dry runs are optional and can be enabled or disabled in the workspace settings.

Run Mode

When queuing a new run from the UI, you will have the options below presented to you. All standard Terraform or OpenTofu commands are still available when executing from the CLI.

• Plan & Apply - The default option. Initiates a full cycle of the plan, apply, (cost and policy checks are executed only if are configured in the environment).
• Plan Only - Only execute a terraform plan, which includes the cost-estimate and policy checks.
• Refresh-only - A new configuration is not applied, Terraform only updates the state accordingly to the actual value in the 3rd party.
• Skip Refresh - The current state is not refreshed while planning the changes.
• Replace - A limited list of resources can be recreated. At least 1 resource is required to be selected.
• Target Resources - A list of resources that will be targeted during the plan and apply. All other resources will be ignored.

Ignore Draft Pull Requests

Draft pull requests are commonly used during the early development cycles to note when a pull request is in a draft state. Since draft pull requests are so early on in the development cycle, it's possible that you don't want a Scalr plan to execute when pull requests are opened. Scalr gives you the option to ignore draft pull requests by unchecking "Trigger runs for draft pull requests". As of right now, this will apply to any workspace that is linked to the VCS provider.

Bulk Runs

Need to kick off runs in multiple workspaces at the same time? Bulk actions allow you to multi-select workspaces at the account or environment scope to execute a run with any of the run modes seen above or a destroy.

Prioritize Runs

During active development phases, runs will build up in the queue. It's much easier to select the run you want to actually execute rather than having to go through and delete other runs one by one, which is what the force run feature does. By forcing a run, Scalr will automatically discard all previous pending runs to ensure the selected run executes as fast as possible. Just click on the lightning bolt to select the run to execute.

Target Resources

The target option gives users the ability to focus the Terraform run on a specific resource or set of resources:

After a target is checked, select one or more resources that the run will impact once executed.

OIDC connect

Overview

Scalr has built-in support for major cloud providers (AWS, Azure, Google) via Provider configurations. However, some custom providers (Cloudflare, Vault, etc.) don't have the OIDC-connected options via the provider configurations. To solve this issue, Scalr exports an environment variable, SCALR_OIDC_TOKEN, for each run phase (plan & apply) that can be used to connect to the custom provider.

Token payload

The OIDC token is signed by the Scalr JWT token and can be exchanged for a temporary token by the custom provider. The payload has the following structure:

{
  "aud": "<account-name>",
  "exp": 1700056966,
  "iat": 1700053066,
  "iss": "https://scalr.io",
  "jti": "0ddab61b-4ca3-4112-be31-7549c83f26b8",
  "nbf": 1700053066,
  "ref": "",
  "scalr_account_id": "acc-xxxxxxxx",
  "scalr_account_name": "<account-name>",
  "scalr_environment_id": "env-xxxxxxxx",
  "scalr_environment_name": "<environment-name>",
  "scalr_run_id": "run-xxxxxxx",
  "scalr_run_phase": "plan",
  "scalr_tags": "",
  "scalr_workspace_id": "ws-xxxxxxxxxxxxx",
  "scalr_workspace_name": "<workspace-name>",
  "sub": "account:<account-name>:environment:<environment-name>:workspace:<workspace-name>"
}

Issuer always equals to https://scalr.io.

Payload customization

To make the token generation more streamlined, Scalr adds default values for the following attributes:

• aud - by default, it is the account name. To override it, you can create the shell variable SCALR_OIDC_AUD at any level and it will be set for all workspaces within the scope it is created (workspace, environment, or account).
• exp - by default, it is set to the run operation timeout of the workspace. If the timeout is not set, then the system's default value is used (60 minutes). To override it, you can create the shell variable SCALR_OIDC_EXP at any level and it will be set for all workspaces within the scope it is created (workspace, environment, or account).

Built-In Variables

The following shell variables are built into the runtime environment for use as needed:

• 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_OIDC_TOKEN - The ID token that is exported for each run phase (plan & apply) that allows users to connect to third parties (e.g. Vault, Cloudflare, etc.) via the OIDC. More about OIDC connect read here

See the full documentation for variables here: Variables