Terraform allows you to properly plan and deploy your code through the use of terraform plan, allowing you to see exactly what will take place before you trigger a full terraform apply. The same concept also works in reverse when you want to perform a terraform destroy. You can view a full plan of what resources will be deleted before it is triggered, allowing you to have that extra level of protection. 

However, proper measures and peer reviews still need to take place prior to triggering a terraform apply and terraform destroy. Over time, Terraform state files can become messy and difficult to manage as more resources are deployed. The terraform state list command helps efficiently navigate, filter, and identify specific resources, making it easier to troubleshoot, plan, and maintain your infrastructure.

Overview of Terraform state command

Terraform excels at managing infrastructure at scale by handling the full lifecycle of resources: creating new ones, updating existing ones, and tearing down those that are no longer needed. It achieves this by maintaining a state file that records the current status of the infrastructure, enabling Terraform to determine the necessary changes to reach the desired state. State management is crucial; without it, Terraform cannot function as intended. 

The state is stored in a JSON-formatted file named terraform.tfstate, which can be kept locally or remotely in cloud storage services like Azure Blob Storage, AWS S3, or Google Cloud Storage. Remote state storage allows team members to share the state file, ensuring consistency across deployments. It also provides locking mechanisms to prevent simultaneous updates, avoiding conflicts and corruption.

The terraform state command is primarily used to manage the state file. This command offers numerous benefits, aiding in daily tasks and troubleshooting by allowing you to inspect, modify, and manipulate the state file.

With the state commands, you can list all resources and modules in the state file, saving you from having to scan it manually. Additionally, you can delve deeper into each listed resource and module. Several sub-commands enable manipulation of the state file's data, such as terraform state mv, rm, and replace-provider.

What is the terraform state list command?

The terraform state list is a Terraform command used to list all the resources that are currently being tracked in the Terraform state file, making it easier to maintain and troubleshoot your infrastructure. The resources are listed with their address, which typically includes the module path, resource type, and name. You can also filter the output by providing an address prefix to list only the resources that match that pattern.  

The terraform state list command is particularly useful when you want to:

• Identify the resources that are currently being managed by Terraform
• Troubleshoot issues related to specific resources
• Verify the state file matches your expected infrastructure

Syntax & option flags

The syntax of this command is as follows:

terraform state list [options] [address...]

• options: Optional flags that modify the behavior of the command.
• address: An optional argument that specifies a resource address to filter the listed resources.

The available options are:

• -state=path --  This option allows you to specify a different state file path if needed. 
• -module=name - This option lets you filter the list to show resources within a specific module. 
• -id=id  - This option filters the list by the resource ID, but it is ignored if not set.

What is the difference between the Terraform state list and show commands?

Both the terraform state list and terraform state show commands are used to interact with the Terraform state file. Whereas terraform state list gives you a high-level view of all the resources in the state file, terraform state show dives deep into the specifics of a single resource.  

The terraform state list command retrieves a simple list of all the modules and resources being tracked in your state file, which is very high-level. This command is useful for getting a quick inventory of the resources without diving into all the details. 

The terraform state show command does the exact opposite. It is used to show the attributes of a single resource or module in the Terraform state. The command outputs attributes and metadata associated with the resource or module, such as resource ID, properties, and any dependencies. This is similar to the details you would see in a terraform plan. 

Overall, these commands serve different purposes and give you different sets of information about your managed resources.

💡 You might also like:

• How to Deploy your Infrastructure in CI/CD using Terraform
• How to Automate Terraform Deployments
• Managing Terraform at Scale with GitHub Actions

How to use the terraform state list command?

Now, we will look at some examples of how to maximize the use of terraform state list command:

Example 1: List all resources

To list all resources, simply run:

terraform state list

You will receive an output like the one below (we are using AWS in this case). For a Terraform resource, you will get the resource type first and then the resource name after resource_type.resource_name. For modules, you have the module, the specific module name, the resource type, and the name of the specific resource within the module at the end.

 

aws_eks_cluster.eks_cluster
aws_eks_node_group.eks_node_group
aws_iam_role.eks_node_group_role
aws_iam_role.eks_role
aws_iam_role_policy_attachment.eks_cni_policy
aws_iam_role_policy_attachment.eks_ecr_policy
aws_iam_role_policy_attachment.eks_node_group_policy
aws_iam_role_policy_attachment.eks_policy
aws_internet_gateway.igw
aws_route_table.public
aws_route_table_association.public[0]
aws_route_table_association.public[1]
aws_security_group.eks_cluster_sg
aws_security_group.eks_node_sg
aws_subnet.private_eks_subnet[0]
aws_subnet.private_eks_subnet[1]
aws_subnet.public_eks_subnet[0]
aws_subnet.public_eks_subnet[1]
module.network.aws_subnet.public
module.network.aws_vpc.main

Example 2: List resources in a module

The terraform state list command also allows you to filter by module type to grab all the modules in your state file with a specific type:

terraform state list -module=compute

Returning the following output:

module.compute.aws_instance.web
module.compute.aws_instance.app
module.compute.aws_security_group.sg

You can also filter further if you are looking for a module with a specific resource type:

terraform state list module.compute.aws_instance

Returning the following output:

