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 バージョン、およびタスクごとに調査を先行させるワークフローについて説明しています。これらは、エージェントがあらゆるタスクで再利用する情報です。記憶に頼るのは確実ではありませんが、このリファレンスは短くまとまっています。

担当する各タスクについても、作業を始める前に、該当するリファレンスを読み込んでください。

• ProjectType / ClusterProjectType の作成または更新（プロジェクトの Cell インフラストラクチャーテンプレート — Cell の名前空間、クォータ、ネットワークポリシー、基本 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。
• プレーン間の障害分離、コントローラー／ゲートウェイ／エージェントのログ調査、ゲートウェイ／ルートの診断 → ./references/troubleshooting.md。

これらのリファレンスに含まれていない PE のトピック — TLS／外部 CA、コンテナーレジストリ、アイデンティティプロバイダーの設定、マルチクラスター接続、デプロイトポロジー、オブザーバビリティアダプターモジュール、API ゲートウェイモジュール、アラートストレージバックエンドの選択、IdP／ブートストラップ認証マッピング、Helm アップグレード — については、公式の PE ガイド 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
• プロジェクト + 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 リソース、生のコントローラー / エージェント / ゲートウェイログの調査。
• プラットフォーム側の障害のトラブルシューティング — プレーン間の障害切り分け、プレーンのヘルスチェック、コントローラー / ゲートウェイ / エージェントのログ → troubleshooting.md

このスキルでできないこと

• アプリケーションレベルの作業 — openchoreo-developer の担当です。 Component ／ Workload ／ ReleaseBinding の作成、workload.yaml の編集、patch_component traits: [...] を使った PE 作成の Trait の 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 をゼロから初期インストールする作業 — 新しいコントロールプレーンと最初のプレーンへの Helm インストール、Colima ／ k3d ／ GCP ／マルチクラスターのブートストラップ手順などです。これらは openchoreo-install の担当です。OpenChoreo の稼働開始後のプラットフォーム運用は、このスキルの担当に戻ります。
• ランタイムログ／メトリクス／トレースの集約クエリ — レプリカをまたいだログ検索、メトリクスクエリ、トレース検索、アラートやインシデントのクエリなどです。バインディング配下のポッドレベルの証跡には get_resource_events ／ get_resource_logs を使用してください。より長期間の履歴を確認する場合は、該当するプレーンに対する kubectl logs を使用するか、設定済みであればオブザーバビリティバックエンド（Loki ／ Prometheus ／ Tempo）独自の UI ／ API を使用してください。
• 外部システムの操作 — IdP ／ Thunder ／ SSO の管理、外部シークレットバックエンド（Vault ／ AWS Secrets Manager ／ OpenBao）の管理、Git プロバイダーの構成（webhook、デプロイキー）、商用 WSO2 Choreo クラウドリソース、インシデント状態の変更（確認応答／解決／RCA）などです。ユーザーから依頼された場合は、その旨を明確に伝え、該当するシステムを案内してください。このスキルで設定できる OpenChoreo 側の要素についても説明してください。

ツールの範囲

2 つの操作面があります。OpenChoreo CRD には MCP（openchoreo-cp サーバー）、クラスター固有の操作（Helm のインストール／アップグレード、ClusterSecretStore、Argo ClusterWorkflowTemplate、Kubernetes Gateway API リソース、生のコントローラー／エージェント／ゲートウェイのポッドログ）には kubectl ／ Helm を使用します。各手順では、ステップごとに適切な操作面を示しています。

ツールの命名。 このスキルでは、MCP ツールは短い名前（例：create_environment）で記載しています。実際に呼び出す名前には、サーバー名を囲むエージェント固有のプレフィックスが付きます。Claude Code では mcp__openchoreo-cp__<tool> です。他のコーディングエージェントでは、異なるプレフィックスが使用されます。利用するエージェントに合った名前を使用してください。

スコープを集約したツール。 ProjectType ／ ComponentType ／ ResourceType ／ Trait ／ Workflow、3 つのプレーンファミリー、Authz のロール／バインディングファミリーは、それぞれ scope 引数を取る単一のツールです。scope は "namespace"（デフォルト。namespace_name が必要）またはプラットフォーム全体の Cluster* リソースを対象とする "cluster" を指定します。このスキルでは、標準名と scope を使用します。たとえば、scope: "cluster" を指定した create_component_type で ClusterComponentType を作成し、scope: "cluster" を指定した create_resource_type で ClusterResourceType を作成し、scope: "cluster" を指定した 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 を使います。 kubectl を使うのは、クラスター固有の CRD（Helm、ClusterSecretStore、Argo の ClusterWorkflowTemplate、Kubernetes Gateway API）を扱う場合、またはその操作の書き込み方法が MCP で提供されていない場合に限ります。
• デフォルトでは 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 呼び出しを 1 回）、その後で MCP／kubectl を呼び出してください。省略すると、kubectl の呼び出しが連鎖的に増え、既存の MCP ツールを見落とします。概念の参照だけでは不十分です。レシピには、適切なツール呼び出しの順序が記載されています。
• 実際の問題を特定する前に、すべてのリファレンスファイルを読み込む。
• 現在のクラスターやリソーススキーマを確認せずに、古い例を繰り返す。
• 影響を受けているオブジェクトとログを確認する前に、クラスター全体を広範囲に調査する。
• アプリのリソースチェーンを確認せず、アプリレベルのデプロイの症状を純粋にプラットフォームの問題として扱う。
• 複数のプラットフォーム変更を同時に行い、因果関係を見失う。
• ユーザーに確認せず新しい名前空間を作成する。明示的な指示がない限り、default を使用してください。
• 操作に MCP ツールがあるのに、kubectl を使う。
• 不完全な update_component_type／update_trait／update_workflow の仕様を送る。この呼び出しは仕様全体を置き換えるため、不足しているフィールドは削除されます。
• このスキルに存在しない可観測性ツール（ログ／メトリクス／トレース／アラート／インシデント用の query_* ツール）を作り出す。関連するプレーンに対して kubectl logs を使うか、可観測性バックエンド自体の UI でクエリしてください。