地形程序

运维部署 社区

技能解读

当前原文的自动摘译,尚未人工审校。

Terraform 分叉检测 — OpenTofu

如果.terraform-version或tofu.lock.hcl表示OpenTofu(HashiCorp BSL fork,2023+),请在下面的所有命令中用tofu替换terraform。对于本技能中涵盖的操作,标志语义是相同的。 OpenTofu 存储库的其他指标:CI 配置中引用的tofu二进制文件,而不是terraform``.tofu/目录或tofu.tf文件

预先计划验证

现代预计划套件(在存在配置时运行):

制定包含详细退出代码的计划

-detailed-exitcode 形式是迭代协调循环 (RALF) 的标准预言机:成功 = 0(无差异)。

申请

始终应用已保存的计划文件,切勿在应用过程中重新计划。在应用时重新计划可能会导致审查内容和执行内容之间出现偏差。

计划摘要格式

在提出审查计划时,总结如下:

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
运维部署
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Terraform Procedures — State, plan/apply, and OpenTofu compatibility

Knowledge reference for Terraform/OpenTofu operations used by infrastructure-change workflows. Covers the plan/apply lifecycle, state-management commands, refactoring patterns, and fork-compatibility notes. Designed to be loaded as background context when a workflow encounters Terraform configs.

## Terraform fork detection — OpenTofu

If `.terraform-version` or `tofu.lock.hcl` indicates [OpenTofu](https://opentofu.org) (HashiCorp BSL fork, 2023+), substitute `tofu` for `terraform` in all commands below. Flag semantics are identical for the operations covered in this skill.

Other indicators of an OpenTofu repo:
- `tofu` binary referenced in CI configs instead of `terraform`
- `.tofu/` directory or `tofu.tf` files

## Plan / apply lifecycle

### Pre-plan validation

```
terraform validate
terraform fmt -check -recursive
```

Modern pre-plan suite (run when configs are present):

```
tflint                              # if .tflint.hcl present
tfsec . --soft-fail                 # if tfsec.yml or .tfsec/ present
checkov -d . --soft-fail            # if .checkov.yml present
terraform-docs markdown table .     # regenerate docs if terraform-docs.yml present
```

### Plan with detailed exit codes

```
terraform plan -out=tfplan -detailed-exitcode
# Exit codes:
#   0 = no changes
#   1 = error
#   2 = changes proposed
```

The `-detailed-exitcode` form is the standard oracle for iterative reconciliation loops (RALF): success = `0` (no diff).

### Apply

```
terraform apply tfplan
```

Always apply a saved plan file, never re-plan during apply. Re-planning at apply time can introduce drift between what was reviewed and what is executed.

### Plan summary format

When presenting a plan for review, summarise as:

```
## Terraform Plan Summary
| Action  | Count | Resources |
|---------|-------|-----------|
| Add     | X     | [list]    |
| Change  | X     | [list]    |
| Destroy | X     | [list]    |

WARNING — DESTROY/REPLACE resources:
- [resource] — [reason]

Data loss risk: [yes/no]
Estimated cost impact: [if applicable]
```

## State operations — use with extreme caution

State surgery is the second-most-fragile area after `destroy`. Always back up state before any of these operations (`terraform state pull > backup.tfstate`).

```
terraform state list                                # enumerate resources
terraform state show <addr>                         # inspect a resource
terraform state mv <src> <dst>                      # rename / refactor
terraform state rm <addr>                           # remove from state (resource still exists in cloud)
terraform import <addr> <id>                        # adopt an existing cloud resource
terraform state pull > backup.tfstate               # snapshot state
terraform state push backup.tfstate                 # restore (DANGEROUS)
```

### Refactor without state surgery

For module refactoring, prefer `moved {}` blocks (TF v1.1+) and `removed {}` blocks (TF v1.7+) — they encode the rename inside `.tf` files instead of imperative state ops, which means:

- Changes are reviewable in PRs
- The refactor is reproducible across workspaces
- No risk of half-applied state on operator error

Example `moved` block:

```
moved {
  from = aws_instance.old_name
  to   = aws_instance.new_name
}
```

### Partial-apply anti-pattern

`-target=<resource>` for partial-apply is an anti-pattern except in emergencies. State drift between resources causes surprising future plans and breaks the invariant that the state file matches the configuration.

If `-target` becomes necessary (e.g., breaking a cyclic dependency during initial bootstrap), follow up immediately with a full plan/apply to reconcile.

## Workspaces

Terraform workspaces partition state within a single backend:

```
terraform workspace list
terraform workspace new <name>
terraform workspace select <name>
terraform workspace show
```

Workspaces are appropriate for per-environment state (dev/staging/prod) when the configuration is identical and only variable values differ. For divergent configurations, prefer separate root modules.

## Policy-as-code gate

If `.conftest/` (Conftest), `.opa/` (raw OPA Rego), `.tflint.hcl` (TFLint), or `tfsec.yml` (tfsec) / `.checkov.yml` (Checkov) configs are present, run them as a **pre-plan** gate. A plan that violates policy never advances to apply.

## Rollback

```
# Revert the .tf file changes and re-apply
terraform plan -out=tfplan-rollback
terraform apply tfplan-rollback
```

For state-only rollback (after a botched `state mv` or `state rm`):

```
terraform state push backup.tfstate
```

State rollback overwrites the backend state and should be coordinated with whoever holds the workspace lock.

## When this applies

| Phase | Apply this knowledge |
|---|---|
| Step 3 — Review current state | `terraform validate`, `fmt -check`, `plan -detailed-exitcode` |
| Step 3a-bis — State operations | `state list/show/mv/rm/import`, `moved {}` / `removed {}` blocks |
| Step 4 — Implement | `terraform fmt -recursive`, `terraform validate` |
| Step 5 — Plan review | `terraform plan -out=tfplan` and plan-summary format |
| Step 6 — Apply | `terraform apply tfplan` |
| Step 8 — Rollback | Revert `.tf` files and re-apply, or push backup state |

## Integration

- **Used by**: `/infra-change` (Steps 3, 4, 5, 6, 8 — Terraform plan/apply lifecycle)
- **Companion knowledge**: `@gitops-detection` (HCP Terraform / Terraform Cloud / Atlantis / Spacelift / env0 controllers that own the apply gate)
- **External references**: [Terraform docs](https://developer.hashicorp.com/terraform/docs), [OpenTofu docs](https://opentofu.org/docs/), [moved block](https://developer.hashicorp.com/terraform/language/modules/develop/refactoring), [removed block](https://developer.hashicorp.com/terraform/language/resources/syntax#removing-resources)

---
> Source: [alex-voloshin-dev/ai-assets](https://github.com/alex-voloshin-dev/ai-assets) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。