volcengine-iac

Volcengine IaC 技能

当用户选择 IaC 时，使用 Terraform 生成、规划和应用 Volcengine 基础设施。volcengine-deploy 仍负责应用打包、运行时发布、健康检查和基于 CLI 资源清单的部署。

编写新示例时，优先使用 Cloud Control 提供程序 volcengine/volcenginecc。从 assets/examples/ 下经过验证的示例开始，然后阅读对应的 references/volcenginecc-*.md 说明，了解验证结果和注意事项。受阻资源记录在 references/volcenginecc-blocked.md 中。assets/modules/ 下现有的可复用模块仍使用旧版 volcengine/volcengine 提供程序，直到每个组件都通过 volcenginecc 重新验证。

符合以下任一条件时，使用此技能：

• 用户要求使用 Terraform 或 IaC；
• 用户已有 Terraform 状态或工作区；
• 计划、差异或漂移检测很重要；
• 基础设施计划由团队长期管理，且用户选择了 IaC；
• 部署需要 VKE、托管数据库/缓存/存储、负载均衡器、域名/证书、IAM/KMS、日志、监控或 Serverless 触发器，且用户选择了 IaC。

不要仅仅因为部署周期较长、基于 VKE 或包含托管依赖项就使用此技能。适当时可以推荐 IaC，但让用户自行选择。用户要求使用 CLI、进行临时演示/快速验证、部署不需要计划/差异/销毁的纯 ECS 单虚拟机服务，或 Terraform/提供程序安装受阻且目标可以安全地使用 CLI 作为备用方案时，不要使用此技能。

此技能包含 assets/examples/ 下经过验证的 volcenginecc 示例、assets/modules/ 下旧版可复用模块，以及用于生成 tfvars、汇总计划、导出输出和检查漂移的包装脚本。只有在明确目标形态后才选择文件；对于小型 Terraform 修改，不要将大量目录内容加载到上下文中。

六个旧版模块（CLB/ALB、VKE、CR、数据库、缓存、对象存储）以外的资源，应先作为经过验证的 volcenginecc 示例添加，只有在反复使用证明接口稳定后才封装为模块。

---

0. 先决条件

必需的环境变量：VOLCENGINE_ACCESS_KEY、VOLCENGINE_SECRET_KEY、VOLCENGINE_REGION。

必需的工具：terraform >= 1.5、jq、git、python3（用于 gen_tfvars.py）。

可选：由 volcengine-prepare/volcengine-deploy 生成的 .volcengine/deploy-choice.json。如果不存在，请集中简短询问 Terraform 相关问题。

此技能默认将 Terraform 工作文件写入 .volcengine/terraform/。用户需要远程状态时，可以使用兼容 S3 的 TOS 后端；请参阅 references/backend-tos.md。对于用户接受相应权衡的小型一次性实验，可以使用本地状态。

如果由 volcengine-deploy 调用，请将输出返回到 .volcengine/iac-outputs.json，然后让部署流程继续执行镜像构建/推送、Cloud Assistant 命令、Kubernetes 清单、veFaaS 发布、迁移和健康检查。

---

1. 生成流程

路径 A — 由 .volcengine/deploy-choice.json 驱动

work_dir="${work_dir:-.volcengine/terraform}"
workload="${workload:-standard}"
mkdir -p "$work_dir"

python3 scripts/gen_tfvars.py \
  --input ".volcengine/deploy-choice.json" \
  --output "$work_dir/terraform.tfvars" \
  --workload "$workload"

gen_tfvars.py 根据以下内容推导：

• 从选择文件和环境中获取 project、region、AZ 对
• 根据所选模式和已知依赖项确定 enable_vke / enable_cr / enable_rds / enable_redis / enable_tos 标志
• 根据粗略的 --workload 等级确定规格（实例类型、节点数、RDS 规格、Redis 容量）

用户可以在应用之前覆盖任何值。

路径 B — 自然语言输入

如果不存在准备报告，请向用户集中询问一组问题，然后根据经过验证的示例或旧版模块创建 Terraform 工作目录，并生成匹配的变量值。必需的回答：

1. 项目名称（资源前缀）
2. 区域（例如 cn-beijing）
3. 是否需要 VKE？（是/否）
4. 是否需要有状态依赖项：MySQL？PostgreSQL？Redis？TOS 存储桶？
5. 工作负载等级：轻量 / 标准 / 高负载

写入的文件

gen_tfvars.py 只会写入 terraform.tfvars。Terraform 配置文件来自 assets/examples/ 下已验证示例的副本，或由 assets/modules/ 组装而成的小型根模块；请编辑这些文件以匹配所选堆栈，不要指望脚本生成它们。

文件	用途
main.tf / variables.tf	复制或组装的 Terraform 配置
terraform.tfvars	由 gen_tfvars.py 生成或手动编辑的具体值
backend.tf	仅在选择 TOS 远程状态时生成；否则省略

每个模块的完整变量架构见 references/modules.md。对于新的 volcenginecc 工作，请从 assets/examples/ 下已验证的示例开始，而不是使用这些旧版模块，除非用户明确需要旧版 Provider。

