Workspaces¶

A workspace is the result of a Terraform deployment where all objects related to the deployment are stored and managed. This is where you can find state, update the Terraform version, manage variables, see run history and much more. Scalr can be integrated with your existing workflow whether it is a GitOps approach through a VCS provider or using the native Terraform CLI.

VCS Integrated Workspace¶

Scalr workspaces can be linked to Terraform configurations held in VCS repositories in order to automate pull request (PR) checks and deployments.

By linking a workspace to a specific branch of the repository a webhook is created in the VCS provider that will POST to Scalr for every PR or commit/merge that affects that branch. Scalr will then automatically perform a “dry run” (terraform plan) for every PR and a run (terraform apply) for every commit/merge.

There are two basic steps to get started with a workspace:

Create the workspace
Set the variables (if necessary)

Create Workspace¶

To enable a VCS based workspace, create a workspace linked to a specific repo and branch:

Workspaces can be updated with the following settings:

Branch
- The branch of the repository that the workspace should point to.
Configuration Version Root
- Set this field if the repository contains multiple Terraform configurations in sub-directories. Terraform will only run and change resources based on a change to a specific sub-directory.
- By default, runs are always triggered inside the configuration version root. To override that behavior - use trigger prefixes (see below).
Terraform Work Directory
- This is where Terraform actually runs.
- This directory must be a subdirectory of the top level of the repository or of the subdirectory if specified.
Triggers
- If there are multiple folders, other than just the working directory, that need to trigger a run based on a change.
- Trigger prefixes require working directory to be set. And that working directory is always a trigger prefix.

Set Terraform Variables¶

Terraform variables can be set in the Terraform code or within the Scalr UI. If the configuration contains variables that do not have assigned values, then these must be assigned values in then Scalr workspace via the UI. Scalr will automatically create the variables.

If the local workspace contains any *.auto.tfvars files these will provide default variable values that Terraform will automatically use.

If variables in the *.auto.tfvars files have the same names as variables specified in the workspace, the predefined workspace values will be used. For map variables the values in *.auto.tfvars are merged with values in the same named variable in the workspace.

Set Shell Variables¶

If the Terraform configuration utilizes shell variables (export var=value), e.g. for credentials and other provider parameters, these must be set in Scalr.

Shell variables can be set at all levels in Scalr and are inherited by lower levels. Use environment or account level for shell variables that are needed in multiple workspaces or environments. Use workspace level for shell variables that are specific to individual Terraform configurations.

It is also possible to use the Scalr provider to pull output from one workspace and post it as an environment or account shell variable to make it easily available to all other workspaces.

See Shell Variables for full details.

Dry Runs¶

Scalr will automatically kick off dry runs when a PR is opened against a branch that is linked to a Scalr workspace. Scalr will report the checks back into your VCS provider.

Runs¶

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.

Video¶

More of a visual learner? Check out this feature on YouTube .

CLI Driven Workspace¶

If you already have an existing workflow that utilizes the native Terraform CLI or you just want the flexibility to use it, you can continue to use the CLI as it is fully supported. Scalr will execute the runs in a container in the Scalr backend, but the logs and output will still be sent back to your console.

To utilize Scalr as a remote backed there are a few simple steps:

Obtain an API token from Scalr
Add a backed configuration to a Terraform configuration

API Token¶

In the environment create a token by clicking on your profile:
Add the token to the CLI Configuration file:

Windows : terraform.rc in %APPDATA% directory.

Unix/Linux/Mac : ~/.terraformrc

credentials "<account>.scalr.io" {
  token = "<user-token>"
}

Backend Terraform Configuration¶

To enable the backend configuration, you’ll need the Organization ID, which can be found on the main environment dashboard:
Next, add the terraform block to the Terraform configuration. The hostname is the URL of your account, enter the Organization ID, and enter the workspace name of your choice:

terraform {
  backend "remote" {
    hostname = "<account>.scalr.io"
    organization = "<id of the environment>"  // e.g. org-t4737mmm538mabc
    workspaces {
      name = "<workspace-name>"
    }
  }
}

Lastly, run terraform init, which will create the workspace. From this point forward, you can use the CLI as you normally would and commands will be executed remotely in Scalr.

If there is an existing state file in the local system or state had previously been stored in another remote backed, then the terraform init command will automatically migrate the state to Scalr. See Migrating to Scalr for more details.

Warning

Version Mismatch. If the workspace is pre-created manually in Scalr and the Terraform version of the workspace does not match the version of the CLI then then following error will be displayed:
Error reading local state: state snapshot was created by Terraform vx.x.x, which is newer than current vx.x.x;.
If you see this error, please ensure the Terraform version of the CLI matches the Terraform version of the workspace.