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 contains information about the resources that Terraform has created. By default, this file is stored locally on the machine it is run from. The bootstrap command will create the necessary S3 bucket and DynamoDB table that will instead be used 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: Create a new configuration file

Create a new configuration file for remote state:

repo-iac/environments/dev/_config/remote-state.yml
StackName: "remote-state"
S3Backend: false

Step 2: Add and install the remote-state package

Run the following command in the repo-iac/environments/dev/ directory:

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

This will add the package you want to install to packages.yml. If you want to know more about how this works, read the reference documentation for packages.yml.

Then, run the following command to install the package:

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

Step 3: Initialize and apply the remote-state stack

Now you need to tell Terraform to initialize this stack and apply it, 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
cd 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

Verify in the AWS CLI

Run the following command:

aws s3 ls

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

Verify in the AWS console

Login 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 a place to store Terraform state for all your future stacks. However, the stack you're currently working on is already using a local state file (terraform.tfstate).

The next step is to transfer this local state file to the S3 bucket you just set up. This is done by reconfiguring Terraform to use the S3 bucket as the backend.

Navigate to the environments/dev/_config directory and edit remote-state.yml.

repo-iac/environments/dev/_config/remote-state.yml
StackName: "remote-state"
S3Backend: true

Navigate to the repo-iac/environments/dev directory, and reinstall the package.

repo-iac/environments/dev
ok pkg install

Initialize the new configuration:

repo-iac/environments/dev
cd 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

You can now delete terraform.tfstate since it's stored in the S3 bucket instead. This is done so that the next time Terraform is run, it's updating the correct file instead of adding 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.