Terraform State skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Terraform State"
  short_description: "Imports, moves and lock fixes with a backup first"
  default_prompt: "$terraform-state Import these existing AWS resources into Terraform without recreating them"

# Terraform state surgery

Imperative commands for cases the `import`, `moved` and `removed` blocks cannot cover.
Every command below that writes state needs a fresh backup and the user's explicit
confirmation of the exact command first.

## Backup and inspect

```bash
terraform state pull > backup-$(date +%Y%m%d%H%M%S).tfstate
jq '{version, terraform_version, serial, lineage, resources: (.resources | length)}' backup-*.tfstate
terraform state list
terraform state show 'aws_instance.web["primary"]'
```

`serial` increments on every write; `lineage` identifies the state's history. Terraform
refuses to push a state with a different lineage or a lower serial unless forced.

Quote addresses containing brackets in shells: `'module.app.aws_instance.web["a"]'`.

## Rename or move within one state

```bash
terraform state mv 'aws_instance.web' 'module.compute.aws_instance.web'
terraform state mv 'aws_instance.web[0]' 'aws_instance.web["primary"]'
```

Prefer a `moved` block: it is reviewed in plan and works for every caller of a module.
Use `state mv` only for one-off fixes in a root module you own outright.

## Move between two state files

The `removed` plus `import` approach in SKILL.md is safer. If you must move state directly:

```bash
terraform -chdir=platform state pull > platform.tfstate
terraform -chdir=network  state pull > network.tfstate
cp platform.tfstate platform.backup.tfstate; cp network.tfstate network.backup.tfstate

# -state/-state-out are legacy local-file flags: run this from an empty scratch
# directory with no backend block, so they operate on the pulled files only
mkdir -p surgery && cp platform.tfstate network.tfstate surgery/ && cd surgery
terraform state mv -state=platform.tfstate -state-out=network.tfstate \
  'aws_vpc.main' 'aws_vpc.main'
cd .. && cp surgery/platform.tfstate surgery/network.tfstate .

terraform -chdir=network  state push ../network.tfstate
terraform -chdir=platform state push ../platform.tfstate
```

Then update both configurations so the resource block exists only in `network`, and plan
both: each must show no changes. Push the destination first so a failure in between
leaves the resource tracked twice (recoverable) rather than nowhere.

## Forget a resource

```bash
terraform state rm 'aws_instance.legacy'
```

The resource keeps running and is no longer managed. If the resource block is still in
the code, the next plan creates a duplicate. Prefer a `removed` block.

## Stuck lock

Symptom: `Error acquiring the state lock` with a lock ID, who, and when.

1. Find out whether the holder is still running: CI job, a teammate's terminal. A lock
   from a running apply must not be broken.
2. If the holder is gone (killed job, crashed laptop), confirm with the user, then:

```bash
terraform force-unlock <LOCK_ID>
```

3. Run `terraform plan` immediately. An apply that died midway may have created resources
   that are not in state; import them rather than letting the next apply create duplicates.

With S3 `use_lockfile`, the lock is a `<key>.tflock` object next to the state. With the
legacy DynamoDB table, the lock is an item keyed by `<bucket>/<key>`. Deleting those by
hand is equivalent to force-unlock and needs the same confirmation.

## Bad apply or corrupted state

- Versioned bucket (S3, GCS): list object versions of the state key, download the last
  good version, inspect it with jq, then push it (with confirmation). Pushing an older
  serial requires `terraform state push -force`; understand that resources created after
  that version will be missing from state and must be imported.
- HCP Terraform: state versions are listed per workspace; roll back from there.
- No backup and no versioning: rebuild state by importing every resource with `import`
  blocks. Slow, but safe and reviewable.

## Backend migration

```bash
terraform state pull > pre-migration.tfstate
# edit the backend block (e.g. local -> s3, or change bucket/key)
terraform init -migrate-state
terraform state list | wc -l          # same count as before
terraform plan -detailed-exitcode     # expect exit 0
```

- `-migrate-state` copies state; it does not delete the old copy. Remove the old object
  only after the user confirms the new backend works and pipelines point to it.
- `-reconfigure` ignores existing state and starts fresh against the new backend config:
  never use it to "fix" a migration error, it can orphan state.
- Workspaces migrate together; check `terraform workspace list` before and after.

## Provider source changes

```bash
terraform state replace-provider registry.terraform.io/-/aws registry.terraform.io/hashicorp/aws
```

Needed after legacy 0.12 upgrades or when switching to a fork or another registry
(for example OpenTofu's registry; see the opentofu skill).

## Sensitive data

State stores resource attributes in plain text, including generated passwords and
private keys. Restrict read access to the backend as tightly as the secrets themselves,
enable encryption at rest, and delete local `.tfstate` copies made during surgery once
the work is verified (confirm before deleting backups).