# Move Terraform State to a Remote S3 Backend

Yes. An agent adds an S3 backend with versioning, encryption and locking to your Terraform root module, bootstraps the bucket and opens a PR with migration steps.

[Run this on Rush](https://cloud.getrush.ai/run/add-remote-state/terraform/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the configuration into its own cloud sandbox and reads every `.tf` file before it touches the backend. In a root module like hashicorp-education/learn-terraform-provision-eks-cluster, `terraform.tf` pins `required_version = "~> 1.3"`, requires the `aws` provider at `~> 5.47.0` together with `random`, `tls` and `cloudinit`, and carries a commented-out `cloud {}` block that was never finished. `main.tf` builds a VPC from `terraform-aws-modules/vpc/aws` 5.8.1 and an EKS cluster from `terraform-aws-modules/eks/aws` 20.8.5 with two managed node groups, `variables.tf` declares only `region` with a default of `us-east-2`, and `.gitignore` already excludes `*.tfstate`, `*.tfstate.*` and `*.tfvars`. There is no `backend` block anywhere, so state lives in a local `terraform.tfstate` on whoever ran `apply` last. The `.terraform.lock.hcl` is committed and pins `aws` to 5.47.0, so the agent leaves provider versions alone.

Remote state has a chicken-and-egg problem: the bucket must exist before `terraform init` can write to it. The agent adds a small `bootstrap/` root module beside the main one with its own provider block and a single `aws_s3_bucket` plus `aws_s3_bucket_versioning` set to `Enabled`, `aws_s3_bucket_server_side_encryption_configuration` with SSE-S3 or a KMS key when the prompt asks for one, `aws_s3_bucket_public_access_block` with all four flags true, and `prevent_destroy = true` in its lifecycle so a stray `destroy` cannot take the state with it. The bucket name comes from a variable so the same bootstrap serves several accounts. Locking is the second decision: S3's own lockfile needs a Terraform release newer than the `~> 1.3` floor in `terraform.tf`, so the agent either raises `required_version` and sets `use_lockfile = true`, or keeps the floor and adds an `aws_dynamodb_table` with a `LockID` hash key for the classic lock. It picks whichever the prompt names and says why in the pull request.

The main module then gets a `backend "s3"` block inside the existing `terraform {}` block in `terraform.tf`, next to `required_providers`, with `bucket`, `key`, `region` and `encrypt = true`. Because a backend block cannot read variables, the agent writes a `backend.hcl` example with the bucket and table names and documents `terraform init -backend-config=backend.hcl` in the README, so a fork of the repository does not inherit someone else's bucket. The dead `cloud {}` comment goes, since two backends cannot coexist and leaving it invites a future conflict. `outputs.tf` in the bootstrap module exports the bucket and table names so the values in `backend.hcl` can be copied rather than retyped.

Proof comes from Terraform itself. The agent runs `terraform fmt -check -recursive` and `terraform init -backend=false` followed by `terraform validate` in both the main and the bootstrap modules, so the new blocks are parsed and type-checked without any AWS credentials. It writes the migration sequence into the README as commands to run once: `terraform init` and `apply` in `bootstrap/`, then `terraform init -migrate-state -backend-config=backend.hcl` in the root, which copies the local state file into the bucket and asks for confirmation. If the Project holds AWS credentials as secrets, the prompt can ask the agent to run that sequence too; otherwise it stops at validation and says so.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Move this Terraform root module's state to a remote S3 backend. Read every .tf file, .terraform.lock.hcl, .gitignore and the README first, and keep provider versions as they are. Add a bootstrap/ root module that creates the state bucket (versioning enabled, server-side encryption, public access blocked, prevent_destroy) and a DynamoDB lock table with a LockID hash key, with the bucket name as a variable and both names as outputs. Add a backend \"s3\" block to the terraform {} block in terraform.tf with encrypt = true, remove the commented-out cloud block, and add a backend.hcl example plus README steps for terraform init -backend-config=backend.hcl and terraform init -migrate-state. Run terraform fmt -check -recursive, terraform init -backend=false and terraform validate in both modules. Do not run apply. Open a pull request that lists the files, the migration commands in order, and the validate output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch that adds `bootstrap/main.tf`, `bootstrap/variables.tf` and `bootstrap/outputs.tf`, edits `terraform.tf` to add the `backend "s3"` block and drop the commented `cloud {}` block, adds `backend.hcl` with placeholder bucket and table names, and extends the README with the one-time bootstrap and migration steps. `main.tf`, `variables.tf`, `outputs.tf` and `.terraform.lock.hcl` are untouched, because a backend change moves where state is stored and changes no resource.

The description quotes the `terraform validate` result for both modules, names the locking method and why it was chosen against the `required_version` floor, and lists the commands a maintainer runs in order. The transcript at `GET /o/{org}/sessions/{id}/messages` keeps every `terraform` command and its output, so a reviewer can see that `fmt` found nothing to change and that `init -backend=false` succeeded rather than take the pull request's word for it.

Before merging, a reviewer checks that the bucket's public access block is complete, that `encrypt = true` is set on the backend, that the `key` is unique to this root module so a second module in the same bucket cannot overwrite it, and that the README tells people to keep `terraform.tfstate.backup` until the first remote `plan` shows no changes. A follow-up on the same session can add `workspace_key_prefix` for per-environment workspaces or switch the lock from DynamoDB to the S3 lockfile once the team's Terraform is new enough.

## Run it on every new Terraform root module

A platform team that owns several root modules with local state runs this once per repository. From a script, send the body above to `POST /o/{org}/sessions` with each repository in `resources`, one run per repository, and a `request_id` that is a UUID v5 of the repository name so a retry is safe. Give the key a `webhook_url`, and every run the key starts posts `run.completed` with `data.session_url` when its turn ends; a handler reads the pull request link from the session and posts it where the team triages.

To stop local state from creeping back, add an automation to the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and a prompt that fails the review when a new root module appears without a `backend` block. The trigger clones the pull request's branch and places the event after the prompt, and the automation starts at most `max_runs_per_hour` runs in an hour.

## Why run it on Rush?

Moving state is a small diff with a large blast radius: a wrong `key` or a missing public access block is a problem that shows up months later. The agent reads the actual `required_version`, the provider pins and the `.gitignore` before it decides between a lockfile and a lock table, and it validates both modules in its own sandbox with a Terraform binary already installed, so the pull request arrives checked rather than typed.

Each `terraform fmt`, `init` and `validate` and its output stay in the run's transcript, so the review is of a log rather than a promise, and the laptop that handed off the task is free while it happens. Several root modules can get the same backend at once, each in its own sandbox and its own pull request, with the same bucket layout in every one.

## Frequently asked questions

### Will the agent migrate my existing state file?

Only if the Project gives it AWS credentials as secrets and the prompt asks for it. By default it adds the backend, validates both modules without credentials and writes the `terraform init -migrate-state` steps into the README for a maintainer to run once. Migration copies the local state into the bucket and asks for confirmation before it does.

### DynamoDB lock table or S3 lockfile?

Both prevent two people from applying at once. The S3 lockfile needs a Terraform release newer than the `~> 1.3` floor in this module's `terraform.tf`, so the agent uses it only when the prompt allows raising `required_version`; otherwise it adds a DynamoDB table with a `LockID` hash key, which works on every version the module already accepts.

### Will this change any of my AWS resources?

No. A backend block changes where Terraform stores state, not what it manages, so the first `terraform plan` after migration should show no changes. The bootstrap module creates only the bucket and the lock table, in its own state, and marks the bucket `prevent_destroy` so it cannot be removed by accident.

### Can several environments share one bucket?

Yes. Each root module gets its own `key`, and workspaces are separated by `workspace_key_prefix`. The agent sets a key specific to this module and leaves a note in the README on how a second module or a staging workspace picks a different one, so two configurations never write to the same object.

### Why not finish the commented-out Terraform Cloud block instead?

Because the prompt asks for S3 and a configuration can declare only one backend. The agent removes the dead comment so nobody later uncomments it next to the S3 block. If you would rather use HCP Terraform, a follow-up message on the same session can swap the backend for the `cloud` block and drop the bootstrap module.

## More Terraform jobs

- [Add Renovate to a Terraform Module Repository](https://getrush.ai/run/add-renovate/terraform/)
- [Add Consistent Resource Tags to a Terraform Configuration](https://getrush.ai/run/add-resource-tags/terraform/)
- [Generate Terraform Module Docs With terraform-docs and Keep Them Current in CI](https://getrush.ai/run/add-terraform-docs/terraform/)

## More jobs like this: Hand off a long task

- [Make a Maven Build Reproducible](https://getrush.ai/run/add-reproducible-builds/maven/)
- [Add Request ID Logging to an Actix Web App](https://getrush.ai/run/add-request-id-logging/actix/)
- [Add Request ID Logging to an AdonisJS App](https://getrush.ai/run/add-request-id-logging/adonisjs/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
