Migrating to Scalr

Terraform Cloud Migration Module

If you are currently using Terraform Cloud or Enterprise and planning to migrate to Scalr, the quickest way to do this is by using our TFC migration module here. The module will migrate the following objects:

  • Organizations - Will be migrated into Scalr environments.
  • Workspaces - Will be migrated into Scalr workspaces. Only VCS-based workspaces will be migrated. CLI-driven workspaces have to be migrated manually.
  • Workspace variables - Terraform and non-sensitive environment variables will be created as Terraform and shell variables in Scalr.
  • State files - The current workspace state file will be migrated.

See the full description and instructions in the module readme.

Migrating with the Terraform CLI

If you would prefer to migrate workspaces one by one, this can be done with the Terraform CLI:

First, pull down the state from Terraform Cloud:

terraform state pull > terraform.state

Next, get the API token from Scalr:

terraform login <account-name>.scalr.io

Update your Terraform code and add Scalr as the new cloud backend. You will need to add the hostname field:

terraform {
  cloud {
    hostname = "<account-name>.scalr.io"
    organization = "<environment-id>"

    workspaces {
      name = "<workspace-name>"

To initialize Scalr as the backend by running:

terraform init

Run the following to push the state into Scalr:

terraform state push terraform.state

Other Backends

Existing Terraform or OpenTofu based deployments with state files stored locally or in another remote backend such as Terraform Cloud/Enterprise, S3, Consul, etc, can easily be migrated into Scalr using the Terraform CLI.

Regardless of where the existing state is stored, the process is the same.

  1. Get an API token for Scalr
  2. Stop any runs or processes that might start runs.
  3. Add or amend the backend settings in the Terraform configuration.
  4. Run terraform init to migrate the state.
  5. Set input variables.



If migrating from another remote backend DO NOT copy the state file to your local directory. If you do this will cause an error as Terraform is expecting the old state to be remote.

API Token

Run terraform login <account-name>.scalr.io. Ensure you update to your actual account name:

terraform login <account-name>.scalr.io
Terraform will request an API token for <account-name>.scalr.io using your browser.

If login is successful, Terraform will store the token in plain text in
the following file for use by subsequent commands:

Do you want to proceed?
  Only 'yes' will be accepted to confirm.

 Enter a value: yes

This will redirect you to the Scalr UI to create the API token. Copy the token and paste it into the command prompt:


Terraform must now open a web browser to the tokens page for docs.scalr.io.

If a browser does not open this automatically, open the following URL to proceed:


Generate a token using your browser, and copy-paste it into this prompt.

Terraform will store the token in plain text in the following file
for use by subsequent commands:

Token for <account-name>.scalr.io:
  Enter a value:

Retrieved token for user [email protected]


Success! Terraform has obtained and saved an API token.

The new API token will be used for any future Terraform command that must make
authenticated requests to <account-name>.scalr.io.

Stop Runs

Stop all runs and existing pipelines to ensure data integrity. The existing state storage may not have state locking, so it is possible that the state could be corrupt if a run takes place during migration.

Set the Remote Backend

  1. Get the organization id from the environment info on the main environment dashboard:

  1. Add or amend the terraform block in the Terraform configuration to point to a Scalr workspace. The hostname will be <account>.scalr.io if using SaaS. The workspace name is also set at this point.
terraform {
  backend "remote" {
    hostname = "my-account.scalr.io"
    organization = "<organization-name of environment>"
    workspaces {
      name = "<workspace-name>"

Migrate the State

Run terraform init and the workspace will be created with the latest state file. When asked if you want to copy the existing state, type “yes”. The Terraform CLI will automatically migrate the state from the old remote backend to Scalr.

# terraform init

Initializing the backend...
Backend configuration changed!

Terraform has detected that the configuration specified for the backend
has changed. Terraform will now check for existing state in the backends.

Terraform detected that the backend type changed from "s3" to "remote".
Do you want to copy existing state to the new backend?
  Pre-existing state was found while migrating the previous "s3" backend to the
  newly configured "remote" backend. No existing state was found in the newly
  configured "remote" backend. Do you want to copy this state to the new "remote"
  backend? Enter "yes" to copy and "no" to start with an empty state.

  Enter a value: yes

Successfully configured the backend "remote"! Terraform will automatically
use this backend unless the backend configuration changes.

Initializing provider plugins...

The following providers do not have any version constraints in configuration,
so the latest version was installed.

To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.

* provider.aws: version = "~> 2.70"

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

The workspace has been created in Scalr and the state imported.



If migrating from another remote backend DO NOT copy the state file to your local directory. If you do this will cause an error as Terraform is expecting the old state to be remote. If you see an error like Scalr detected a terraform.tfstate file then delete terraform.tfstate and re-run terraform init.


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