CLI Workspace

In this tutorial, we will start with the basics, by preparing a Workspace in Scalr that can be used together with the native Terraform CLI.

Scalr is fully compatible with the native Terraform CLI and with just some minor changes to your configuration, you will be able to take advantage of all extra features Scalr has to offer, like Policies and Cost estimation.

Even if you have not previously used the Terraform CLI, this tutorial will show you how to get started.

When using CLI based workspaces in Scalr, your Terraform run instructions will be uploaded to Scalr using the Scalr API. Scalr will then launch a separate container where Terraform will execute your plan and stream the output back to your console.

Getting Started

For the Terraform CLI to be able to communicate with the Scalr API, an API Token needs to be created and you must have the Terraform CLI installed locally.

User or Service Account

Here we have a choice to make. API Tokens can be created under a “User Account” or a “Service Account”. It could be tempting to create an API Token under a regular “User Account”. If you do so, please keep in mind that if that user ever leaves the company and the User Account gets deleted, the API Token will also be deleted and anything that relies on it will stop working. As a general rule, we recommend that you only use such API Tokens for development or testing. For production, please use “Service Accounts” instead.

A Service Account is a special type of account that can only access Scalr through the Scalr API. Any attempts to access the Scalr web interface using a Service Account will be denied. A Service Account is used when you don’t want to tie Scalr access to a specific human user.

To create a Service Account, first switch to Account Scope (green).

../_images/switch_to_account2.png

Pick Service Account under IAM in the Scalr Menu.

../_images/service_accounts.png

Under Service Accounts, click on New Service Account, give it a name and click Create. In this example, we pick the name “tutorial”.

../_images/create_service_account.png

Click on the Cogwheel icon to configure API Tokens for the newly created Service Account.

../_images/service_account_cogwheel.png

Click on Generate API Token and make sure to copy the Token to a temporary location as you will need it later in the tutorial and it will not be shown again.

../_images/generate_api_token.png

Create Workspace

Time to create our Workspace. Go to Workspaces in the Scalr Menu and click on New Workspace.

../_images/workspaces_menu.png

Give your Workspace a name and click Create. You can pick the desired Terraform version under Advanced.

../_images/new_cli_workspace.png

The Workspace has now been created and we need to configure Terraform to use it. We can copy the base backend configuration by clicking on the expand panel icon and then on the copy icon in the top right corner.

../_images/expand_workspace_panel.png

Create a directory on the system where you are planning on using the Terraform CLI from, then place the Terraform configuration into a file called main.tf

~/tutorial# cat >> main.tf <<EOL
terraform {
  backend "remote" {
    hostname = "example.scalr.io"
    organization = "env-u3rf1s5rnu0lh18"

    workspaces {
      name = "tutorial"
    }
  }
}
EOL

Next step is to provide the API Token to Terraform CLI by running terraform login <scalr-domain>.

~/tutorial# terraform login example.scalr.io
Terraform will request an API token for example.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:
    /root/.terraform.d/credentials.tfrc.json

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

  Enter a value: yes


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

Open the following URL to access the tokens page for example.scalr.io:
    https://example.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:
    /root/.terraform.d/credentials.tfrc.json

Token for example.scalr.io:
  Enter a value:

If you picked to use a Service Account API Token in the previous step, paste it in now. When you paste the Token, nothing will be echoed back in the console for security reasons.

On the other hand, if you decided to go with the standard User Account API Token, you need to create one by opening your browser and point it to the URL provided in the output.

../_images/user_token.png

Copy the Token field from Scalr and paste it to your console.

../_images/user_token_result.png

Terraform CLI should now greet you with a success message to indicate that the API Token is valid.

Token for example.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 example.scalr.io.

Test Run

Before we do our first test run, we need to initialize Terraform by running terraform init. This step tells Terraform to read our configuration file and let it know where to find the Scalr Workspace.

~/tutorial# terraform init

Initializing the backend...

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

Initializing provider plugins...

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.

You are now fully setup and ready to build infrastructure with Terraform CLI and Scalr! Next step would be to add infrastructure configuration to the main.tf file as you would normally do with Terraform.

Scalr supports passing values to Terraform using Variables. Read more about Set Terraform Variables.

To learn more about using the Terraform CLI, please visit the Terraform website.