Control Plane スキル

Control Plane とは

Control Plane は、AWS、GCP、Azure、プライベートクラウド全体でコンテナ化されたワークロードを統一されたインターフェイスからデプロイおよび管理するハイブリッドプラットフォームです。クラウドプロバイダーの違いを一貫性のある API、CLI (cpln)、Console UI、Terraform プロバイダー、Pulumi プロバイダー、Kubernetes Operator、MCP Server の背後に抽象化します。PCI DSS Level 1、SOC 2 Type II、HIPAA 適格認定取得済みです。

主要なエントリーポイント:

• CLI: cpln — npm @controlplane/cli、Homebrew (brew tap controlplane-com/cpln && brew install cpln)、またはバイナリでインストール
• Console: https://console.cpln.io
• API: https://api.cpln.io
• MCP Server: https://mcp.cpln.io/mcp (AI エージェント向け 80+ ツール)
• ドキュメント: https://docs.controlplane.com (AI エージェント向けページインデックス: https://docs.controlplane.com/llms.txt)
• 完全な CLI 規約とハルシネーション罠: https://docs.controlplane.com/cli-conventions.md

このスキルを使用する場合

マルチクラウド GVC 全体でワークロードをデプロイする場合、インフラストラクチャを構成する場合 (ロケーション、ネットワーク、ファイアウォール、ドメイン)、シークレット + アイデンティティ + ポリシーアクセスチェーンを管理する場合、cpln apply / CI/CD で自動化する場合、cpln logs / exec / connect / port-forward でデバッグする場合、イメージをビルドしてプッシュする場合、Kubernetes / Docker Compose / Helm から移行する場合、mk8s / BYOK / Kubernetes Operator を使用する場合、または MCP Server 経由で AI ツールを接続する場合。

リソースモデル

Org (Organization) — トップレベルの分離境界、グローバルに一意な名前
├── Principals: ユーザー、グループ、サービスアカウント           (org スコープ)
├── Governance: ポリシー、クォータ、監査コンテキスト          (org スコープ)
├── Infrastructure: クラウドアカウント、エージェント、ロケーション、    (org スコープ)
│                   IP Sets、mk8s クラスター
├── Assets: シークレット (12 タイプ)、イメージ、ドメイン           (org スコープ)
└── GVC (Global Virtual Cloud) — デプロイメント環境
    ├── Workloads (1+ コンテナ、4 タイプ)             (GVC スコープ)
    ├── Identities (クラウドアクセス、シークレット、ネットワーク)      (GVC スコープ)
    └── Volume Sets (永続ストレージ)                  (GVC スコープ)

スコープルール:

• Org スコープ: シークレット、ドメイン、クラウドアカウント、エージェント、ポリシー、イメージ、グループ、サービスアカウント、IP Sets、mk8s
• GVC スコープ: Workloads、Identities、Volume Sets
• ワークロードは親 org からシークレットを参照できますが、ボリュームセットとアイデンティティは自身の GVC からのみ参照できます
• ドメインは org スコープですが、一度に正確に 1 つの GVC に関連付けられます
• プルシークレットは GVC レベル で構成されます (ワークロードごとではなく) — Docker、ECR、GCP シークレットタイプのみプルシークレットとして機能します
• 1 ワークロードあたり 1 つのアイデンティティですが、1 つのアイデンティティは同じ GVC 内の複数のワークロードで共有できます。アイデンティティは GVC 全体で共有できません — それを必要とする各 GVC で同じ仕様でアイデンティティを再作成してください。

プラットフォーム機能

機能	説明	使用時期
Workloads	サーバーレス、標準、cron、ステートフルとしてコンテナをデプロイ	主要デプロイメント単位 — ほとんどのユーザーはここから開始します
Template Catalog	30+ の本番対応テンプレート (Postgres、Redis、Kafka、MongoDB など)	データベース、キュー、または一般的なサービスが必要 — ゼロから構築する代わりにインストール
Managed Kubernetes (mk8s)	AWS、GCP、Azure、Hetzner など全体で Kubernetes クラスターをプロビジョニング	完全な Kubernetes クラスターが必要 (チームは mk8s クラスターにデプロイ)
CPLN Platform (BYOK)	既存の Kubernetes クラスターを Control Plane ロケーションとして登録	既に Kubernetes があります — 上に Control Plane ワークロード管理が必要
Kubernetes Operator	Control Plane リソースを Kubernetes CRD として管理 (ArgoCD/GitOps)	Control Plane インフラの Kubernetes ネイティブ GitOps が必要
Agents	プライベートネットワークへのセキュアトンネル (VPC、オンプレミス、データセンター)	ワークロードがファイアウォール背後のプライベート TCP エンドポイントに到達する必要
External Logging	ログを S3、CloudWatch、Coralogix、Datadog、Logz.io、Stackdriver にシップ	コンプライアンス、長期保持、または外部ログ分析
Domains	自動 TLS、ジオ-ルーティング、パスベースルーティング搭載のカスタムドメイン	独自ドメインでワークロードを公開 (CNAME または NS デリゲーション)
MCP Server	インフラをプログラムで管理する AI エージェント向け 80+ ツール	AI 支援インフラストラクチャ管理

