When a run is executed in a Scalr workspace the result is the deployment of resources and then the storage of the Terraform or OpenTofu state in Scalr. Scalr will store not only the current state but all previous state files as well with the ability to download them.

The permission state-versions:read must be granted for a user to read state.

State Storage

The state is stored in a Scalr-managed bucket in Google Compute Cloud in the US Central region. All state is stored with AES 256 encryption and only the Scalr application has the ability to decrypt the state.

Want to store the state in your own GCP bucket? This is possible on brand new Scalr accounts by updating the blob settings.This is not considered state backup as the state will still be stored fully encrypted, this should be used if your security or compliance team have a requirement that state must be stored in your own GCP bucket.

Rollback

The state rollback feature allows you to easily rollback to a previous state file in the event of an error or corrupt file. This will not update or change your resources unless a new Terraform run is executed and a change is detected. The rollback option can be found on the page of the old state file:

Update State

📘

If using OpenTofu, substitute the tofu command for terraform.

Push

State can be updated and manipulated easily in Scalr as Scalr can be added as a remote backend to local workspaces. Scalr supports all of the standard Terraform or OpenTofu open-source commands as long as the remote backend is added to your config.

First, get the API token for Scalr by running the following:

terraform login <account-name>.scalr.io

Next, make sure you have Scalr added as the backend for the local workspace:

terraform {
  backend "remote" {
    hostname = "<my-account>.scalr.io"
    organization = "<ID of environment>"
    workspaces {
      name = "<workspace-name>"
    }
  }
}

Next, you can pull the state with terraform state pull> terraform.tfstate

Now that you have the state locally, you can make updates to it and then push it back into Scalr with terraform state push terraform.tfstate

In some scenarios, you must ensure that the serial of the state is one number higher than the previous serial that was in the Scalr workspace. You will know you have an issue if you see the error:cannot overwrite existing state with serial 1 with a different state that has the same serial

This can be fixed by updating the serial in the actual state file before pushing:

{
  "version": 2,
  "terraform_version": "1.0.0",
  "serial": 2,
...

Import

Resources can also be imported into the existing Terraform state in Scalr by running the standard import command: terraform import resource.scalr <resource-id>. There is a caveat in that the credentials and secrets need to be stored locally to do this with the Terraform CLI.

If you do want to use the credentials and variables stored in Scalr, then a pre-plan hook can be used to execute the import command. The steps to do this are:

• prepare a script with the import commands:

terraform import <address-1> <resource-id-1>  
terraform import <address-2> <resource-id-2>  
terraform import <address-3> <resource-id-3>

• Add a pre-plan hook to execute the script
• Trigger a terraform plan
• After the plan is finished, delete the hook as this is a one time job.

State Backup/Export

For organizations that want to have a copy of the state stored locally, this can be done using the Terraform/OpenTofu CLI or Scalr API to export the state.

If using the Terraform CLI, you can simply run a terraform state pull> terraform.tfstate to pull it down locally.

If using the Scalr API, most users do this in two ways:

• Run a job to do a bulk export on a recurring schedule.
• Export the state using the post-apply custom hook after a successful apply.

In either case, this API can be called to get a state file based on the version ID or this API call can be called to pull the current state for a workspace.

We have also created a script that you can use to do the backup: https://github.com/Scalr/scalr-state-backup