Introduction to Terraform state

When managing cloud infrastructure with Terraform, tracking which configuration blocks correspond to which real resources is essential for accurate change detection. Terraform state stores this mapping, enabling Terraform to generate correct execution plans and apply only the changes that are needed.

What is Terraform state

Terraform state is a metadata repository for your infrastructure configuration. Terraform saves the state of every resource it manages in a state file named terraform.tfstate by default, though you can also store the file remotely.

Each resource block in a Terraform configuration is identified in the state by its resource_name. Terraform uses this identity to map remote objects—such as cloud resources—to the resource instances declared in your configuration. When Terraform creates or modifies a remote object, it records that object's identity in the state file. Future configuration changes use this record to determine whether to update or delete the object.

The resource management flow works as follows:

• On the first terraform apply, Terraform creates the declared resources and generates a state file that references each resource by its block name.

• On subsequent runs, Terraform compares the configuration file, the state file, and the actual remote resource state, then generates an execution plan based on the differences.

• When the plan executes, Terraform updates each resource to match the configuration. If an in-place update is not possible due to remote API limitations, Terraform destroys and recreates the resource.

• After the plan completes, Terraform updates the state file to reflect the current infrastructure state.

• If a resource is removed from the configuration but still exists in the state file, Terraform destroys that resource.

Storing Terraform state

By default, Terraform saves state locally in the current working directory as a .tfstate file. This works well for single-developer projects with no additional configuration. When multiple developers run Terraform simultaneously, each with their own local state file, this approach causes problems.

Local state in a team environment has three limitations:

1. No shared access

   Every team member needs access to the same state file. Storing it on a shared resource—such as an ECS instance—adds management overhead and creates a single point of failure.

2. No state locking

   If two team members run Terraform simultaneously, they can trigger a race condition. Multiple Terraform processes writing to the same state file at once risks conflicts, data loss, and state file corruption.

3. Sensitive data exposure

   The state file stores data in plaintext. Sensitive values such as database credentials and SSH passwords are visible to anyone with access to the file.

Store the state file in a remote, central location when a team manages infrastructure together. When infrastructure changes, the remote state file updates automatically, keeping every team member in sync with the latest state.

Remote state storage resolves all three limitations:

1. Automatic updates

   After configuring a remote backend, Terraform automatically loads the state from the remote location on every plan or apply run, and pushes the updated state back after each apply. This eliminates manual state management errors.

2. State locking

   When a Terraform command runs, the remote backend locks the state file. This prevents corruption from concurrent terraform apply runs by multiple developers.

3. Secure storage

   OSS buckets support encryption in transit and at rest, and provide fine-grained access control so you can restrict who can read or modify the state file.

Configuring remote state storage

Alibaba Cloud supports remote state storage using Object Storage Service (OSS) buckets, with state file locking provided by Tablestore. Before configuring remote state storage, create an OSS bucket to store the state file and a Tablestore instance to handle locking.

1. Create dependent resources

   Add the alicloud_oss_bucket, alicloud_ots_instance, and alicloud_ots_table resources to a Terraform configuration file such as main.tf. Set the bucket name, Tablestore instance name, instance type, and table name as needed. Run terraform apply to create the resources.

2. Configure the remote state

   Add the backend configuration to a new file named backend.tf, then run terraform init. Terraform detects the existing local state file and prompts you to copy it to the OSS bucket—enter yes. After terraform init completes, your Terraform state is stored in the OSS bucket.

To simplify this setup, use the Terraform module provided by Alibaba Cloud.

The following is a snippet of a state file stored in 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 records metadata for each managed resource, including its type, name, and provider.

Best practices for Terraform state

1. Use remote state for team collaboration

   Use remote state to lock and version the state file when working in a team. Use OSS as the remote state storage backend and Tablestore for state locking. Restrict access to the state storage bucket to the build system and administrators with elevated privileges. Add *.tfstate to your .gitignore file to prevent local state files from being accidentally committed to version control systems such as GitHub or GitLab.

2. Avoid storing sensitive data in the state

   Many resources and data providers write sensitive values—such as credentials and passwords—to the state file in plaintext. Avoid storing sensitive information in resources that expose it through the state.

3. Encrypt the state

   Always encrypt the remote state file as an additional security layer. OSS supports three encryption methods: KMS, AES256, and SM4. Use a custom KMS key for an extra layer of protection.

4. Never modify the state file manually

   The state file maintains the mapping between your Terraform configuration and your Alibaba Cloud infrastructure. Manual edits can corrupt the state and cause serious infrastructure failures.