ガードレール — まず読んでください

本番環境の障害を防ぐ 8 つのルール。スキップするとデータロス、クロステナント変更、サイレント実行時障害、トークン予算の浪費につながります。

1. 状態を変更する前に Org / プロファイル / GVC を確認

cpln の状態を変更するコマンド (create、delete、update、apply、patch、edit、add-binding、remove-binding、add-key、force-redeployment、clone、image build --push、シークレット create-* バリアント、add-location、remove-location) を実行する前に、ターゲット org、プロファイル、および (該当する場合) GVC が明確に確立されている必要があります。いずれかが不足している場合は、停止して質問してください。アクティブな CLI プロファイルにサイレントにフォールバックしないでください。

コンテキストは次の場合にのみ確立されます: ユーザーが現在のリクエストで名前を付けた、この会話の前に名前を付けた、この セッションで MCP set_context を呼び出した、または明示的な「デフォルトプロファイルを使用」命令を与えた場合。それ以外の場合は質問してください:

このコマンドを実行する前に、ターゲットを確認したいです。アクティブなプロファイルは <name> (org: <org>、GVC: <gvc>) のようです。それを使用すべき、または別の org / プロファイル / GVC を使用すべき?

読み取り専用 コマンド (get、query、audit、logs、permissions、access-report、eventlog) の場合、デフォルト化は許容可能です — ただし ターゲットを最初にアナウンス: "プロファイル <name> → org <org>、GVC <gvc> を使用中…"

2. シークレットアクセス — 3 つの必須ステップ

ワークロードはすべての 3 つなしでシークレットにアクセスできません:

1. Identity 作成および割り当て: cpln workload update WL --gvc GVC --set spec.identityLink=//identity/ID
2. Policy identity に reveal を付与: cpln policy create --name P --target-kind secret --resource SECRET その後 cpln policy add-binding P --permission reveal --identity //gvc/GVC/identity/ID
3. Reference 環境変数またはボリューム内: cpln://secret/NAME.payload (opaque)、cpln://secret/NAME.KEY (dictionary)、.username/.password (userpass)、.cert/.key (tls) など

いずれか 1 つが不足 = サイレント実行時障害。#1 サポート問題。

3. イメージ参照

• 決して 外部イメージを docker.io/ で接頭辞を付けないでください。docker.io/library/nginx:latest ではなく nginx:latest を使用してください。
• Org 独自のレジストリ ワークロード仕様内: //image/NAME:TAG。ホスト名 <own-org>.registry.cpln.io は docker login/push にのみ使用され、ワークロード仕様内では決して使用されません。
• クロス org プル: <other-org>.registry.cpln.io/NAME:TAG。
• イメージは linux/amd64 である必要があります。cpln image build --push はこれをデフォルトとします。間違ったプラットフォーム = 実行時に exec format error。
• ワークロード仕様の port はコンテナが実際にリッスンしているポートと一致する必要があります。そうでないとヘルスチェックが失敗します。

4. ファイアウォールデフォルト — すべてが拒否されます

• 内部 (ワークロード間): inboundAllowType: none — すべてブロック。same-gvc、same-org、または workload-list に設定します。
• 外部インバウンド: 無効。CIDR を追加 (0.0.0.0/0 ですべて) または cpln workload create で --public を使用します。
• 外部アウトバウンド: 無効。CIDR またはホスト名を追加します。ホスト名エグレスはポート 80、443、445 に制限されます。CIDR ルールはホスト名より優先されます。ブロックルールはに許可より優先されます。

ファイアウォール構成なしのワークロードは、データベースに到達できず、ユーザーに到達できず、ピアと通信できません。常に明示的に構成します。

5. ワークロードタイプ制約 (作成後は不変)

機能	serverless	standard	stateful	cron
ゼロへのスケール	rps または concurrency	KEDA のみ	KEDA のみ	いいえ
ポート	正確に 1 コンテナ × 1 ポート (必須)	0 以上	0 以上	公開してはいけません
Capacity AI	はい (デフォルト)	はい (デフォルト)	常に無効	N/A
永続ボリューム	いいえ	いいえ	はい (ボリュームセット)	いいえ
replicaDirect LB	いいえ	いいえ	このタイプのみ	いいえ
spec.job	禁止	禁止	禁止	必須
マルチメトリック オートスケーリング	いいえ	はい (cpu/memory/rps)	はい (cpu/memory/rps)	N/A
maxConcurrency	使用	無視	無視	N/A
timeoutSeconds 最大	600	3600	3600	N/A
ワークロードあたりのコンテナ最大数	8	8	8	8

