Terraform state - Terraform - Alibaba Cloud Documentation Center

What is Terraform state

Terraform state is an essential element in the Terraform lifecycle. It acts as a metadata repository for your infrastructure configuration. Terraform saves the state of the resources it manages in a state file.

By default, the state is saved in a file named terraform.tfstate, but it can also be stored remotely. Remote storage is recommended for scenarios where a team collaborates to manage infrastructure.

Terraform uses the state to create execution plans and modify your infrastructure. Before any operation, Terraform performs a refresh to update the state with the actual state of the infrastructure. The main purpose of Terraform state is to store the mapping between infrastructure objects in a remote system, such as in the cloud, and the resource instances declared in the configuration file. When Terraform creates or modifies a remote object based on the configuration file, it records the identity of that remote object in the corresponding resource instance and saves it in the state file. Terraform can then update or delete that object based on future configuration changes.

Each infrastructure resource created in a resource block is identified in the Terraform state by its resource_name. The management flow for the resource is as follows:

When you apply a Terraform configuration for the first time using terraform apply, infrastructure resources are created, and a state file is automatically generated. This file references the names declared in the resource blocks.
If a resource is already identified in the Terraform state file, Terraform compares the configuration file with the state file and the actual state of the remote resource. Based on this comparison, an execution plan is generated.
When the plan is executed, the resource is updated to match the definition in the configuration file. If an in-place parameter update is not possible due to remote API limitations, the execution plan will destroy the resource and then recreate it. If the plan is to destroy a resource, Terraform initiates the destruction operation.
After the plan is successfully executed, the Terraform state file is updated to reflect the current infrastructure state.
If a resource is removed from the current Terraform configuration but still exists in the state file, Terraform destroys the resource that is no longer in the configuration.

Storing Terraform state

By default, Terraform saves the state locally in the current working directory in a file with the .tfstate extension. This setup requires no additional configuration and is suitable for projects with a single developer. However, when multiple developers run Terraform simultaneously, each with their own local state file, this configuration can cause problems.

Using a local state in a team collaboration scenario presents the following problems:

Lack of shared access
When you use Terraform to update your infrastructure, each team member needs to access the same state file. This requires storing the file in a shared location, such as on an ECS instance, which adds to the management overhead.
No state locking
If two team members run Terraform at the same time, they might encounter a race condition. Multiple Terraform processes could update the state file simultaneously, which risks conflicts, data loss, and state file corruption.
The local status file does not contain confidential information
Because information is stored in plaintext in the state file, sensitive data such as database credentials and SSH logon passwords are at risk of being exposed.

Therefore, when multiple developers in a team manage infrastructure with code, we recommend storing the state file in a remote, central location. This way, when the infrastructure changes, the remote state file is updated, ensuring everyone on the team is working with the latest infrastructure state.

Using remote state storage resolves the problems associated with local state:

Automatic updates
After you configure a remote backend, Terraform automatically loads the state file from the remote location every time you run the plan or apply command. In addition, it automatically stores the updated state file remotely after each apply, which eliminates the risk of manual error.
State locking support
When you execute a Terraform command, the remote state file can be locked. This prevents the state file from being corrupted if multiple developers run terraform apply at the same time.
Remote file storage is more secure than local storage for state files.
OSS buckets support encryption in transit and at rest. In addition, OSS buckets provide multiple methods to configure access permissions, so you can control access to the state file in a fine-grained manner.

Configuring remote state storage

Alibaba Cloud provides remote state storage capabilities based on OSS buckets and supports remote state file locking using Tablestore. Therefore, before you configure remote state storage, you must first create an OSS bucket to store the state file and a Tablestore instance for locking. The following section shows you how to remotely store the Terraform state in an OSS bucket:

Create dependent resources
First, add the alicloud_oss_bucket, alicloud_ots_instance, and alicloud_ots_table resources to a Terraform configuration file, such as main.tf. Configure the resources as needed by setting parameters such as the bucket name, Tablestore instance name, instance type, and table name. After the configuration is complete, run terraform apply to create the bucket and other resources.
Configure the remote state
Next, add the backend configuration code to a new Terraform configuration file named backend.tf, and then run terraform init to configure your Terraform remote state. At this point, Terraform detects that a local state file already exists and prompts you to copy it to the new OSS bucket. Enter yes. After terraform init runs successfully, your Terraform state is stored in the OSS bucket.

To configure remote storage more conveniently, you can use the Terraform Module provided by Alibaba Cloud.

The following is a snippet of a state file from an OSS bucket:

{
  "version": 4,
  "terraform_version": "1.7.1",
  "serial": 9,
  "lineage": "5827f172-fc29-c293-cce7-7932f3537499",
  "outputs": {},
  "resources": [
    {
      "mode": "managed",
      "type": "alicloud_oss_bucket",
      "name": "this",
      "provider": "provider[\"registry.terraform.io/hashicorp/alicloud\"]",
      "instances": [
        {
          "schema_version": 0,
          "attributes": {
            "access_monitor": [
              {
                "status": "Disabled"
              }
            ],
            "acl": "private",
            "bucket": "tf-oss-backend-for-demo",

The state file includes metadata for the created resources, such as the resource type, resource name, and provider name.

Best practices for Terraform state

We provide the following suggestions for optimizing and securing Terraform state files:

Use remote state in team collaboration scenarios
Use remote state in team collaboration scenarios to lock and version the state file. Alibaba Cloud customers should use OSS as the remote state storage backend and use Tablestore to lock the state file. Ensure that only the build system and administrators with high privileges can access the remote state storage bucket. To prevent accidentally committing a developer's local state file to a source code version control system, such as GitHub or GitLab, add the state file pattern (*.tfstate) to your .gitignore file.
Do not store sensitive data in the state
Many resources and data providers store sensitive data in plaintext in the state file, which poses a security risk. If possible, avoid storing sensitive information in the state file.
Encrypt the state
As an additional layer of defense, always encrypt the remote state file. Alibaba Cloud OSS supports three encryption methods: KMS, AES256, and SM4. You can provide an additional layer of protection for the state file using a custom KMS key.
Do not manually modify the Terraform state
The state file is critical for maintaining the mapping between the Terraform configuration and your Alibaba Cloud infrastructure resources. State file corruption can lead to major infrastructure problems. Therefore, do not attempt to manually modify the content of the Terraform state file.