deck-gateway

decK 网关工作流

目标

使用 decK 生成、检查和应用 Kong Gateway 实体配置，同时准确掌握实时状态、作用范围和部署模式。

当任务涉及 Gateway 实体和面向 Gateway 的 GitOps 时，请使用此技能。请勿将其用作 kongctl 或 Terraform 所负责的 Konnect 平台工作流的替代方案。

工具定位

• 当目标 Gateway 实体位于 Konnect 且 MCP 可用时，首先使用共享的 kong-konnect MCP 服务检查实时 Konnect 状态。
• 当仓库已经使用 decK、_format_version 或 deck gateway 命令，或者用户明确要求使用 decK 时，请使用此技能。
• 当实际任务是事件诊断、实时状态发现，或在确定由仓库管理的 decK 范围之前检查 Konnect 时，请先使用领域技能或 kongctl-query。
• 保留仓库中现有的 decK 布局、文件拆分方式、标签和 CI 模式。
• 除非用户明确要求迁移，否则不要将 Terraform 或 kongctl 仓库转换为 decK。
• 当用户需要 HCL 或 kongctl 而不是 decK 时，请转交给 terraform-kong-gateway、terraform-konnect 或 kongctl-declarative。

要加载的参考资料

仅加载与当前分支相符的参考文件：

• references/command-paths.md
  • 在选择 validate、diff、sync、dump 或文件生成路径时加载。
• references/openapi-generation.md
  • 当用户从 OpenAPI 文档开始，并希望由此生成 Gateway 实体时加载。
• references/state-shaping-and-tags.md
  • 当文件拆分、标签、包含边界或所有权结构比实体内容本身更重要时加载。
• references/dump-diff-sync-safety.md
  • 当主要问题是在变更前如何安全检查实时状态时加载。

验证约定

预检

在编辑文件或建议执行实时同步之前：

• 确认已安装且可运行 deck：deck version
• 确认目标部署模式和实时目标：
  • 通过 Admin API 管理的自托管 Gateway
  • 使用相应 Konnect 身份验证标志的 Konnect 管理控制平面
• 确认凭据已通过环境变量、配置文件或安全主机设置提供。切勿回显或提交密钥。
• 写入新文件前检查当前文件结构。
• 确认所有权边界：
  • 涉及哪个状态文件、目录、包含路径或包装脚本
  • 是否使用标签限定所有权范围
  • 命令将操作哪个环境或控制平面
• 选择 decK 路径前，确认任务属于声明式编写、预览、导出还是实时变更。

预览

• 验证正在编辑的确切文件、目录或包含路径。
• 运行范围最小的 diff，仅显示预期的实体范围。
• 仅在需要检查实时状态时使用限定范围的 dump。
• 在任何 sync 之前，检查文件范围、包含边界、标签范围和非预期删除。

执行

• 执行任何变更命令前，说明预期的实时影响。
• 只有用户明确要求变更时，才运行 deck gateway sync。
• 使 sync 与已预览的文件、目录、标签或包含边界保持一致。

验证结果

• 重新运行相同范围的 deck gateway diff，并确认没有剩余的预期变更。
• 当变更范围小于整个仓库时，验证被触及的确切实体范围。
• 不要仅凭 sync 成功就认定实时 Gateway 已符合预期。

运行规则

• 将 decK 视为 Gateway 实体的受版本控制表示，而不是实时 Gateway 当前与其一致的证明。
• 如果必需的 deck 命令受 Agent 环境限制，而非实时产品或 CLI 本身的限制，请请求在获得批准后取消沙箱限制并重试，再判断是否为身份验证或命令执行失败。
• 将 deck gateway validate 加上范围限定的 deck gateway diff 视为执行 sync 前必需的预览步骤。
• 如果仓库已有文件拆分方式和标签，请予以保留。
• 优先采用增量式或范围限定的更改；除非用户要求完整导出，否则不要广泛重新导出整个控制平面。
• 优先使用仓库自有的状态文件作为预期配置的来源。使用实时转储进行检查或恢复，而不要将其作为默认编写格式。
• 不要将 Konnect 平台资源放入 decK 文件。decK 用于 Gateway 实体，而非完整的 Konnect 产品范围。
• 如果用户从 API 规范出发，并希望据此生成 Gateway 实体，请使用 OpenAPI 驱动的生成方式。
• 不要假设 decK 适用于 DB-less 运行时加载、身份或团队管理，或非 Gateway 的 Konnect 资源。

