Skip to content

Remote state

Now that we have created the environment definition file, we can bootstrap the environment.

Terraform state is a file that tracks the resources Terraform has created. By default, this file is stored locally. The bootstrap command creates the S3 bucket and DynamoDB table needed to store Terraform state remotely.

After these steps, you will have a foundation for all the other stacks you create inside this environment.

Step 1: Add and configure the remote-state package

repo-iac/environments/dev/
ok pkg add remote-state
cd remote-state

In package-config.yml, set S3Backend to false:

repo-iac/environments/dev/remote-state/package-config.yml
StackName: "remote-state"

S3Backend: false

Step 2: Install the package

repo-iac/environments/dev/remote-state/
ok pkg install

Step 3: Initialize and apply the remote-state stack

Initialize and apply the stack to create the S3 bucket and DynamoDB table:

SSH Key

If you haven't already added a SSH key to your GitHub account (or have gh(GitHub CLI) configured). See GitHub SSH key guide for more information. This is required for Terraform to be able to fetch the modules from the golden-path-iac repository.

repo-iac/environments/dev/remote-state/
terraform init
terraform apply

Step 4: Verify

Verify that the S3 bucket for storing remote Terraform state was created.

You are looking for a bucket with the following name:

ok-iac-config-${local.account_id}-${local.region}-${local.environment}

For example:

2021-09-01 10:00:00 ok-iac-config-12345678910-eu-west-1-my-team-dev

Run the following command:

aws s3 ls

The list should contain the name of the S3 bucket you just created.

Sign in to the AWS console and navigate to S3.

The list should contain the name of the S3 bucket you just created.

Step 5: Move your current local Terraform state to the S3 backend

You now have remote storage for all future stacks. However, this stack still uses a local state file (terraform.tfstate).

Transfer the local state to the S3 bucket by reconfiguring Terraform to use S3 as the backend.

Edit package-config.yml and set S3Backend to true:

repo-iac/environments/dev/remote-state/package-config.yml
StackName: "remote-state"

S3Backend: true

Reinstall the package:

repo-iac/environments/dev/remote-state/
ok pkg install

Initialize the new configuration:

repo-iac/environments/dev/remote-state/
terraform init -migrate-state -force-copy

Verify that everything is working by running terraform plan. There should not be any changes to apply at this point:

repo-iac/environments/dev/remote-state
terraform plan

Delete terraform.tfstate since it's now stored in S3. This ensures Terraform uses the remote state instead of creating a new local file.

repo-iac/environments/dev/remote_state
rm "terraform.tfstate" && \
rm "terraform.tfstate.backup"

Commit your files

At this stage it is a good idea to commit your files.

Next step

Set up DNS.