openchoreo-platform-engineer

OpenChoreo 平台工程师指南

通过控制平面 MCP 服务处理 OpenChoreo 平台级工作；对于集群原生事项，使用 kubectl 和 Helm。请保持此文件精简，通过 MCP 探索平台的实时形态，并仅在任务确有需要时阅读详细参考资料。

步骤 0 — 确认 MCP 连接

运行 list_namespaces。如果无法访问该工具，请告知用户需要按照 https://openchoreo.dev/docs/ai/mcp-servers/ 配置 openchoreo-cp MCP 服务，并停止依赖 MCP 的 OpenChoreo 操作。对于集群原生 CRD，仍可使用 kubectl 和 Helm。

步骤 1 — 加载概念参考资料

在编写或修改任何平台资源之前，请先阅读 ./references/concepts.md。其中涵盖 OpenChoreo 的资源层级、Cell 运行时模型、端点可见性、平面、OpenChoreo 期望的 API 版本，以及每项任务都应遵循的先探索工作流——Agent 会在每项任务中重复用到这些内容。对这些内容仅凭记忆并不可靠；该参考资料很短。

对于接手的每项任务，在开始处理之前，还要加载相应的参考资料：

• 编写或更新 ProjectType / ClusterProjectType（项目的单元基础设施模板——单元命名空间、配额、网络策略、基线 RBAC）→ ./references/project-types.md。
• 编写或更新 ComponentType / ClusterComponentType 或 Trait / ClusterTrait → ./references/component-types-and-traits.md。
• 编写或更新 ResourceType / ClusterResourceType（托管基础设施模板——数据库、队列、缓存）→ ./references/resource-types.md。
• 编写或更新 Workflow / ClusterWorkflow（CI 构建模板或通用自动化）→ ./references/workflows.md。
• 在模板 / 补丁 / 验证中编写 CEL 表达式 → ./references/cel.md。
• 授权（AuthzRole / ClusterAuthzRole 及绑定） → ./references/authz.md。
• 平面间的故障隔离、控制器 / 网关 / Agent 日志检查、网关 / 路由诊断 → ./references/troubleshooting.md。

对于这些参考资料未涵盖的平台工程主题——TLS / 外部 CA、容器镜像仓库、身份提供商配置、多集群连接、部署拓扑、可观测性适配器模块、API 网关模块、告警存储后端选择、IdP / 引导认证映射、Helm 升级——请查阅官方平台工程师指南：https://openchoreo.dev/docs/platform-engineer-guide/。这些主题以文档为准；请勿依赖记忆。

此技能可以做什么

此技能支持以下平台工程任务。

• ProjectType / ClusterProjectType 编写 — 项目的单元基础设施模板：parameters + environmentConfigs 架构、CEL validations、规定的单元命名空间条目 + 命名空间范围的策略（配额、NetworkPolicies、RBAC、镜像拉取密钥）→ project-types.md
• ComponentType / ClusterComponentType 编写 — 架构、基础工作负载类型、资源模板、补丁、验证规则、allowedWorkflows 门控 → component-types-and-traits.md、recipes/author-a-componenttype.md
• ResourceType / ClusterResourceType 编写 — 参数 + environmentConfigs 架构、带 CEL 的 K8s 清单模板、输出（value / secretKeyRef / configMapKeyRef）、includeWhen / readyWhen、retainPolicy → resource-types.md
• Trait / ClusterTrait 编写 — creates[] / patches[]、参数架构、环境配置覆盖 → component-types-and-traits.md、recipes/author-a-trait.md
• Workflow / ClusterWorkflow 编写 — Argo runTemplate 结构、allowedWorkflows 门控、用于密钥的 ExternalRefs → workflows.md；对于绑定到组件的构建，请参阅 recipes/author-a-ci-workflow.md；对于独立自动化，请参阅 recipes/author-a-generic-workflow.md
• 模板 / 补丁 / 验证中的 CEL 表达式 → cel.md
• 授权 — AuthzRole / ClusterAuthzRole 及绑定 → authz.md
• 环境 + DeploymentPipeline 生命周期 — 针对现有平面创建环境，定义线性 / 分支式晋级路径 → recipes/create-an-environment-and-promotion-path.md
• Project + Namespace 创建 — 为新租户命名空间配置项目、环境和流水线。除非用户明确要求新建命名空间，否则默认使用 default 命名空间 → recipes/bootstrap-a-namespace.md
• Pod 级诊断 — 开发者请求排查应用问题时，针对 ReleaseBinding 使用 get_resource_events、get_resource_logs → troubleshooting.md
• 集群原生相关事项 — Helm 安装 / 升级（控制平面 / 平面 / cluster-agent；升级顺序：先控制平面）、ClusterSecretStore / SecretStore、Argo ClusterWorkflowTemplate、Kubernetes Gateway API 资源、原始控制器 / Agent / 网关日志检查。
• 排查平台侧故障 — 跨平面故障隔离、平面健康检查、控制器 / 网关 / Agent 日志 → troubleshooting.md

