资源栈常见问题排查指南

本文档帮助用户排查在控制台使用资源栈（Formation）时遇到的常见问题。

受支持的 Terraform Provider 白名单

以下是当前资源栈支持的 Terraform Provider 列表：

注意：使用未在白名单中的 Provider 会导致资源栈创建/更新失败。如需支持新的 Provider，可以提交工单申请。

更多信息请参考七牛 Provider 官方文档。

日志及产物的目录结构

<artifactsStorageBucket> 是资源栈创建时指定的产物存储路径，格式为 kodo://<bucket-name>/<目录>/。如果创建资源栈时未指定，系统会自动生成并创建对应的 Kodo 空间：

• 自动生成格式：kodo://rfs-<8位随机字符>-<regionID>-artifacts/
  • <8位随机字符>：由数字和小写字母（0-9a-z）随机生成
  • <regionID>：RFS 服务所在的区域 ID（如 cn-east-1）
  • 示例：kodo://rfs-a3b7f9k2-cn-east-1-artifacts/
• 空间复用：同一用户在同一区域的所有资源栈共享同一个自动创建的空间，不会重复创建
• 空间区域：默认在 LAS 所在区域创建，如果该区域没有 Kodo 服务，会自动选择就近区域

资源栈的执行日志和产物按以下目录结构组织：

<artifactsStorageBucket>/
└── r-<revision>/                              # 每个 revision 对应一次执行操作
    ├── logs/
    │   ├── terraform-log-<uuid>.log           # Terraform 内部执行日志
    │   └── rfsjob-log-<uuid>.log              # RFSJob 执行过程日志
    ├── apply_results/                         # 执行 apply 操作时的产物
    │   ├── artifacts/
    │   │   └── log.json                       # Terraform 结构化日志
    │   └── content/                           # Terraform 实际执行的模块代码
    └── plan_results/                          # 执行 plan 操作时的产物
        ├── artifacts/
        │   └── log.json                       # Terraform 结构化日志
        └── content/                           # Terraform 实际执行的模块代码

说明

• apply_results/ 和 plan_results/ 分别对应 apply（创建/更新/删除）和 plan（计划）操作的产物，目录内部结构相同。
• revision 是资源栈的版本号，每次执行操作（无论成败）都会生成一个新的 revision 目录用于存储日志；操作成功后，资源栈版本号才会递增。

日志文件说明

常见问题

1. 创建/更新/删除资源栈失败

问题现象：资源栈状态变为 CreateFailed（创建失败）、UpdateFailed（更新失败）或 DeleteFailed（删除失败）。

可能原因：

• Terraform 模板语法错误
• Git 仓库拉取失败（地址错误、权限不足、网络不可达等）
• 使用了不受支持的 Terraform Provider（参见白名单）
• 输入变量（Variables）的值不符合类型或约束要求
• 云资源 API 调用失败（资源不足、余额不足、参数非法等）

排查步骤：

1. 在资源栈详情页，鼠标移动到状态说明，获取初步错误信息
2. 进入 <artifactsStorageBucket>/r-<revision>/ 目录（revision 编号可在资源栈详情页的版本信息中查看），按优先级查看日志：

   提示：可在资源栈详情页点击当前版本右侧的图标，直接跳转到对象存储的对应目录。

   • 查看 <操作>_results/artifacts/log.json——包含结构化的错误信息和上下文，能定位大部分问题
   • 查看 logs/rfsjob-log-<uuid>.log——排查 Git Clone 失败、执行流程中断等问题
   • 查看 logs/terraform-log-<uuid>.log——排查 Terraform 引擎层面的异常

解决方案：

1. 修正配置后重新更新：根据错误信息修正 Terraform 配置，执行"更新"操作重新部署

   提示：若界面弹出 强制重试资源栈 提示，说明当前错误不可直接重试，必须先修正配置后再操作。
   

2. 重试操作：系统会使用相同配置重新执行 terraform apply，适用于偶发错误（网络异常、Git 仓库临时不可用等）

注意：以上排查步骤适用于所有资源栈失败类问题（包括下文中的问题 2、3、4），均可通过查看对应 revision 目录下的日志来定位原因。

2. 更新资源栈失败，提示资源在平台外被修改

问题现象：更新资源栈失败，日志中提示检测到资源在平台外发生变更。

可能原因：

• 资源栈管理的云资源被通过控制台或 API 直接修改（如手动调整了虚拟机配置）
• 资源栈记录的状态与云资源的实际状态不一致

解决方案：

1. 更新时有一个是否同步资源状态的选项，选择同步重新更新——系统会先同步资源的最新状态，再执行更新操作
   
2. 建议：通过资源栈统一管理资源变更，避免直接修改资源栈管理的云资源

3. 更新资源栈后部分资源被替换

问题现象：更新资源栈后，某些资源被删除并重新创建（Replace），而非原地更新（Update）。

可能原因：

• 某些资源属性的变更不支持原地更新（in-place update），Terraform 只能通过先创建新资源再删除旧资源（Replace）来完成变更

解决方案：

1. 更新前先预览变更——创建一个 Update 类型的资源栈计划（StackPlan），查看 resourceChanges 中 action 为 Replace 的资源，确认无误后再应用
   

2. 注意：Replace 操作会先创建新资源再删除旧资源，可能导致短暂的服务中断。对于有状态的资源（如数据库实例、云盘等），旧资源删除后其存储的数据将永久丢失且无法恢复，请务必在操作前完成数据备份

3. 如果不希望资源被替换，请调整 Terraform 配置，避免修改会触发替换的属性（具体哪些属性会触发替换，请参考对应 Provider 的文档说明）

4. 应用资源栈计划时提示"需要执行 Refresh"

问题现象：应用资源栈计划时提示 StackNeedRefresh，查看计划详情时，资源偏移（Resource Drift）列表不为空。

StackNeedRefresh 提示：

资源偏移（Resource Drift）列表示例：

可能原因：

• 计划创建后到应用期间，资源在平台外发生了变更
• 系统检测到了资源偏移（Resource Drift）

资源偏移表示系统检测到某些资源在资源栈之外被修改。偏移类型包括：

偏移类型	说明
Update	资源的属性在平台外被更新
Delete	资源在平台外被删除

解决方案：

1. 查看偏移列表，确认哪些资源发生了变更
2. 若变更是预期的，在是否同步资源状态的选项中，选择同步后应用计划
   
3. 若变更非预期，先排查是否有人手动修改了云资源
4. 也可以删除当前计划，重新创建新计划（新计划会基于最新状态生成）
5. 建议：通过资源栈统一管理资源变更，避免在平台外直接操作资源栈管理的资源