• ワークロードタイプは不変です。 タイプを変更するには削除 + 再作成が必要です。まず状態をキャプチャします: cpln workload get NAME --gvc GVC -o yaml-slim > NAME.bak.yaml。
• Capacity AI は次と互換性がありません: ステートフル、CPU オートスケーリング、マルチメトリックオートスケーリング、GPU。
• Cron はオーバーライドなしですべての GVC ロケーションにデプロイします。spec.job と schedule 必須。プローブ、オートスケーリング、timeoutSeconds、capacityAI、debug は無視されます。
• ワークロード名 最大 49 文字。-headless で終わることはできません。
• コンテナ名予約、プローブ XOR ルール、GPU 制約、および完全な検証については、マニフェストを作成する際に /reference/workload/general を取得してください。

6. 破壊的な操作 — 爆発半径で確認

破壊的な操作の前に、構造化されたサマリーを提示し、明示的な確認を待機してください — 権限がオートアプルーブする場合でも。権限モードはツール-プロンプト UX です。これは会話レベルのセーフティで、独立しています。

• 常に破壊的: 任意の cpln <resource> delete、gvc delete-all-workloads、volumeset shrink、volumeset snapshot delete、volumeset volume delete。
• サービス中断: policy remove-binding (実行時アクセスが壊れる)、serviceaccount remove-key (CI/CD が壊れる)、group remove-member (ユーザーがロックアウト)、gvc remove-location (再デプロイメントを強制)。
• 暗黙的な破壊 (不変性の罠): org 削除は不可能。ワークロード type/name は不変 (名前変更は cpln workload clone OLD --name NEW --gvc GVC 経由)。ボリュームセット fileSystemType および performanceClass は不変。cpln apply 名前変更リソースの新しいリソースを作成 (古いものは cpln delete --file ... で削除する必要があります)。

削除 + 再作成が唯一の道の場合: (1) -o yaml-slim で状態をキャプチャ、(2) 同じ名前を再利用して URL/内部 DNS/ドメインルート/ポリシー targetLinks/アイデンティティバインディングを保持、(3) 確認 — ユーザーは 技術 ではなく 目標 を承認しました。

必須の確認形式:

破壊的な操作を実行する必要があります:

• アクション: <正確なコマンド>
• 影響を受け: <name + kind> in <org> / <gvc>
• 爆発半径: <トラフィック、進行中のリクエスト、ダウンストリーム呼び出し元、ディスク上のデータ、CI/CD パイプライン、パブリック URL>
• 可逆性: <X 経由で可逆 / 可逆でない>
• 軽減: <<file>.bak.yaml としてマニフェストをキャプチャ; 同じ名前を再利用します; など>

進行を確認してください。

明確なはいとは異なる何か = 停止してください。複数の破壊的なタスクを 1 つの事前質問にバンドルします。破壊的と非破壊的をバンドルしてスリップスルーしないでください。

7. 制約の競合 — 表面化、サイレント デフォルトなし

互換性制約がユーザーの意図をブロックする場合 (ステートフルへの並行性オートスケーリング、cron へのゼロへのスケール、shared ボリュームセット上のスナップショット、CPU メトリックを持つ Capacity AI)、それを表面化し、代替案を提示します。disabled / none / 1 replica / manual にサイレント ダウングレードしないでください — これらはしばしば過小プロビジョニング バグまたは SPOF を付属させます。

必須形式:

<resource> を構成する制約にぶつかりました:

• あなたが求めたもの: <intent>
• 制約: <正確な制限>
• 代替案:
  • <value> — <なに、トレードオフ>
  • <value> — <...>
• 私の推奨: <option> 理由: <プロジェクト根拠の推論>。

どちらをお選びですか? または上流の選択を再検討してください (例: ワークロードタイプ)?

保守的なデフォルトが正しい場合でも (例: シングルライター SQLite の場合の min=max=1)、推論で明示的に言ってください。時々正しい答えは以前の決定から撤退することです。

8. 長時間実行操作 — AI レイヤーからポーリングしない

ステートフル プロビジョニング、大規模イメージプッシュ、mk8s 作成、GVC ロケーション追加 — 長時間。AI レイヤーからステータスをポーリングしないでください。 各ポーリングは会話コンテキストを再読み込みし、ゼロ診断値のために数千トークンを焼きます。

デフォルト待機: cpln apply --file <m>.yaml --ready。CLI の内部でブロック。AI トークン ≈ 0。

ギャップ: --ready は終末コンテナエラー (ゼロ以外の終了、イメージプル エラー、クラッシュループ、致命的なスタートアップ) で高速失敗しません。最初のデプロイが正しく構成されていない場合、プレーンな --ready はコンテナが死亡している間、その完全なタイムアウトを通じて座っています。