此技能无法完成的工作

• 应用级工作——由 openchoreo-developer 负责。 编写 Component / Workload / ReleaseBinding，编辑 workload.yaml，通过 patch_component traits: [...] 将 PE 编写的 Traits 附加到 Component，管理 SecretReference 的 CRUD（create_secret_reference / update_secret_reference / delete_secret_reference——底层的 ClusterSecretStore 仍由 PE 负责），硬删除开发者侧资源（delete_component / delete_workload / delete_release_binding / delete_project / delete_component_release——但 delete_namespace 属于 PE 侧，不会通过 MCP 暴露），追踪运行时崩溃，部署或提升应用，调试开发者侧的问题。当任务跨越职责边界时，请将此技能与 openchoreo-developer 配合使用——许多“这个应用部署失败”的问题，实际上是缺少 ClusterTrait 或 DeploymentPipeline 配置错误。如果两个技能都可用，请立即同时使用。
• 从零开始安装 OpenChoreo——为全新的控制平面和首个 Plane 执行 Helm 安装，以及 Colima / k3d / GCP / 多集群引导流程。此项由 openchoreo-install 负责。OpenChoreo 运行后，第 2 天的平台工作由此技能负责。
• 聚合运行时日志 / 指标 / 追踪查询——跨副本搜索日志、查询指标、查找追踪、查询告警和事件。要获取绑定下的 Pod 级证据，请使用 get_resource_events / get_resource_logs；要查看更长时间范围的历史记录，请改用相关 Plane 上的 kubectl logs，或在已配置时通过相应 UI / API 查询可观测性后端（Loki / Prometheus / Tempo）。
• 外部系统操作——IdP / Thunder / SSO 管理工作、外部密钥后端管理（Vault / AWS Secrets Manager / OpenBao）、Git 提供商配置（webhook、部署密钥）、商业版 WSO2 Choreo 云资源，以及事件状态变更（确认 / 解决 / RCA）。用户提出这类需求时，请明确说明并指引他们前往相应系统；同时解释此技能可以配置的 OpenChoreo 侧内容。

工具范围

两个工具界面：用于 OpenChoreo CRD 的 MCP（openchoreo-cp 服务），以及用于集群原生事项的 kubectl / Helm（Helm 安装 / 升级、ClusterSecretStore、Argo ClusterWorkflowTemplate、Kubernetes Gateway API 资源、原始控制器 / Agent / 网关 Pod 日志）。操作步骤会为每一步指定正确的工具界面。

工具命名。 在此技能中，MCP 工具均以其基本名称引用（例如 create_environment）。实际可调用名称会带有特定 Agent 的前缀，用于包装服务名称——Claude Code 使用 mcp__openchoreo-cp__<tool>。其他编码 Agent 使用不同的前缀。请根据你的 Agent 预期使用相应前缀。

合并作用域的工具。 ProjectType / ComponentType / ResourceType / Trait / Workflow、三类 Plane，以及 Authz 角色 / 绑定类别，各自都由一个接受 scope 参数的工具提供——"namespace"（默认值；需要 namespace_name）或用于平台级 Cluster* 资源的 "cluster"。此技能使用规范名称 + scope；例如，使用 scope: "cluster" 调用 create_component_type 会创建 ClusterComponentType，调用 create_resource_type 会创建 ClusterResourceType，调用 create_project_type 会创建 ClusterProjectType。旧的 *_cluster_* 名称仍作为已弃用的别名存在（v1.1 中显示横幅提示，v1.2 中隐藏，v1.3 中移除），也可用于 v1.1 服务——请优先使用规范形式。

工作方式

完整的逐任务发现流程见 concepts.md（在 Step 1 加载）。请牢记以下持久原则：

