Migrating to Scalr

Existing Terraform 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 process 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

  1. In the environment create a token.

  2. Add the token to the CLI Configuration file.

  • Windows : terraform.rc in %APPDATA% directory.

  • Unix/Linux/Mac : ~/.terraformrc.

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

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 state could be corrupt if a run takes place during migration.

Set the Remote Backend

  1. Get the organization id from the environment switcher on the UI by hovering over, or from the dashboard.

  2. Add or amend the terraform block in the Terraform configuration to point to a Scalr workspace. The hostname will be the local installation if Scalr is self-hosted or “my-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 as shown in this screen shot.



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 and error like Scalr detected a terraform.tfstate file then delete terraform.tfstate and re-run terraform init.

Set Terraform Variables

If the Terraform configuration contains input 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 workspace’s values will be used. For map variables the values in *.auto.tfvars are merged with values in the same named variable in the workspace.


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