Accessing and Modifying Terraform State

Before starting to talk about access to states, it is necessary to explain what states or State are. What are States?

What's Terraform State?

Terraform State is a way for Terraform to manage the infrastructure, configurations and resources created in order to maintain a mapping of what already exists and control the update and creation of new resources.

A basic example is when we create an S3 Bucket, an EC2 instance or an SQS via Terraform. All these resources are mapped in the state and are managed by Terraform.

State locations

Local

By default Terraform allocates state locally in the terraform.tfsate file. Using the State locally can work well for a specific scenario where there is no need to share the State between teams.

Remote

Unlike Local, when we have teams sharing the same resources, using State remotely becomes essential. Terraform provides support so that State can be shared remotely. We won't go into detail on how to configure it, but it's possible to keep State in Amazon S3, Azure Blob Storage, Google Cloud Storage, Alibaba Cloud OSS, and other cloud services.

The State is represented by the terraform.tfsate file in JSON format, here is an example of a S3 Bucket mapped on State:

{
  "version": 4,
  "terraform_version": "0.12.3",
  "serial": 3,
  "lineage": "853d8b-4ee1-c1e4-e61e-e10",
  "outputs": {},
  "resources": [
  {
  "mode": "managed",
  "type": "aws_s3_bucket",
  "name": "s3_bucket_xpto",
  "provider": "provider.aws",
  "instances": [
  {
  "schema_version": 0,
  "attributes": {
  "acceleration_status": "",
  "acl": "private",
  "arn": "arn:aws:s3:::bucket.xpto",
  "bucket": "bucket.xpto",
  "bucket_domain_name": "bucket.xpto",
  "bucket_prefix": null,
  "bucket_regional_domain_name": "bucket.xpto",
  "cors_rule": [],
  "force_destroy": false,
  "grant": [],
  "hosted_zone_id": "Z3NHGSIKTF",
  "id": "bucket.xpto",
  "lifecycle_rule": [],
  "logging": [],
  "object_lock_configuration": [],
  "policy": null,
  "region": "us-east-1",
  "replication_configuration": [],
  "request_payer": "BucketOwner",
  "server_side_encryption_configuration": [],
  "tags": {
  "Environment": "development"
  },
  "versioning": [
  {
  "enabled": false,
  "mfa_delete": false
  }
  ],
  "website": [],
  "website_domain": null,
  "website_endpoint": null
  },
  "private": "Ud4JbhV=="
  }
  ]
  }
  ]
 }

Accessing and updating the State

Despite the State being allocated in a JSON file, it is not recommended to change it directly in the file. Terraform provides the use of the Terraform state commands executed via CLI so that small modifications can be made.

Through the CLI, we can execute commands in order to manipulate the State, as follows:

terraform state <subcommand> [options] [args]

Sub-commands:

list List the resources in the state

mv Move an item in state

pull Extract the current state and list the result on stdout

push Update a remote state from a local state file

rm Remove an instance from state

show Show state resources

1. Listing State resources

Command:

terraform state list

The above command makes it possible to list the resources being managed by State

Example:

$ terraform state list
 
 aws_s3_bucket.s3_bucket
 aws_sqs_queue.sqs-xpto

In the example above, we have as a result, an S3 and an SQS Bucket that were created via terraform and are being managed by State.

2. Viewing a resource and its attributes

Command:

terraform state show [options] RESOURCE_ADDRESS

The above command makes it possible to show in detail a specific resource and its attributes

Example:

$ terraform state show aws_sqs_queue.sqs-xpto
 
 # aws_sqs_queue.sqs-xpto:
 resource "aws_sqs_queue" "sqs-xpto" {
  arn = "arn:aws:sqs:sqs-xpto"
  content_based_deduplication = false
  delay_seconds = 90
  fifo_queue = false
  id = "https://sqs-xpto"
  kms_data_key_reuse_period_seconds = 300
  max_message_size = 262144
  message_retention_seconds = 345600
  name = "sqs-xpto"
  receive_wait_time_seconds = 10
  tags = {
  "Environment" = "staging"
  }
  visibility_timeout_seconds = 30
 }

3. Removing resources from the State

Command:

terraform state rm [options] RESOURCE_ADDRESS

The above command removes one or more items from the State. Unlike a terraform destroy command, which removes the State resource and remote objects created in the cloud.

Example:

$ terraform state rm aws_sqs_queue.sqs-xpto

Books to study and read

If you want to learn more about and reach a high level of knowledge, I strongly recommend reading the following book(s):

Terraform: Up & Running: Writing Infrastructure as Code is a book focused on how to use Terraform and its benefits. The author make comparisons with several other IaC (Infrastructure as code) tools such as Ansible and Cloudformation (IaC native to AWS) and especially how to create and provision different resources for multiple cloud services. Currently, Terraform is the most used tool in software projects for creating and managing resources in cloud services such as AWS, Azure, Google Cloud and many others. If you want to be a complete engineer or work in the Devops area, I strongly recommend learning about the topic.

AWS Cookbook is a practical guide containing 70 familiar recipes about AWS resources and how to solve different challenges. It's a well-written, easy-to-understand book covering key AWS services through practical examples. AWS or Amazon Web Services is the most widely used cloud service in the world today, if you want to understand more about the subject to be well positioned in the market, I strongly recommend the study.

Well that’s it, I hope you enjoyed it!