module.compute.aws_instance.web
module.compute.aws_instance.app

Example 3: Filter resources by names

In the following example, we use the terraform state list command to simply filter through the state by name:

terraform state list aws_instance

Output:

aws_instance.web
aws_instance.app
aws_instance.db

You can also filter modules by names and wildcards:

terraform state list 'module.compute.aws_instance*'

Giving you the following output:

module.compute.aws_instance.web
module.compute.aws_instance.app

Example 4: Filter resources by IDs

Filtering the state by IDs can help you pinpoint the exact resource while troubleshooting and debugging an issue with a specific resource. It can also help you when you plan to perform actions on a subset of resources, such as updating or removing them from the state. Filtering by ID can ensure you are targeting the correct resources. 

Filtering a resource with ID:

terraform state list -id=i-1fsdf3432gbcdef0

Returning the following output:

aws_instance.myresource1

Here, we are filtering the state by the resource ID of my AWS EBS Volume, which was created with the use of a module:

terraform state list -id=vol-03432532f1htkpq

Returning the following output:

module.compute.aws_ebs_volume.data_volume

You can also filter by multiple resource IDs:

terraform state list -id=i-1fsdf3432gbcdef0 -id=i-fg34234454vedcba0

Returning the following output:

aws_instance.myresource1
aws_instance.myresource2

Terraform state list command in a remote backend

Until now, we have been working directly with the state file stored on our local machine. However, in real-world scenarios, you will probably be working with a remote state backend. 

Remote state backend involves storing your state file in a remote location such as Azure Blob Storage container, AWS S3 Bucket, or Google Cloud Storage. Running the terraform state list command against the remote state works as it would when running against a local state.

Here are a few examples of how you would configure a remote state backend with some of the popular cloud providers:

Azure

Remote state configuration for Azure:

terraform {
  backend "azurerm" {
    resource_group_name   = "azure_rg"
    storage_account_name  = "terraform_backend"
    container_name        = "dev_tfstate"
    key                   = "terraform.tfstate"
  }
}

Let's run terraform state list command against this remote state backend.

terraform state list

#Output
azurerm_resource_group.azure_rg
azurerm_virtual_network.my_vnet
module.compute.azurerm_subnet.my_snet
module.compute.azurerm_network_security_group.my_nsg

AWS

Remote state configuration for AWS:

terraform {
  backend "s3" {
    bucket = "aws_terraform_state"
    key    = "remote/path/key"
    region = "us-east-2"
  }
}

Run the terraform state list command against the AWS remote state backend:

terraform state list

#Output
aws_instance.myawsinstance
aws_security_group.sgtest
module.compute.aws_subnet.test_snet
module.compute.aws_vpc.test_vpc

Google Cloud Provider

Remote backend block for Google Cloud:

terraform {
  backend "gcs" {
    bucket = "gcp_state_bucket"
    prefix = "terraform/state"
  }
}

If we run the terraform state list command against the GCP remote state backend:

terraform state list

#Output
google_compute_instance.my_instance
google_storage_bucket.gcp_state_bucket
module.compute.google_subnet.my_snet
module.compute.google_vpc.my_vpc

The sub-commands we covered earlier also apply when running against a remote state backend. 

Managing Terraform state with Spacelift

Terraform is really powerful, but to achieve an end-to-end secure Gitops approach, you need to use a product that can run your Terraform workflows. Spacelift takes managing Terraform to the next level by giving you access to a powerful CI/CD workflow and unlocking features such as:

• Policies (based on Open Policy Agent) - You can control how many approvals you need for runs, what kind of resources you can create, and what kind of parameters these resources can have, and you can also control the behavior when a pull request is open or merged.
• Multi-IaC workflows - Combine Terraform with Kubernetes, Ansible, and other infrastructure-as-code (IaC) tools such as OpenTofu, Pulumi, and CloudFormation,  create dependencies among them, and share outputs
• Build self-service infrastructure - You can use Blueprints to build self-service infrastructure; simply complete a form to provision infrastructure based on Terraform and other supported tools.
• Integrations with any third-party tools - You can integrate with your favorite third-party tools and even build policies for them. For example, see how to Integrate security tools in your workflows using Custom Inputs.

Spacelift enables you to create private workers inside your infrastructure, which helps you execute Spacelift-related workflows on your end. For more information on configuring private workers, refer to the documentation.

Spacelift can also optionally manage the Terraform state for you, offering a backend synchronized with the rest of the platform to maximize convenience and security. You can also import your state during stack creation, which is very useful for engineers who are migrating their old configurations and states to Spacelift.

Behind the scenes, Spacelift uses Amazon S3 and stores all the data in Ireland. It's super simple to have Spacelift manage the state for you, as this behavior is achieved by default without you needing to do anything. You can read more about how it actually works here.

It's protected against accidental or malicious access because Spacelift can map state access and changes to legitimate Spacelift runs, automatically blocking all unauthorized traffic.

For more information, refer to this blog post, which shows in detail Spacelift's remote state capabilities.

Key points

Terraform state files can become messy and hard to manage over time as you increasingly deploy resources to your environment with Terraform. The terraform state list commands can be very useful for advanced state management --- efficiently managing and navigating through your IaC state files.

Written by Faisal Hashem