home / skills / thebushidocollective / han / terraform-state
This skill helps manage Terraform state securely across local and remote backends, ensuring locking, encryption, and safe state operations.
npx playbooks add skill thebushidocollective/han --skill terraform-stateReview the files below or copy the command above to add this skill to your agents.
---
name: terraform-state
user-invocable: false
description: Use when managing Terraform state files, remote backends, and state locking for infrastructure coordination.
allowed-tools: []
---
# Terraform State
Managing Terraform state files and remote backends.
## State Basics
Terraform state tracks resource mappings and metadata.
### Local State
```bash
# Default location
terraform.tfstate
terraform.tfstate.backup
```
### Remote State
```hcl
terraform {
backend "s3" {
bucket = "my-terraform-state"
key = "prod/terraform.tfstate"
region = "us-east-1"
encrypt = true
dynamodb_table = "terraform-locks"
}
}
```
## State Commands
```bash
# List resources
terraform state list
# Show resource
terraform state show aws_instance.web
# Move resource
terraform state mv aws_instance.web aws_instance.app
# Remove resource
terraform state rm aws_instance.old
# Pull state
terraform state pull > terraform.tfstate
# Push state
terraform state push terraform.tfstate
# Replace provider
terraform state replace-provider hashicorp/aws registry.terraform.io/hashicorp/aws
```
## Remote Backends
### S3 Backend
```hcl
terraform {
backend "s3" {
bucket = "terraform-state-bucket"
key = "path/to/terraform.tfstate"
region = "us-east-1"
encrypt = true
dynamodb_table = "terraform-state-lock"
# Optional: state locking
kms_key_id = "arn:aws:kms:us-east-1:123456789:key/..."
}
}
```
### Terraform Cloud
```hcl
terraform {
cloud {
organization = "my-org"
workspaces {
name = "my-workspace"
}
}
}
```
### Azure Backend
```hcl
terraform {
backend "azurerm" {
resource_group_name = "terraform-rg"
storage_account_name = "tfstate"
container_name = "tfstate"
key = "prod.terraform.tfstate"
}
}
```
## State Locking
Prevents concurrent modifications:
```hcl
# S3 + DynamoDB locking
terraform {
backend "s3" {
bucket = "my-terraform-state"
key = "terraform.tfstate"
region = "us-east-1"
dynamodb_table = "terraform-locks"
}
}
```
## Import Resources
```bash
# Import existing resource
terraform import aws_instance.web i-1234567890abcdef0
# Import with module
terraform import module.vpc.aws_vpc.main vpc-12345678
```
## Workspaces
```bash
# List workspaces
terraform workspace list
# Create workspace
terraform workspace new staging
# Switch workspace
terraform workspace select production
# Delete workspace
terraform workspace delete staging
```
## Best Practices
### Enable State Locking
Always use state locking to prevent concurrent modifications.
### Encrypt State
```hcl
backend "s3" {
encrypt = true
kms_key_id = "arn:aws:kms:..."
}
```
### Separate State Files
Use different state files for different environments:
```
states/
├── prod/terraform.tfstate
├── staging/terraform.tfstate
└── dev/terraform.tfstate
```
### Backup State
```bash
# Backup before dangerous operations
cp terraform.tfstate terraform.tfstate.backup.$(date +%Y%m%d_%H%M%S)
```
### Never Edit State Manually
Always use `terraform state` commands.
This skill helps manage Terraform state files, configure remote backends, and enforce state locking for safe infrastructure coordination. It provides concrete commands, backend examples (S3, Azure, Terraform Cloud), and guidance for importing, moving, and backing up state. Use it to reduce risk when changing Terraform-managed resources across teams and environments.
The skill inspects Terraform state workflows and offers the correct CLI commands and backend configurations for common tasks: listing, showing, moving, removing, pulling, and pushing state. It includes backend examples for S3 (with DynamoDB locking), Azure rm, and Terraform Cloud, plus workspace and import patterns. It highlights state-locking and encryption options and recommends operational safeguards like backups and environment-separated state files.
How do I prevent two users from applying at the same time?
Use a backend that supports state locking (e.g., S3 + DynamoDB) or Terraform Cloud, which prevents concurrent state writes during apply operations.
Can I edit terraform.tfstate to fix a resource quickly?
No — avoid manual edits. Use terraform state commands (show, mv, rm, import) to make safe, trackable changes and always back up the state first.