Remote state data source in Terraform - Commands & Configuration

Introduction

When you manage infrastructure with Terraform, sometimes you need to use information from another Terraform project. The remote state data source lets you safely access that information stored in a shared place.

When you want to use outputs from one Terraform project in another without copying values manually.

When multiple teams manage different parts of infrastructure but need to share some settings.

When you want to keep your infrastructure code organized by splitting it into smaller projects.

When you want to avoid repeating the same resource definitions in different Terraform configurations.

When you want to build infrastructure that depends on resources created elsewhere.

Config File - main.tf

main.tf

terraform {
  required_version = ">= 1.0"
}

provider "aws" {
  region = "us-east-1"
}

# Access remote state from another Terraform project stored in an S3 bucket
data "terraform_remote_state" "network" {
  backend = "s3"
  config = {
    bucket = "example-terraform-state"
    key    = "network/terraform.tfstate"
    region = "us-east-1"
  }
}

resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"

  # Use subnet ID from remote state
  subnet_id = data.terraform_remote_state.network.outputs.subnet_id

  tags = {
    Name = "web-server"
  }
}

This file configures Terraform to use AWS in the us-east-1 region.

The terraform_remote_state data source reads the state file stored in an S3 bucket named example-terraform-state under the key network/terraform.tfstate.

The aws_instance resource creates a web server instance using an AMI and instance type. It uses the subnet_id output from the remote state to place the instance in the correct subnet.

Commands

This command initializes the Terraform working directory. It downloads the AWS provider and prepares to use the remote state data source.

Terminal

terraform init

Expected Output

Initializing the backend...



Initializing provider plugins...

- Finding latest version of hashicorp/aws...

- Installing hashicorp/aws v4.0.0...

- Installed hashicorp/aws v4.0.0 (signed by HashiCorp)



Terraform has been successfully initialized!



You may now begin working with Terraform. Try running "terraform plan" to see any changes that are required for your infrastructure.

This command shows what Terraform will do. It reads the remote state to get the subnet ID and plans to create the AWS instance in that subnet.

Terminal

terraform plan

Expected Output

Refreshing Terraform state in-memory prior to plan...



An execution plan has been generated and is shown below.

Resource actions are indicated with the following symbols:

  + create



Terraform will perform the following actions:



  # aws_instance.web will be created

  + resource "aws_instance" "web" {

      + ami                          = "ami-0c55b159cbfafe1f0"

      + instance_type                = "t2.micro"

      + subnet_id                    = "subnet-12345678"

      + tags                        = {

          + "Name" = "web-server"

        }

    }



Plan: 1 to add, 0 to change, 0 to destroy.



─────────────────────────────────────────────────────────────────────────────



Note: You didn't specify an "-out" parameter to save this plan, so Terraform

can't guarantee to take exactly these actions if you run "terraform apply" later.

This command applies the planned changes and creates the AWS instance using the subnet ID from the remote state.

Terminal

terraform apply -auto-approve

Expected Output

aws_instance.web: Creating...

aws_instance.web: Still creating... [10s elapsed]

aws_instance.web: Creation complete after 15s [id=i-0abcd1234efgh5678]



Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

→

-auto-approve - Automatically approve the apply step without asking for confirmation

This command shows the subnet ID output from the remote state data source, confirming the value used.

Terminal

terraform output subnet_id

Expected Output

subnet-12345678

Key Concept

If you remember nothing else from this pattern, remember: the remote state data source lets you safely reuse outputs from another Terraform project by reading its stored state.

Common Mistakes

Using a wrong or missing backend configuration for the remote state

Terraform cannot find or read the remote state file, causing errors or missing data.

Ensure the backend config in the data source matches exactly where the remote state is stored, including bucket name, key, and region.

Trying to access outputs that do not exist in the remote state

Terraform will fail with an error because the output key is not found.

Verify the remote state project exports the outputs you want to use, and use the exact output names.

Not running terraform init after adding the remote state data source

Terraform will not download necessary plugins or configure the backend, causing failures.

Always run terraform init after changing backend or data source configurations.

Summary

Configure the terraform_remote_state data source to read another project's state from a shared backend like S3.

Use outputs from the remote state to configure resources in your current Terraform project.

Run terraform init to prepare, terraform plan to preview changes, and terraform apply to create resources using remote state data.