CLI

📘

OpenTofu

The commands below reference terraform, insert tofu instead for openTofu.

Set Up

Note: This workspace type is unavailable if the Scalr remote backend is disabled .

Obtain a Scalr token from the UI in your profile settings or by running terraform login <account-name>.scalr.io. When executing the login command, Scalr will automatically create the credentials and store them in the credentials.tfrc.json locally.

Set the following options:

• For a CLI-based workspace, you simply have to choose the working directory if one is needed.
• Add Scalr as the remote backend. The environment ID or name can be used as the organization. If the environment name has a space in it, the ID must be used:

terraform {
  backend "remote" {
    hostname = "<account-name>.scalr.io"
    organization = "<scalr-environment-name>"

    workspaces {
      name = "<workspace-name>"
    }
  }
}

Working directory

Scalr supports specifying a working directory in CLI-driven workspaces. This feature allows users to run OpenTofu/Terraform commands from a specific subdirectory within their project, rather than the project root. It is particularly useful in the following scenarios:

• Monorepos: When multiple Terraform configurations exist in different subdirectories, you can target a specific one without affecting others.
• Modular Infrastructure: If your project contains reusable Terraform modules alongside root module configurations, you can set the working directory to execute only the relevant configuration.
• Multi-Environment Repositories: When managing multiple environments (e.g., dev/, staging/, prod/), setting a working directory ensures that only the intended environment is processed during a run.

Considerations

While the working directory feature improves flexibility, it also introduces some considerations:

Performance Overhead: Terraform/OpenTofu CLI uploads all files from the repository root, including cached modules and unrelated files, even when using a working directory. This can lead to excessive data being transferred to remote workspaces, potentially slowing down runs. To mitigate this, consider using .terraformignore to exclude unnecessary files.

Private Module Registry: To improve performance, consider publishing your modules to the Private Module Registry instead of relying on the local modules and working directory. This ensures that only the workspace-specific configuration is uploaded during CLI-driven runs, significantly reducing the amount of data transferred to the remote workspace.

To avoid these issues, it is recommended that workspace configurations be documented clearly and that all team members follow a consistent directory structure.

Provider Configurations

Before executing a run in a workspace, credentials must be added so that the code can authenticate to the Terraform provider during the run. This can be done through the Scalr provider configuration feature. Provider configurations give users a central place to manage their configurations and assign them for use within environments and workspaces.

Set Variables

Once the workspace is created and saved, variables might need to be added to the workspace if required. Find out more about setting shell and Terraform/Tofu variables here.

Extra Settings

Other optional settings can be applied to all workspace types which can be found in workspace settings.

Terraform Init

Once the setup is complete, run terraform init to connect to the workspace to the Scalr remote backend. From this point forward, the standard Terraform/Tofu commands will work as expected.

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

❗️

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 the 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.

Terraform Plan & Apply

After the workspace has been created in Scalr and initialized with the terraform init command, a terraform plan and/or a terraform apply can be executed to make changes to the resources.