工作流

1. 检查现有的 decK 结构

确认：

• 仓库是否已有一个或多个 decK 状态文件
• 配置是否按环境、工作区或服务拆分
• 是否使用标签来限定所有权范围
• CI 是否使用 deck gateway diff、deck gateway sync 或封装脚本

添加新文件或命令前，先遵循现有约定。

2. 确认目标 Gateway 范围

明确：

• 目标是自托管 Gateway，还是 Konnect 控制平面
• 涉及哪些 Gateway 实体：服务、路由、插件、使用者、使用者组、上游、目标、证书或与保管库相关的配置
• 任务是创建、更新、转储、验证、差异审查还是导入

不要将团队、门户或访问规则等平台资源视为 Gateway 实体。

3. 使用 decK 的原生安全机制进行预览

选择能够满足请求的最精简 decK 路径：

• 在审查差异前验证结构或文件格式
• 提议更改前，对自有范围进行差异比较
• 仅在检查或恢复需要时转储实时状态
• 仅在用户要求修改实时环境时执行同步
• 仅当源数据为规范时，使用 OpenAPI 生成路径

如果有多个 decK 路径都适用，且需要更明确的判断依据，请加载 references/command-paths.md。

4. 编写或更新状态文件

编辑状态时：

• 保留仓库现有的按文件或按领域拆分布局
• 尽可能保持实体名称和标签稳定
• 避免不必要的重排或格式变动
• 仅添加请求所需的实体

如果仓库的拆分方式、标签或包含范围是主要限制，请加载 references/state-shaping-and-tags.md。

5. 仅在用户要求时执行

• 在展示或运行变更命令前，说明预期对实时环境产生的影响。
• 仅当用户明确要求修改实时环境时，才使用 deck gateway sync。
• 命令范围应限定为已预览的文件、标签、select-tags 或包含边界。

如果用户需要更安全的先检查后执行流程，或即将使用范围较广的转储／同步流程，请加载 references/dump-diff-sync-safety.md。

6. 使用 decK 验证结果

执行用户要求的 sync 后：

• 重新运行相同范围的 deck gateway diff，并确认没有剩余的预期更改
• 如果任务范围小于整个仓库，请验证目标实体范围，而不要仅凭广泛同步的成功消息作判断
• 指出自有范围之外仍存在的任何差异，而不要隐瞒
• 不要仅凭 sync 的退出状态就认定实时 Gateway 已与预期状态一致

7. 报告确切影响

说明：

• 哪些文件发生了更改
• 哪些 Gateway 实体受到影响
• 结果仅为声明式编写、漂移审查，还是实时同步
• 下一步面向用户的验证步骤是什么

Kong 特定注意事项

• decK 最适合管理 Gateway 实体，而非范围更广的 Konnect 平台。
• Git 中的 decK 文件并不能证明实时控制平面与其一致。
• 如果文件范围或标签范围过于宽泛，大范围的 sync 运行可能会覆盖相邻实体的更改。
• Konnect 控制平面仍使用 decK 管理 Gateway 实体工作流，但周边平台资源可能需要使用其他工具。
• 如果用户确实需要 HCL 加 Terraform 状态，强行使用 decK 会带来不必要的转换。

验证清单

回答前，请确认你能说明：

• 为什么 decK 适合此代码库或请求
• 哪个由代码库管理的文件、包含边界或标签边界具有权威性
• 涉及哪些 Gateway 实体
• 哪些 deck 预览命令可以安全地证明预期更改
• 任务属于编写、差异比对、导出还是同步
• 命令应针对哪个环境
• 用户请求的是实时修改，还是仅需声明式更改
• 更改后的验证步骤将如何确认确切受影响的范围
• 是否应由其他工具技能负责实现

移交

• 如果代码库已通过 HCL 管理自托管 Gateway 配置，请使用 terraform-kong-gateway。
• 如果代码库已通过 HCL 管理由 Konnect 托管的 Gateway 实体或周边 Konnect 资源，请使用 terraform-konnect。
• 如果任务实际涉及的是 Konnect 平台 YAML，而非 Gateway 实体的 decK，请使用 kongctl-declarative。
• 如果用户首先需要检查实时状态，而非编写配置，请使用 kongctl-query 或相关领域技能。