openchoreo-developer

OpenChoreo 開発者ガイド

コントロールプレーンの MCP サーバーを通じて、アプリケーション開発者が OpenChoreo 上でサービスをリリースし、運用できるよう支援します。MCP を通じて稼働中のプラットフォーム構成を確認し、タスクで必要な場合にのみ詳細なリファレンスを読みます。

Step 0 — MCP の接続を確認する

list_namespaces を実行します。ツールに接続できない場合は、https://openchoreo.dev/docs/ai/mcp-servers/ に従って openchoreo-cp MCP サーバーを設定する必要があることをユーザーに伝え、そこで終了します。

Step 1 — 概念を読み込む（必須）

何よりも先に、./references/concepts.md を最後まで読んでください。 タスクが簡単に見えても省略できません。記憶だけでは誤りが生じます。セッションごとに一度読み込みます。これを読まずに作業していることに気づいた場合は、作業を止めて今すぐ読み込んでください。

次に、タスクに合ったリファレンスを読み込みます。

• 初回デプロイ（まだ Project がない、または OpenChoreo に初めて触れる場合）→ ./references/getting-started.md
• 既存の Component を扱う場合 → 該当するレシピに直接進みます。既存の Component で BYO とソースビルドのどちらを選ぶか判断するには、get_component を実行して spec.workflow を確認します。存在する場合 → build-from-source.md、存在しない場合 → deploy-prebuilt-image.md。

Step 2 — プラットフォーム関連のタスクでは PE スキルを読み込む

リクエストが ProjectType ／ ComponentType ／ ResourceType ／ Trait ／ Workflow（またはクラスターのバリアント）、あるいは このスキルでは対応できないこと に該当する場合は、../openchoreo-platform-engineer/SKILL.md も読み込んでください。PE スキルがインストールされていない場合は、エスカレーションしてください。

このスキルでできること

• プロジェクト — 作成、更新。create_project は、PE が作成した (Cluster)ProjectType を参照する任意の type_name / type_kind / parameters を受け取ります。省略した場合は、デフォルトの ProjectType が使用されます。コンポーネントをデプロイする前に、プロジェクトの セル を環境ごとにデプロイする必要があります → deploy-and-promote.md の プロジェクトセルをデプロイする を参照してください。
• コンポーネント — 作成、更新、auto_deploy / parameters / traits / workflow / メタデータの patch_component。
  • BYO イメージ → deploy-prebuilt-image.md
  • ソースからビルド → build-from-source.md
• ワークロード — イメージ、ポート、エンドポイント、環境変数、ファイル → configure-workload.md
• トレイトのアタッチ — プラットフォームのカタログから選択 → configure-workload.md
• コンポーネントの接続 — エンドポイントの依存関係。プラットフォームが環境変数を注入します → connect-components.md
• リソースの利用 — マネージドインフラストラクチャの依存関係（データベース、キュー、キャッシュ）。プラットフォームは dependencies.resources[] を介して、出力を環境変数およびファイルマウントとして注入します → use-a-resource.md
• SecretReferences — CRUD と secretKeyRef の利用 → manage-secrets.md。ClusterSecretStore は PE が管理します。
• デプロイと昇格 — プロジェクトセルを環境ごとにデプロイ（create_project_release_binding、ピン留めはコントローラーによってシードされます）し、ComponentRelease を Environment にバインドして、両方を DeploymentPipeline に沿って昇格します → deploy-and-promote.md
• 環境ごとのオーバーライド — ReleaseBinding のレプリカ、リソース、環境変数、トレイト設定 → override-per-environment.md
• ソフトアンデプロイ／ロールバック — update_release_binding release_state: Undeploy を実行するか、以前の ComponentRelease に再バインドします。
• 開発者リソースのハード削除 — delete_component、delete_workload、delete_release_binding、delete_project、delete_component_release。破壊的な操作のため、事前に確認してください。delete_namespace はありません — PE 側の操作です。
• ランタイムの調査 — Component / ReleaseBinding の status.conditions[] と status.endpoints[]、get_resource_tree によるバインディングとレンダリング済み K8s リソースの対応付け、get_resource_events / get_resource_logs による Pod レベルの証拠の確認、WorkflowRun のログとイベント → inspect-and-debug.md
• プラットフォームリソースの検出（読み取り専用）— ProjectTypes、ComponentTypes、ResourceTypes、Traits、Workflows、Environments、DeploymentPipelines、planes。

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

