nstung463/kimi-agent-skills/terraform-deploy-traps
Claude Code and agent skill by nstung463/kimi-agent-skills
- community
- ext:[{"type":"hook","description":"Pre/post lifecycle hooks"}]
Checking that the SKILL.md file is still in the repository.
Terraform 部署实战踩坑指南,提供对常见运维陷阱(如 provisioner 时序竞争、SSH 连接冲突、DNS 记录重复、卷权限问题、数据库初始化遗漏、Caddyfile 硬编码域名等)的根因分析及可直接复制的修复方案。当用户编写 null_resource provisioner、搭建多环境配置、排查 terraform apply 后容器持续重启或不健康、使用 cloud-init 初始化实例,或遇到 terraform plan/apply 报错、provisioner 执行失败、基础设施漂移、TLS 证书错误以及 Caddy/网关配置问题时,此技能将被激活。
Install
npx vskill@latest install nstung463/kimi-agent-skills/terraform-deploy-trapsSemi-extensibleMentions customization, but needs skill-specific knowledge. Read the extensible skills standard
SKILL.md
The same SKILL.md was published earlier as serejaris/kimi-skills/terraform-deploy-traps.
Terraform 运维陷阱
这些故障模式全部来自真实部署事故。每一条都曾导致过线上问题。组织方式:具体报错 → 根因分析 → 可直接复制的修复方案。
Provisioner 陷阱(报错 → 修复)
remote-exec 中报 docker: not found
cloud-init 还在安装 Docker,provisioner 就已经 SSH 进去执行命令了。
local-exec 中 rsync: connection unexpectedly closed
Terraform 会保持自己的 SSH 连接不释放;local-exec 的 rsync 再开第二个连接就会被拒绝。永远不要用 local-exec 往远程传文件。改用 tarball + file provisioner:
macOS 的 BSD tar:--exclude 必须写在源路径参数之前。
cloud-init status 一直显示 "running"
apt-get -y 并不会抑制 debconf 的交互对话框。像 iptables-persistent 这类包会在 TTY 提示上阻塞。
已知会阻塞的包:iptables-persistent、postfix、mysql-server、wireshark-common。
容器日志报 EACCES: permission denied,容器持续重启
宿主机挂载目录归 root 所有,但容器以非 root 用户(uid 1001)运行。在 docker compose up 之前修复:
查找 UID:在 Dockerfile 中搜索 adduser.*-u 或 USER 指令。
Provisioner 失败但看不到任何诊断输出
set -e 在第一个错误时就退出,导致后面的 docker logs 输出被隐藏。改用 set -u(不加 -e),在最后放一个统一的验证关卡:
容器 Restarting — 数据库表不存在
DB 迁移没有写在 provisioner 里。PostgreSQL 的 docker-entrypoint-initdb.d 只在数据目录为空时执行。需要显式创建数据库并运行迁移:
docker compose build 忽略环境变量覆盖
Compose 从 .env 文件读取 build args,而不是从 shell 环境变量。VAR=x docker compose build 不生效。
TLS 握手失败:Invalid format for Authorization header
Caddy DNS-01 ACME 需要 Cloudflare 的 API Token(cfut_ 前缀,40+ 字符,Bearer 认证)。使用 Global API Key(37 个十六进制字符,X-Auth-Key 认证)会导致 HTTP 400 Code:6003。生产环境可能因为有缓存证书而看起来正常;全新环境在首次申请证书时就会失败。
通过 API 创建范围受限的 token:
TLS 在预发环境失败但生产正常 — 域名硬编码
Caddyfile 或 compose 中写了固定域名。预发环境的 Caddy 加载了生产配置,尝试为不属于自己的域名申请证书 → ACME 失败。
Caddyfile:使用 {$VAR} — Caddy 在启动时解析环境变量。
Compose:使用 ${VAR:?required} — 变量未设置时立即报错。
将环境变量传入网关容器,让 Caddy 能读取到:
OAuth 登录失败:Social sign in failed
Casdoor 的 init_data.json 中包含硬编码的回调地址。--createDatabase=true 仅在首次创建数据库时应用 init_data,重启后不再执行。通过 provisioner 中的 SQL 修复:
还要检查 AUTH_CASDOOR_ISSUER — 它必须匹配 Casdoor 子域名(auth.staging.example.com),而不是应用的根域名。
多环境隔离
在创建第二个环境之前,先 grep .tf 文件中的硬编码名称。完整检查矩阵见 references/multi-env-isolation.md。
apply 时会直接报错(全局唯一资源):
| 资源 | 唯一性范围 | 修复方式 | |
|---|---|---|---|
| SSH 密钥对 | 地域级别 | "${env}-deploy" | |
| SLS 日志项目 | 账号级别 | "${env}-logs" | |
| 云监控联系人 | 账号级别 | "${env}-ops" |
DNS 重复陷阱:两个环境在同一个 Cloudflare zone 中为相同域名创建 A 记录 → 产生两个独立的记录 ID → DNS 轮询 → 约 50% 流量打到错误实例。修复:使用子域名隔离(staging.example.com)或单独的 zone。记得为 Caddy 服务的所有子域名创建 DNS 记录(如 auth.staging、minio.staging)。
快照交叉污染:未加过滤条件的 data "alicloud_ecs_snapshots" 会返回账号下所有快照。新环境继承旧的 100GB 快照,创建 40GB 磁盘时失败。用变量控制:
不要给 data source 加 count — 会改变其 state 地址,导致漂移。
部署前验证
在 terraform apply 之前运行验证脚本,在本地就捕获配置错误,避免"部署→发现→修复→重新部署"的循环。
关键检查项(详见 references/pre-deploy-validation.md):
terraform validate— 语法检查- Caddyfile 和 compose 文件中无硬编码域名
- 必需的环境变量已设置(
LOBEHUB_DOMAIN、CLAUDE4DEV_DOMAIN、CLOUDFLARE_API_TOKEN、APP_URL等) - Cloudflare API Token 格式正确(不是 Global API Key)
- 所有 Caddy 服务的域名都有 DNS 记录
- Casdoor issuer URL 匹配
auth.*子域名 - SSH 私钥文件存在
集成到 Makefile:在 make apply 之前运行 make pre-deploy ENV=staging。
从零部署
全新磁盘会暴露所有隐式依赖。详见 references/zero-to-deploy-checklist.md。
全新实例上会导致 provisioner 失败的关键项:
- 目录:在 cloud-init 中
mkdir -p /data/{svc1,svc2}—fileprovisioner 在目标目录不存在时会失败 - 数据库:显式执行
CREATE DATABASE— PG 初始化脚本仅在数据目录为空时运行 - 迁移:通过
schema_migrations表追踪,幂等执行 - Provisioner 执行顺序:共享 Docker 网络的资源之间需要
depends_on - 内存:小实例(≤8GB)在 Docker 构建时先停掉非关键容器
- 域名参数化:Caddyfile/compose 中的每个域名必须用
{$VAR}/${VAR:?required} - 凭据格式:Caddy 需要 API Token(
cfut_),不是 Global API Key
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/terraform-deploy-traps/SKILL.md
Popularity
- Repository stars
- 4
- Repository forks
- 1
- 7-day trend score
- 13
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Extension points
hookPre/post lifecycle hooks
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/nstung463/kimi-agent-skills/terraform-deploy-traps)