パタース-ウィンドウ ペイシェンス セーフティネット を使用 (バックグラウンドで --ready を実行、期待される待機を睡眠、30 秒ごとに確認された終末エラーを監視) の場合: 最初のデプロイ、新しくビルドされたイメージ、ワークロードタイプ移行、最近の障害後の再適用。プレーンな --ready は問題ありません: イメージタグバンプ、env 更新、健康なワークロード上の小さな構成調整。完全な bash パターン: /guides/cpln-apply。

その他の待機:

• アプリケーション層: curl --retry 30 --retry-delay 5 --retry-connrefused -fsS https://<endpoint>/healthz (cpln workload get WL --gvc GVC -o json | jq -r .status.endpoint 経由でエンドポイントを検索)
• --ready なし操作 (force-redeployment、post-update): timeout 600 bash -c 'until cpln workload get N --gvc G -o json | jq -e ".status.healthCheck.status == true" >/dev/null 2>&1; do sleep 10; done'

ハード ルール — FAILED / killed / timeout の場合: 診断、再待機なし。 1 度に取得: cpln workload get-deployments N --gvc G (失敗したデプロイメント + 正確なエラー)、cpln logs '{gvc="G", workload="N"}' --org ORG stderr について、マニフェストを再読み込みします。修正、セーフティネット付きで再適用。READY 後、最大 1 つ のフォローアップ サニティチェック。

90 秒以上の待機については事前に期待値を設定: サーバーレス/標準初回デプロイ 30–90 秒 · ステートフル初回デプロイ 2–5 分 · force-redeployment 30–90 秒 · ボリュームセット拡張 30–60 秒 · 大規模イメージプッシュ (1GB+) 1–5 分 · コールドパス GVC + 初回ワークロード 1–3 分 · mk8s クラスター 10–30+ 分 (バックグラウンドまたはスキップ)。

ワークロードタイプ — 1 つを選択

必要	使用
アイドル時にゼロスケールすべき Web アプリ	serverless
常に実行、複数ポート、または非 HTTP である必要があるサービス	standard
スケジュール上のバックグラウンドジョブ	cron
永続ストレージが必要なデータベースまたはステートフルアプリ	stateful

オートスケーリング戦略

戦略	Serverless	Standard	Stateful	Cron
同時リクエスト	はい	いいえ	いいえ	いいえ
1 秒あたりのリクエスト	はい	はい	はい	いいえ
CPU 利用率	はい	はい	はい	いいえ
メモリ利用率	はい	はい	はい	いいえ
リクエスト レイテンシー	いいえ	はい	はい	いいえ
マルチメトリック (cpu/memory/rps)	いいえ	はい	はい	いいえ
KEDA (カスタムメトリック)	いいえ	はい	はい	いいえ

ゼロへのスケール は rps または concurrency を持つサーバーレスのみです。標準とステートフルはKEDA のみを通じてゼロにスケールできます。Cron はゼロにスケールできません。その他すべてのタイプは minScale ≥ 1 が必要です。

戦略	最適用途
同時リクエスト	リクエスト駆動型サービス、変動する並行性を持つ API
1 秒あたりのリクエスト	予測可能なパターンを持つ高スループット API
CPU 利用率	計算集約型ワークロード (画像処理、ML 推論)
メモリ利用率	メモリ集約型アプリケーション (キャッシュ、データ処理)
リクエスト レイテンシー	レイテンシー感応型サービス (リアルタイム、インタラクティブ)
KEDA	イベント駆動型スケーリング (キュー深度、外部メトリック)
無効	固定レプリカ数、手動でスケーリング

ワークロードリソース検証 — 知っておくべき制約

制約	ルール
CPU / メモリ最小値	25 ミリコア / 32 MiB
メモリ対 CPU 比	memory(MiB) / cpu(millicores) ≤ 8 (タグ cpln/relaxMemoryToCpuRatio で 32 に緩和)
port vs ports	同じコンテナ上で相互排他; ポート番号はすべてのコンテナで一意
ボリューム	最大 15、一意のパス、パスは別のパスの親になることはできません
target 上限	cpu/memory メトリクスで ≤ 100。KEDA では許可されません
metric/multi/target	metric と multi は相互排他。target は multi と相互排他
replicaDirect LB	ステートフルのみ

デフォルト: type=serverless、cpu=50m、memory=128Mi、autoscaling.target=95、minScale=1、maxScale=5、scaleToZeroDelay=300s、terminationGracePeriodSeconds=90、firewallConfig.internal.inboundAllowType=none。

完全な検証 (ステートフル最小/最大比、GPU 制約 — nvidia t4/a10g、コンテナ名予約、プローブ XOR ルール、ヘルスチェック タイミング範囲) については、/reference/workload/general を取得してください。

シークレット — タイプと参照構文

12 タイプ: opaque、dictionary、userpass、aws、gcp、azure-sdk、azure-connector、docker、ecr、tls、keypair、nats-account。cpln secret create は存在しません — create-opaque、create-aws など を使用してください。

環境変数 / ボリュームの参照構文:

タイプ	フォーム
opaque	cpln://secret/NAME.payload
dictionary	cpln://secret/NAME.KEY (1 env var/key、またはディレクトリとしてマウント)
userpass	cpln://secret/NAME.username / .password
tls	cpln://secret/NAME.cert / .key
keypair	cpln://secret/NAME.publicKey / .privateKey
aws	cpln://secret/NAME.accessKey / .secretKey / .roleArn
gcp	cpln://secret/NAME (通常はボリュームマウント — JSON ファイル)

注入方法: env var (cpln://secret/NAME...)、ボリュームマウント (大規模/マルチファイル/GCP JSON)、または GVC レベルのプルシークレット (spec.pullSecretLinks — docker、ecr、gcp タイプのみ)。

CLI 基礎

セットアップ

cpln login                                                  # インタラクティブ ブラウザ ログイン
cpln profile update default --org my-org --gvc my-gvc       # デフォルト org/GVC を設定

CI/CD の場合、プラットフォームのシークレット管理を通じて環境変数を設定します (--token は決して使用しません。ログにリークします):

変数	目的
CPLN_TOKEN	サービスアカウントキー (cpln serviceaccount add-key)
CPLN_ORG	デフォルト組織
CPLN_GVC	デフォルト GVC
CPLN_PROFILE	プロファイルオーバーライド

コマンドごとにオーバーライド: --org、--gvc、--profile。

検証ルール

cpln コマンドを記憶から記述しないでください。 cpln <command> --help または MCP cpln_suggest ツールで検証してください。コマンドがリソースコマンドマップにない場合は、存在しないと仮定してください。完全な規約: https://docs.controlplane.com/cli-conventions.md

コマンド構造

リソースコマンド: cpln <resource> <action> [REF] [--flags]。スタンドアロン コマンドはこのパターンを破ります: cpln apply、cpln delete、cpln logs、cpln port-forward、cpln cp、cpln convert、cpln login。

共有フラグ (ほぼすべてのコマンド)

• コンテキスト: --profile、--org、--gvc
• 出力: --output/-o (text、json、yaml、json-slim、yaml-slim、tf、crd、names)、--max (デフォルト 50)
• リクエスト: --token、--endpoint、--insecure/-k
• デバッグ: --verbose/-v、--debug/-d

ラウンドトリップの場合は常に -o yaml-slim / json-slim を使用してください。 プレーン yaml/json は サーバー側フィールド (status、id、created、lastModified、links) を含めます。これらは cpln apply を破ります。スリムバリアントはそれらをストリップします。

リソース コマンド マップ

リソース	スコープ	CRUD	非標準サブコマンド
workload	gvc	完全	connect、exec、run、cron (get/run/start/stop)、replica (get/stop)、force-redeployment、get-deployments、open、start、stop
gvc	org	完全	add-location、remove-location、delete-all-workloads
secret	org	汎用 create なし	12 タイプ固有の create コマンド、reveal
policy	org	完全	add-binding、remove-binding
identity	gvc	完全	—
volumeset	gvc	完全	expand、shrink、snapshot (create/delete/get/restore)、volume (delete/get)
domain	org	完全 (clone なし)	—
cloudaccount	org	汎用 create なし	create-aws、create-azure、create-gcp、create-ngs
image	org	create なし	build、copy、docker-login
agent	org	完全 (clone なし)	info、manifest、up
group	org	完全	add-member、remove-member
ipset	org	完全	add-location、remove-location、update-location
serviceaccount	org	完全 (update なし)	add-key、remove-key
mk8s	org	create なし	dashboard、join、kubeconfig
user	org	create なし	invite
org	—	delete なし (不変)	—
profile	local	get、delete、update	login、set-default、token
helm	gvc	get	install、upgrade、template、rollback、uninstall、list、history
stack	gvc	—	deploy、manifest、rm
location	org	部分的	install、uninstall
auditctx	org	完全 (delete なし)	—
quota	org	get、edit、patch	—

標準 CRUD 動詞

get (引数なし = すべてを一覧表示 — list サブコマンドはありません)、get REF、create --name NAME、delete REF...、edit REF、patch REF --file FILE、update REF --set PROP=VAL、clone REF --name NEW、audit [REF]、query、tag REF --tag K=V。また: access-report REF、eventlog REF、permissions。

存在しないコマンド

誤り	正解
cpln secret create	cpln secret create-opaque、create-aws など (12 タイプ固有バリアント)
cpln <resource> list	cpln <resource> get (引数なし = すべてを一覧表示)
cpln mk8s create	cpln apply --file mk8s-manifest.yaml
cpln logs --follow	cpln logs --tail (または -t または -f)
cpln workload log	cpln logs '{gvc="GVC", workload="WORKLOAD"}'
cpln cloudaccount create	cpln cloudaccount create-aws、create-azure、create-gcp、create-ngs
cpln apply (no --file)	cpln apply --file manifest.yaml
cpln workload update --identity X	cpln workload update REF --set spec.identityLink=//identity/X
cpln secret update --data '{}'	cpln secret edit REF または cpln apply --file ...
cpln gvc update --location LOC	cpln gvc update REF --set 'spec.staticPlacement.locationLinks+=//location/LOC'
cpln image push / cpln image pull	cpln image build --push (build+push) または docker push (after cpln image docker-login)
cpln image tag バージョンタグ用	Docker バージョンタグを直接 cpln image build --name NAME:TAG 経由で使用します。cpln image tag は存在しますが、メタデータ key=value タグを管理します (Docker バージョンタグではなく)。
cpln workload create --type stateful/cron	cpln apply --file workload.yaml — CLI フラグは serverless/standard create のみをサポート

高価値コマンド形式

リソースコマンドマップ + 標準 CRUD 動詞がほとんどのケースをカバーします。これらは記憶する価値のある構文に敏感なものです:

タスク	コマンド
バンドルの適用 / 削除	cpln apply --file ./manifests/ --gvc GVC --ready  ·  cpln delete --file manifest.yaml
ワークロード作成 (cron/stateful via apply、CLI フラグではなく)	cpln workload create --name APP --gvc GVC --image IMAGE --port PORT
Opaque シークレット作成	cpln secret create-opaque --name SECRET --file data.txt (stdin の場合は --file - を使用)
バインド権限	cpln policy add-binding POLICY --permission reveal --identity //gvc/GVC/identity/ID
ワークロードにアイデンティティを割り当て	cpln workload update WL --gvc GVC --set spec.identityLink=//identity/ID
ログを表示	cpln logs '{gvc="GVC", workload="WL"}' --org ORG --tail
コンテナで実行 (-- 区切り文字に注意)	cpln workload exec WL --gvc GVC -- COMMAND
ポート フォーワード	cpln port-forward WL 8080:8080 --gvc GVC
再適用用にエクスポート	cpln workload get WL --gvc GVC -o yaml-slim > wl.yaml
名前変更 (get/edit/apply よりも推奨)	cpln workload clone OLD --name NEW --gvc GVC
イメージをビルドしてプッシュ	cpln image build --name IMAGE:TAG --push
K8s マニフェストを変換	cpln convert --file k8s-manifest.yaml

マニフェスト パターン

リソース形式

すべてのリソースが spec を使用しません。トップレベルフィールドはタイプごとに異なります: workload/gvc/identity/volumeset は spec を使用します。secret は type + data を使用します。policy は targetKind + targetLinks + bindings を使用します。

kind: workload
name: my-app
spec:
  type: serverless
  containers:
    - name: main
      image: nginx:latest                              # 正確な ref、docker.io/ 接頭辞なし
      port: 80
      memory: 256Mi
      cpu: 250m
      env:
        - name: DB_PASSWORD
          value: cpln://secret/db-password.payload     # opaque → .payload
  defaultOptions:
    autoscaling: { minScale: 1, maxScale: 5, metric: rps, target: 100 }
  firewallConfig:
    external:
      inboundAllowCIDR: ["0.0.0.0/0"]
      outboundAllowCIDR: ["0.0.0.0/0"]
---
kind: secret
name: db-password
type: opaque
data: { encoding: plain, payload: my-secret-value }
---
kind: policy
name: secret-access
targetKind: secret                                     # 単数形、小文字
targetLinks: [//secret/db-password]
bindings:
  - permissions: [reveal]
    principalLinks: [//gvc/my-gvc/identity/my-app-identity]    # GVC スコープ プリンシパル リンク
---
kind: identity
name: my-app-identity

リソースごとの完全な検証ルール (ワークロード検証、GPU 制約、アイデンティティ XOR ルール、ドメイン DNS モード、ボリュームセット オートスケーリング) については、このスキルの終わりのリソース セクションの対応するリファレンス ページを取得してください。

マルチリソース適用 — 単一呼び出し、多くではなく

cpln apply は、ディレクトリまたはマルチドキュメント YAML が与えられると、リソース間依存関係グラフを歩みます。複数の apply 呼び出しに分割すると、apply が解決するために構築された順序付けの問題を再導入します (まだ適用されていないシークレットを参照するワークロードなど)。

• 単一 GVC バンドル (最も一般的): --gvc <gvc> を 1 回渡します。バンドル内のすべての GVC スコープリソースに GVC を入力しますね(インラインで宣言していない場合)。
• リソースごと GVC 宣言 (リソースが複数の GVC にまたがる、またはマニフェストが自己記述的である必要がある): 各 GVC スコープリソースの トップレベル gvc: フィールドを宣言します (kind/name と同じレベル)。--gvc なしで適用; 適用は各リソースを宣言された GVC にルーティングします。

Org スコープ リソース (secret、policy、domain、image、agent、group、cloudaccount、serviceaccount、ipset、mk8s) は gvc フィールド/フラグを無視します。単一リソース適用は初期マルチリソース デプロイではなく、1 つの既存リソースへのインクリメンタル更新用です。

ワークフロー

ワークロードにシークレット アクセスを許可

3 ステップ ルール (ガードレール #2) をコマンドとして:

# 1. シークレット (ファイルベース; stdin の場合は --file -)
cpln secret create-opaque --name db-password --file ./db-password.txt

# 2. アイデンティティ、ワークロードに割り当て
cpln identity create --name my-app-identity --gvc my-gvc
cpln workload update my-app --gvc my-gvc \
  --set spec.identityLink=//identity/my-app-identity

# 3. reveal でのポリシー、次にシークレット参照を挿入。
#    <container-name> を実際のコンテナで置き換えます (via -o yaml-slim で検索)。
#    Opaque は .payload を使用; dictionary は .KEY; userpass は .username/.password; tls .cert/.key。
cpln policy create --name secret-access --target-kind secret --resource db-password
cpln policy add-binding secret-access \
  --permission reveal \
  --identity //gvc/my-gvc/identity/my-app-identity
cpln workload update my-app --gvc my-gvc \
  --set spec.containers.<container-name>.env.DB_PASSWORD.value=cpln://secret/db-password.payload

バンドルの場合: 4 つすべてのリソースを 1 つのマルチドキュメント ファイルに入れて cpln apply --file bundle.yaml --gvc my-gvc --ready を実行します。Apply は依存関係を解決します。

GitOps with cpln apply

cpln gvc get my-gvc -o yaml-slim > manifests/gvc.yaml         # 常に yaml-slim
cpln workload get my-app --gvc my-gvc -o yaml-slim > manifests/workload.yaml
# 編集、コミット、次に CI:
cpln apply --file ./manifests/ --gvc my-gvc --ready           # 1 呼び出し; apply は順序を解決

失敗したワークロードをデバッグ

cpln workload get-deployments my-app --gvc my-gvc                  # 正確な障害理由
cpln logs '{gvc="my-gvc", workload="my-app"}' --org my-org --tail  # stderr/stdout
cpln workload exec my-app --gvc my-gvc -- env | grep CPLN          # 挿入された env をチェック
cpln workload connect my-app --gvc my-gvc                          # インタラクティブ シェル
cpln port-forward my-app 8080:8080 --gvc my-gvc                    # ローカル アクセス

Terraform / Pulumi / Kubernetes Operator デプロイメント パターンについては、関連するドキュメント ページを取得してください (このスキルの最後のリソースを参照)。

ネットワークと ロード バランサー

ファイアウォール デフォルト (ガードレール #4 に含まれる): 内部 none、外部インバウンドとアウトバウンド無効。ブロック > 許可; CIDR > ホスト名; ホスト名エグレス = ポート 80/443/445 のみ (outboundAllowPort でオーバーライド); ホスト名は *.example.com ワイルドカードをサポート。

エンドポイント:

• 内部 DNS (同じ GVC): WORKLOAD.GVC.cpln.local:PORT
• パブリック正規 (GVC endpointNamingFormat で設定):
  • org (新しい GVC のデフォルト): {workload}-{gvcAlias}.{orgEndpointPrefix}.cpln.app
  • default: {workload}-{gvcAlias}.cpln.app
  • legacy: レガシースキーム
• gvcAlias は自動生成され、GVC 名と異なる場合があります。正確な検索: cpln workload get WL --gvc GVC -o json | jq -r '.status.endpoint'。コンテナは CPLN_GLOBAL_ENDPOINT env var も受け取ります。
• ロケーション ID: aws-us-east-1、gcp-us-central1、azure-eastus
• 内部トラフィックは自動 mTLS です。すべてのワークロードは CPLN_TOKEN env var を取得します (自動ローテーション JWT、そのワークロードの内部からのみ有効)。
• Serverless Host ヘッダーはカスタムドメインではなく、正規エンドポイントです。 オリジナルは X-Forwarded-Host に含まれています。Standard/Stateful はカスタムドメインを Host として受け取ります。

ロード バランサー:

タイプ	スコープ	カスタムポート	静的 IP	ワークロード タイプ
デフォルト (共有)	すべてのワークロード	いいえ	いいえ	すべて
ダイレクト	ワークロードあたり	はい (TCP/UDP)	IP Sets 経由	すべて
専用 (GVC)	GVC あたり	はい	IP Sets 経由	すべて
レプリカ ダイレクト (spec.loadBalancer.replicaDirect)	レプリカあたり	構成可能	IP Sets 経由	ステートフルのみ

GVC 上の専用 LB (spec.loadBalancer.dedicated: true) はロック解除: 443/80 以外のドメインポート、ワイルドカード ホスト名、redirect.class.status5xx/status401 ルール、ドメイン上の tcp プロトコル。trustedProxies: 0 (ソース IP)、1 (最後の X-Forwarded-For)、2 (2 番目から最後の)。

ポリシー

リソースに対する権限をプリンシパルにバインドします。間違ったターゲットの種類、リンク形式、またはアクセス許可名はすべてサイレント失敗します。

• targetKind は単数形で小文字です。有効: account、agent、auditctx、cloudaccount、domain、group、gvc、identity、image、location、org、policy、quota、secret、serviceaccount、task、user、volumeset、workload。有効ではない (親経由で制御): ipset、mk8s、workloadreplica。
• ターゲット スコープ — 正確に 1 つを選択: target: all | targetLinks: [...] | targetQuery: {spec: {match, terms}}。
• スコープ別ターゲット リンク: org スコープ //KIND/NAME、GVC //gvc/NAME、GVC スコープ //gvc/GVC/KIND/NAME、ユーザー //user/EMAIL。
• プリンシパル リンク: ユーザー //user/EMAIL、サービスアカウント //serviceaccount/NAME、グループ //group/NAME、アイデンティティ //gvc/GVC/identity/NAME (決して //identity/NAME ではなく — サイレント無視)。
• ポリシーあたり最大 50 バインディング、バインディングあたり 200 プリンシパル リンク。各バインディングのアクセス許可はアルファベット順で一意である必要があります。ビルトイン ポリシー (origin: builtin) は変更または削除できません。

種ごとの完全な権限テーブル (および reveal、use、manage など実際に何を付与するか) については、cpln policy permissions、MCP mcp__cpln__get_permissions ツール、または /reference/policy を取得してください。

アイデンティティ

GVC スコープ。--set spec.identityLink=//identity/NAME 経由で割り当てます。ワークロードあたり 1 つのアイデンティティ。1 つのアイデンティティは同じ GVC 内のワークロード全体で共有できます。プロバイダーあたり 1 つのクラウド アカウント (1 AWS + 1 GCP + 1 Azure — 2 AWS ではなく)。アイデンティティは GVC 全体で共有できません — GVC ごとに再作成してください。

プロバイダー セクションにはそれぞれ XOR ルールがあります (例: AWS roleName ⊻ policyRefs; GCP serviceAccount ⊻ bindings)。ネットワーク リソース: IPs ⊻ FQDN。ネイティブ ネットワーク リソース: awsPrivateLink ⊻ gcpServiceConnect。各最大 50。完全な XOR ルールとプロバイダー固有のフィールドについては、/reference/identity を取得してください。

ドメイン

フィールド	ルール
dnsMode	cname または ns。Apex ドメインは cname を使用する必要があります — NS は apex をサポートしません。
certChallengeType	http01 または dns01。NS モードは dns01 を必須とします (http01 は拒否されます)。
gvcLink ⊻ workloadLink ⊻ ports.routes	相互排他。workloadLink (レプリカ-ダイレクト) はステートフルのみです。
acceptAllHosts ⊻ acceptAllSubdomains	相互排他。どちらも専用 LB が必要です。
ports[].protocol	http、http2 (デフォルト)、tcp (tcp は専用 LB が必須)。
ルート スコープ	ドメイン内のすべてのルートは、同じ GVC 内のワークロードをターゲットにする必要があります。

CNAME レコード → cpln.app。NS レコード → ns1.cpln.cloud、ns2.cpln.cloud、ns1.cpln.live、ns2.cpln.live。自動 TLS = Let's Encrypt、90 日有効、60 日ごとに自動更新。カスタム証明書は PEM コンテンツを含む keypair シークレット タイプを使用します。CORS、ヘッダー ワイルドカード、ルート制限、および完全なルート スキーマについては、/reference/domain を取得してください。

ボリューム セット

ステートフルのみ。cpln://volumeset/NAME で recoveryPolicy: retain (デフォルト) または recycle でマウント。

ファイルシステム	アクセス	バインディング	スナップショット / 縮小 / 削除 / 復元
ext4	RWO	1 ステートフル ワークロード	はい
xfs	RWO	1 ステートフル ワークロード	はい
shared	RWX	任意の数のワークロード	いいえ

パフォーマンス クラス: general-purpose-ssd (最小 10 GB)、high-throughput-ssd (最小 200 GB)、shared (fileSystemType: shared の場合は自動設定)。すべてに対して最大容量 65,536 GB。

• fileSystemType と performanceClass の両方は不変です。 どちらかを変更 = 削除 + 再作成 (データロス — ガードレール #6)。
• shrinkVolume データを破棄します。ボリュームは 6 時間ごとに 1 回だけ拡張できます。
• createFinalSnapshot: true (デフォルト) はボリューム削除前に自動スナップショット — オンのままにします。

オートスケーリング、予測スケーリング、shared 上のマウント オプション、および AWS KMS カスタム暗号化については、/reference/volumeset を取得してください。

境界 — Console のみの操作

CLI / API / Terraform はほぼすべてを処理します (リソース