プラットフォーム側の作業：ProjectTypes / ComponentTypes / ResourceTypes / Traits / Workflows、Environments、DeploymentPipelines、planes の作成、認可、ゲートウェイ／シークレットストア／IdP の設定、オブザーバビリティのセットアップ、長期間にわたるログ／メトリクス／トレースのクエリ（Pod レベルのイベントと現在のログは get_resource_events / get_resource_logs で確認できます）。

インストールされている場合は ../openchoreo-platform-engineer/SKILL.md を読み込んでください。インストールされていない場合は、プラットフォームエンジニアにエスカレーションするようユーザーに伝えてください。PE の担当範囲のカタログ：https://openchoreo.dev/docs/platform-engineer-guide/.

ツールの範囲

MCP サーバーは 1 つです：openchoreo-cp。このスキルでは、ツールは短縮名（例：get_component）で参照します。エージェントがプレフィックスを付与します（Claude Code では mcp__openchoreo-cp__<tool> を使用します）。

ComponentType / ResourceType / Trait / Workflow および plane ツールはスコープが統合されています。scope 引数を持つ 1 つのツールで、"namespace"（デフォルト）またはプラットフォーム全体の Cluster* リソース用の "cluster" を指定します。このスキルでは常に、正式名称と scope を使用します。旧 *_cluster_* 名も非推奨エイリアスとして引き続き存在します（v1.1 ではバナーが表示され、v1.2 では非表示になり、v1.3 では削除されます）。v1.1 サーバーでは代わりに使用できますが、正式な形式を優先してください。

resource ツールセット（開発者向け、デフォルトで有効）では、Resource の CRUD と、スコープが統合された (Cluster)ResourceType の読み取りが可能です。ResourceReleaseBinding と ProjectReleaseBinding の CRUD はどちらも、ReleaseBinding とともに deployment ツールセットに属します。resource_release_binding の作成／更新呼び出しは、Resource を環境にデプロイ（または昇格）する方法です。project_release_binding の作成／更新は、プロジェクトのセルに対して同じ操作を行います。(Cluster)ProjectType はここでは読み取り専用です（list_project_types／get_project_type／get_project_type_schema。scope に対応）。作成は PE 側で行います。

作業スタイル

• 稼働中のクラスターの出力を記憶より優先してください。 まず MCP 経由で確認し、利用可能な ComponentTypes / Traits / Workflows / Environments / フィールド名を推測しないでください。
• スキーマを優先して作成してください。 仕様を一から記述する前に、get_workload_schema、またはプラットフォーム全体の標準に対して scope: "cluster" を指定した get_component_type_schema / get_trait_schema を使用してください。

安定したガードレール