路径 C — volcenginecc 已验证示例

复制相关的已验证示例，然后运行相同的 init/validate/plan 流程：

cp -R "assets/examples/<example-name>" "$work_dir/<component>"
cd "$work_dir/<component>"
terraform init -backend=false -input=false
terraform validate
terraform plan -out=tfplan.binary -input=false

在 apply 之前，展示计划摘要并要求用户明确确认。更改输入或销毁资源之前，请先阅读匹配的参考文档；其中包含字段选择、验证说明、导入 ID 和 Provider 注意事项。

---

2. 部署堆栈映射

根据部署形态选择少量已验证示例。先使用示例；只有在反复使用证明接口稳定后，才将其封装为可复用模块。典型堆栈组合包括：

• ECS：volcenginecc-network、volcenginecc-ecs，以及可选的 TLS/CloudMonitor
• VKE：volcenginecc-network、volcenginecc-vke、volcenginecc-cr，以及 CLB 或 ALB
• veFaaS：volcenginecc-vefaas，以及可选的 APIG/TLS
• 有状态 Web 应用：运行时堆栈加上 RDS、Redis 和/或 TOS 示例
• 私有服务：运行时堆栈加上私有 NAT 或网络连接示例
• 域名入口：运行时堆栈加上 DNS 和负载均衡器证书示例

此映射仅供参考，并不保证存在预构建模块。将相关示例复制到 .volcengine/terraform/<component>，并保持组件边界清晰，以便 plan/destroy 输出易于阅读。

对于端到端的 VKE 私有 CR nginx 路径，请使用 assets/examples/volcengine-vke-cr-nginx/，并先阅读 references/volcengine-vke-cr-nginx.md。该示例用于处理实际运行中发现的 CR 凭证插件、core-dns、CR 令牌过期和镜像架构问题。

---

3. 目录

使用文件系统作为目录。选择部署形态后，仅列出 assets/examples/ 下相关的目录，然后阅读匹配的 references/volcenginecc-*.md 文件，了解验证说明、导入 ID 和 Provider 注意事项。不要一开始就将所有示例加载到上下文中。

常见示例系列：

• volcenginecc-network、VPC 扩展、NAT、VPN、DirectConnect、CEN、TransitRouter、PrivateLink、DNS、PrivateZone
• volcenginecc-ecs、ECS 扩展、启动模板版本、EBS 快照、Auto Scaling
• volcenginecc-vke、volcenginecc-cr、CLB/ALB 入口、APIG、veFaaS
• volcenginecc-rdsmysql、volcenginecc-rdspostgresql、volcenginecc-rdsmssql、Redis、Kafka 允许列表
• volcenginecc-tos、TOS 通知、TLS、CloudMonitor、IAM、FileNAS、EFS

旧版 volcengine 模块仍可在 assets/modules/ 下使用；使用前请阅读 references/modules.md。

旧版模块目前涵盖 network、vke、cr、rds-mysql、redis 和 tos。ECS 和 CLB/ALB 仍作为已验证示例提供，因为它们的工作负载形态差异太大，无法采用单一且稳定的模块接口。

4. 初始化与后端

cd "$work_dir"

# Map Volcengine creds to the Terraform s3 backend's required env variable names.
export AWS_ACCESS_KEY_ID="$VOLCENGINE_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="$VOLCENGINE_SECRET_KEY"
export AWS_EC2_METADATA_DISABLED=true

terraform init -input=false
tf_workspace="${tf_workspace:-default}"
terraform workspace select "$tf_workspace" || \
  terraform workspace new "$tf_workspace"

如果请求使用远程状态，请根据 references/backend-tos.md 生成 backend.tf。经验证的 TOS 后端结构要求设置 skip_requesting_account_id = true，且不得设置 force_path_style 或 use_path_style。

下载提供程序（首次约需 30–60 秒）需要访问 registry.terraform.io。在中国的网络环境中，这可能会被阻止或速度较慢。如果无法访问公共注册表，而用户仍希望使用 IaC，请使用文件系统镜像或内部镜像配置 Terraform 的 provider_installation。否则，请返回 volcengine-deploy 并询问是否改用 CLI 资源台账方案。

关于 TOS 存储桶前置条件（必须在 init 之前创建），请参阅 references/backend-tos.md。如果没有 TOS 存储桶，请省略 backend.tf，Terraform 将回退到本地状态。

---

5. 计划

terraform plan -out=tfplan.binary -input=false
terraform show -json tfplan.binary > tfplan.json
bash scripts/plan_summary.sh tfplan.json

plan_summary.sh 会按操作类型（CREATE / UPDATE / DELETE / REPLACE）汇总变更，并在末尾打印一行摘要。执行任何 apply 之前，请先向用户展示该摘要。

注意：

• 用户未要求的 DELETE——通常意味着存在状态漂移，或模块调用被误删
• 有状态资源上的 REPLACE——替换 RDS / Redis 会导致数据丢失；请中止并使用 terraform show tfplan.binary 检查差异

---

6. 应用

始终要求用户明确确认。 不要传入 -auto-approve。操作方式：

The plan above will create N resources, change M, destroy K. Approve apply? [yes/no]

