Using the Remote Backend

How to configure your backend.tf with env0's Remote Backend

Local Login to env0 Remote Backend

Remote backends allow running your Terraform deployments both on env0 and locally with access to the remote state. To use the Remote Backend locally, you must log in for your requests will be authorized.
To login, ensure the following conditions are met:

  1. You have a login Token
  2. The current path is the directory of the Terraform stack
  3. The Terraform stack defines a properly configured env0 backend
terraform {
  cloud {
    hostname     = "backend.api.env0.com"
    organization = "<org-id>.<project-id>"
    workspaces {
      name = "my-first-remote-apply"
    }
  }
}

πŸ“˜

A note regarding the PROJECT_ID in the backend configuration

The PROJECT_ID is only required if the env0 environment does not exist in the env0 UI. For example, if this is the first time you are creating a new env0 environment with the env0 remote backend configuration, you need to specify the PROJECT_ID so that env0 will know where to put your new env0 environment. Otherwise, if you are simply updating the backend configuration for an existing env0 environment, you do not need to specify the PROJECT_ID.

Logging in is simple. All you have to do is:

  1. Run terraform login backend.api.env0.com
  2. Enter yes when prompted
  3. Insert your token

πŸ“˜

A note regarding Module Registry & Remote Backend

Technically, the two services are hosted on different api endpoints, so in order to use both the module registry and the remote backend with the same API key, you will have to also setup the token for api.env0.com Please see the section on Private Registry authorization for more details.

Generating a Token

To generate a token, you must create a Personal API Key.
After the API Key has been created, the token will be listed under the Using it locally for Remote Backend.
Alternatively, Admins can create an API Key with a specific role.

🚧

Avoid Creating One Token For Multiple Users

Terraform's workspace locking mechanism prevents state corruption by enforcing that two users cannot plan nor apply simultaneously and overwrite each other's state.

Issuing the same token to multiple users causes the locking mechanism to be ignored, as env0 will be unable to differentiate between different users when they use the same token.

Logout

In case you need to logout, you can browse to backend.api.env0.com/logout/{Token}