• すべての作業はコントロールプレーンの MCP サーバーを通じて行います。MCP 経由では実行できないタスクはプラットフォーム側の作業です。引き継いでください。
• サードパーティ製／公開アプリでは、デフォルトで BYO イメージを使用します。 サードパーティの Dockerfile で ARG BUILDPLATFORM を使用している場合、ソースからのビルドは失敗することがよくあります（終了コード 125）。これを見つけたら、すぐに BYO に切り替えてください。
• サードパーティ製アプリをデプロイする前に： 公式マニフェストを取得し、必須の環境変数をすべて洗い出します。依存関係からサービスアドレスは注入されますが、PORT、機能フラグ、ベンダー SDK の無効化フラグは注入されません。
• 引き継がれた移行計画が仕様です。 ユーザーから移行／オンボーディング計画が提供されたら、名前空間、環境変数の配置（静的な Workload 環境変数と環境ごとの workloadOverrides のどちらにするか）、接続方法の判断はその計画に従ってください。変更する場合は、黙って置き換えるのではなく、実行前に何をなぜ変更するのかを必ず明示してください。
• アプリに合わせて型を作成してください。提供済みの型に合わせてアプリの形を変えてはいけません。 計画（またはアプリ）が必要とする ComponentType、ResourceType、Trait がインストールされていない、または提供済みでも要件を満たさない場合は、型を作成するのが解決策です。../openchoreo-platform-engineer/SKILL.md を読み込み、目的に合った型を作成してください。次のような方法で不足を回避してはいけません。提供済みの ResourceType が合わないからといって、管理対象の依存関係を単純な Component として再モデル化する（依存関係は引き続き Resource です。依存関係に必要な内容を再現する ResourceType を作成してください）。提供済みの Trait がないからといって、アプリに必要な機能を削る（Trait を作成してください）。形状やデフォルト値が合わない提供済みの ComponentType にワークロードを無理に当てはめる（ComponentType を作成してください）。提供済みの型を再利用するのは、要件を実際に満たす場合に限ってください。型はニーズに合わせるものであり、その逆ではありません。
• リソースは ComponentType のデフォルト値ではなく、ソースに基づいて設定してください。 ワークロードのソースで宣言されたリクエスト／制限を使用します（CPU とメモリの両方）。ソースに指定がない場合は、ワークロードの種類に応じて妥当なデフォルト値を選んでください。通常はデモ向けの値であり、割り当て不足になりがちな汎用 CT のデフォルト値を引き継いではいけません。CT を作成する場合は、妥当なデフォルト値を environmentConfigs に設定してください。そうでない場合は、ReleaseBinding の環境ごとの設定で指定してください。
• 注入される接続値はリテラルです。$(VAR) による補間はありません。 依存関係の envBindings は、各接続値（address／host／port／basePath）を、指定した環境変数にリテラルとして注入します。プラットフォームは、他の環境変数値に含まれるシェル／Kubernetes の $(VAR) 参照を展開しないため、value: "http://$(HOST):$(PORT)" はそのままコンテナに渡されます。アプリが読み取る環境変数を正確にバインドしてください。注入される変数だけでは必要な複合文字列（完全な URI、スキームなしの host:port、スキームのプレフィックスなど）を直接設定できない場合は、その複合値をリテラルの環境変数として設定してください。通常は、解決済みのアドレスを使用した環境ごとの workloadOverride を使い、$(VAR) は参照しないでください。
• ツールが見つからない場合は、存在しないのではなくバージョンの不一致を疑ってください。 ドキュメントに記載された MCP ツールが見つからない場合、機能が存在しないと判断する前に、サーバーのバージョンとクラスターのバージョンを確認してください。不一致をユーザーに報告したうえで、代替手段に切り替えるか、エスカレーションしてください。

アンチパターン

• レシピを確認しないこと。 新しい操作（今回のターンで新しい CRD 種別を扱う場合、ライフサイクル操作、ランタイムの調査など）の前に、必ず上のレシピインデックスを再確認し、該当するレシピを読み込んでから（Read を 1 回呼び出す）、MCP／kubectl を呼び出してください。確認を省くと、kubectl の呼び出しが重複し、既存の MCP ツールを見落とすことになります。概念への参照だけでは不十分です。レシピには、適切なツール呼び出しの順序が記載されています。
• 対象のリソースがすでに特定されているか確認する前に、すべての探索呼び出しを実行すること。
• get_*_schema／get_* で現在の形状を確認できるのに、記憶を頼りに仕様を書くこと。
• ReleaseBinding.status.endpoints[] を確認せず、デプロイ済み URL を推測すること。
• 証拠から別の原因が示されているのに、プラットフォーム側の障害をアプリだけの問題として扱うこと。
• 事前ビルド済みイメージがあるサードパーティ製アプリに、ソースビルドコンポーネントを作成すること。
• 同じプロジェクト内のサービス間依存関係に visibility: external を設定すること。デフォルトは project です。
• Ready=True を「動作している」と見なすこと。 Ready は調整済みであることを意味し、正常に機能していることを意味しません。クラッシュループ中のコンテナでも Ready が断続的に変化することがあり、安定したコンテナでも、設定に誤りがあれば（環境変数が誤った名前にバインドされている、依存関係の解決先が存在しないなど）、Ready になっていることがあります。get_resource_tree → get_resource_events／get_resource_logs で確認し、実際にエンドポイントへアクセスしてください。