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

🚧

Warning

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:
    /Users/name/.terraform.d/credentials.tfrc.json

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:
    https://<account-name>.scalr.io/app/settings/tokens?source=terraform-login


---------------------------------------------------------------------------------

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:
    /Users/name/.terraform.d/credentials.tfrc.json

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:
2606
  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.

🚧

Warning

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.

Video

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