用户确认后：

terraform apply tfplan.binary

创建 VKE 集群约需 10–15 分钟。创建 RDS 高可用实例约需 20 分钟。apply 开始时，请向用户提示耗时较长，避免用户以为操作卡住。

apply 成功后，自动运行 export_outputs.sh：

bash scripts/export_outputs.sh
echo "Resources ready. .volcengine/iac-outputs.json now contains downstream consumption keys."

---

7. 供下游使用的输出

export_outputs.sh 会将 terraform output -json 写入 .volcengine/iac-outputs.json，并将文件权限设为 0600。下游技能通常会使用 VPC / 子网 / 安全组 ID、VKE kubeconfig、CR 仓库数据、RDS / Redis 端点或 ID，以及 TOS 存储桶名称。部分键取决于启用的示例 / 模块；使用者必须为 jq 设置防御性默认值。

---

8. 销毁

# Show what will be destroyed first
terraform plan -destroy -out=destroy.binary
terraform show -json destroy.binary | bash scripts/plan_summary.sh

然后：

This will permanently delete N resources including RDS / Redis / TOS bucket data. Confirm? [yes/no]

用户确认后：

terraform destroy
# Note: provider does not accept -auto-approve=false; we rely on the agent-level prompt above.

硬性规则：未经第二次确认，绝不能销毁 prod 工作区中的资源。Agent 应明确再次询问：

Workspace = prod. Re-confirm destroy by typing 'destroy prod':

---

9. 漂移检测

bash scripts/check_drift.sh

返回值：

• 0 和 {"drift": false, ...}——无漂移
• 2 和 {"drift": true, "changed_resources": N, ...}——有 N 个资源在 Terraform 之外发生了变更
• 1 和 {"drift": "error", ...}——仅刷新计划出错

适用场景：

• 已知发生手动干预后（例如有人通过控制台调整了节点池大小）
• 定期作为 CI 任务运行（每周）
• 执行任何重要的 apply 之前，确认基线与状态一致

---

10. 导入现有资源

如果用户希望接管通过 volcengine-cli 或控制台创建的资源，请使用 terraform import。不同资源的导入 ID 各不相同；导入前请阅读对应的 references/volcenginecc-*.md 或 references/modules.md。导入后运行 terraform plan，并通过编辑配置而非状态文件来协调差异。

---

11. 安全规则

• 绝不读取 ~/.volcengine/config.json；其中可能包含明文 AK/SK。
• 绝不提交 terraform.tfstate* 或 .volcengine/iac-outputs.json。
• 绝不向 terraform apply 或 terraform destroy 传入 -auto-approve。
• 在共享环境中，每次 apply 前都运行 check_drift.sh。
• 包含 kubeconfig 或密钥的文件权限必须设为 0600。
• 在每个模块 / 示例中固定提供程序版本。

脚本会尽可能强制设置文件权限。apply 和 destroy 的确认关卡由 Agent 负责。

---

12. 故障排除

按完全一致的错误字符串查找原因；根据对应的原因采取措施后，再考虑无关层面的问题。

症状	原因	修复方法
terraform init：“Failed to query available provider packages”	出站访问 registry.terraform.io 被阻止	使用文件系统或内部镜像配置 provider_installation，然后重新运行 init；否则返回 volcengine-deploy，询问是否可以接受通过 CLI 配置资源清单
terraform init：针对 TOS 后端返回“InvalidAccessKeyId”	未导出 s3 后端环境变量	导出 AWS_ACCESS_KEY_ID="$VOLCENGINE_ACCESS_KEY"、AWS_SECRET_ACCESS_KEY="$VOLCENGINE_SECRET_KEY"、AWS_EC2_METADATA_DISABLED=true
terraform init：TOS 后端返回 InvalidPathAccess	使用路径样式访问，或工作区前缀不受支持	使用 references/backend-tos.md 中经过验证的模板：保留 skip_requesting_account_id = true，移除 force_path_style/use_path_style
VPC 的 apply 成功，但子网因 InvalidVpc.InvalidStatus 失败	VPC 尚未达到 Available 状态（一致性窗口）	添加 depends_on = [volcengine_vpc.main]（网络模块中已配置）
VKE 集群在 Creating 状态卡住超过 20 分钟	配额或可用区容量问题	运行 ve vke ListClusters --body '{"Filter":{"Ids":["..."]}}' | jq .Result.Items[0].Status 查看实际原因
redis 输出缺少端点	提供程序未导出端点	使用 ve redis DescribeDBInstanceDetail --InstanceId $(jq -r '.redis_instance_id.value' .volcengine/iac-outputs.json) 查询
未进行任何编辑，但 terraform plan 显示意外变更	配置漂移，或提供程序补丁版本升级后悄然更改默认值	运行 check_drift.sh，检查 tfplan.json，决定接受还是还原变更
两名工程师的 apply 操作发生冲突	TOS 后端没有类似 DynamoDB 的锁定机制	手动协调；参见 references/backend-tos.md
特定资源的 apply/导入出现漂移	该资源存在提供程序注意事项	编辑配置前，阅读相应的 references/volcenginecc-*.md 说明