• 实时集群输出优先于记忆。 不要假定可用的 ComponentTypes、Traits、Workflows、Environments、平面状态或字段名称——先通过 MCP 发现。
• 先看架构，再编写。 从头编写规范前，先获取创建架构（get_component_type_creation_schema、get_trait_creation_schema）或资源架构（get_*_schema）。MCP 的 create_* / update_* 调用接收结构化规范载荷，而非 YAML 文件——但适用相同的架构。
• 对 ComponentType / Trait / Workflow 来说，update_* 会完整替换规范。 先调用 get_*，在本地修改，然后发送完整规范。省略某个字段就会将其删除。
• 优先使用 MCP。 只有针对集群原生 CRD（Helm、ClusterSecretStore、Argo ClusterWorkflowTemplate、Kubernetes Gateway API），或 MCP 未提供该操作的写入路径时，才使用 kubectl。
• 默认使用 default 命名空间。 创建新命名空间前务必先询问——命名空间是组织边界，不是随意的默认选项。
• 一次只更改一个层级（Helm 值 → 控制平面 CRD → 远程平面资源 → 应用可见结果）。不要靠猜测平台内部实现来修复应用症状。

稳定的防护原则

• update_environment 支持部分更新，但 data_plane_ref 不可变。 要将环境重新指向另一个平面，必须先删除再重新创建（并重新绑定所有现有的 ReleaseBindings）。
• Helm 升级顺序很重要。 先升级控制平面，绝不能让远程平面超前于它。
• 范围很重要。 集群范围和命名空间范围的资源不可互换。ClusterComponentType 只能引用 ClusterTrait 和 ClusterWorkflow，不能引用对应的命名空间范围资源。在范围合并的 MCP 工具中，这由 scope 参数指定——scope: "cluster" 操作 Cluster* 资源，scope: "namespace"（默认值）操作命名空间范围资源。
• status.conditions、实时资源 YAML 和当前控制器日志，比记忆更可靠。 如果任务需要了解精确的控制器行为或 CRD 字段，请检查代码仓库或当前文档，不要猜测。
• 优先选择可逆、可检查的更改，避免跨多个平面或命名空间进行大范围编辑。
• 移交的迁移计划就是规范。 用户提供迁移或入门计划时，应以其中的命名空间、类型名称、创建还是复用的决策，以及各环境覆盖项为准。只有在明确说明时才可偏离——行动前先说明更改内容及原因（集群实际情况不同、简化等），绝不能悄悄替换。
• 绝不要修改共享类型来适配单个应用。 对现有共享类型（尤其是集群范围类型）调用 update_component_type / update_trait / update_workflow 会完整替换规范，并影响所有使用方。要满足单个应用的需求，应以现有类型结构为基础创建新类型。
• 工具缺失意味着版本不匹配，而非功能不存在。 找不到文档中提及的 MCP 工具或 occ 子命令时，应检查已安装的 CLI / 服务版本与集群版本是否匹配，再判断该功能是否不存在——向用户说明版本不匹配，然后采用备用方案。

反模式

• 跳过操作指南。 在执行任何新操作之前（本轮出现新的 CRD 类型、生命周期操作、编写任务），先重新查看上方的操作指南索引，加载匹配的操作指南（调用一次 Read），然后再调用 MCP / kubectl。跳过这一步会导致 kubectl 调用层层出错，也会遗漏现有的 MCP 工具。仅了解概念还不够——操作指南会按顺序列出正确的工具调用。
• 在确定实际问题之前加载所有参考文件。
• 不检查当前集群或资源架构，就重复使用过时示例。
• 尚未检查受影响的对象和日志，就对集群进行大范围扫描。
• 未检查应用资源链，就将应用级部署症状完全归因于平台问题。
• 一次进行多项平台变更，导致无法辨别因果关系。
• 未询问用户就创建新命名空间——除非用户明确另有要求，否则使用 default。
• 在已有 MCP 工具可执行该操作时仍使用 kubectl。
• 发送不完整的 update_component_type / update_trait / update_workflow 规格——调用会替换整个规格；缺失字段会被删除。
• 臆造此技能中不存在的可观测性工具（query_* 日志 / 指标 / 跟踪 / 告警 / 事件工具）。请对相关平面使用 kubectl logs，或查询可观测性后端自带的界面。