<!-- Token Budget: - Level 1 (YAML): ~120 tokens - Level 2 (this file): ~1900 tokens (target <2000) - Level 3 (prompts/, reference/, examples/): loaded on demand -->

NVCF 自己ホスト型 CLI

nvcf-cli は自己ホスト型 NVIDIA Cloud Functions の立ち上げの全段階を実行します: クラスタ登録、コントロールプレーン インストール、コンピュートプレーン インストール、関数のデプロイ/呼び出し、ライフサイクル管理。ユーザーが自己ホスト型 NVCF を運用したいときは、このスキルを使用します。

使用時期

• 「自己ホスト型 NVCF をインストール」 / 「NVCF クラスタを起動」
• 「(コンピュート|GPU) クラスタを NVCF に登録」
• 「(コンテナ|GPU) 関数をデプロイ」 / 「NVCF 関数を呼び出し」
• 「NVCF クラスタの健全性を確認」 / 「NVCF インストールは正常か」
• 「NVCF クラスタ JWKS をローテーション」 / 「NVCA エージェントが認証されなくなった」
• 「NVCF を破棄」 / 「コンピュートプレーンを削除」 / 「NVCF をアンインストール」 / 「このクラスタを登録解除」
• 「down の実行内容をプレビュー」 / 「ドライラン アンインストール」
• NVCFBackend、NVCA、ICMS、helm-nvcf-* のような helm リリース、または icms.<domain> / api.<domain> の URL への参照

クイックスタート

リモートワンクリック インストールの場合、self-hosted up を実行する前に Gateway API イングレスと CLI エンドポイント設定を準備します。このコマンドはコントロールプレーンを適用した後、即座に API、API キー、呼び出し、gRPC エンドポイントを呼び出します。Gateway がプログラムされていないか、CLI ホストヘッダがスタック環境によってレンダリングされた HTTPRoute と一致しない場合、インストール後のヘルスチェックとクラスタ登録は失敗します。

# シングルクラスタ(現在の kubeconfig コンテキスト上のコントロール + コンピュート):
nvcf-cli self-hosted up --cluster-name=ncp-local

# スプリットクラスタ(コントロールプレーンはコンテキスト A、コンピュートプレーンはコンテキスト B):
KUBECONFIG=cp.yaml:gpu1.yaml nvcf-cli self-hosted up \
  --cluster-name=ncp-local \
  --control-plane-context=admin@cp \
  --compute-plane-context=admin@gpu1 \
  --icms-url=https://icms.nvcf.example.com

# 既存のコントロールプレーンに新しいコンピュートプレーンを追加(CP への kubectl アクセス不要;
# 公開 ICMS HTTPRoute 経由でコントロールプレーンに接続):
nvcf-cli self-hosted add-compute-plane \
  --cluster-name=ncp-local-2 \
  --compute-plane-context=admin@gpu2 \
  --icms-url=https://icms.nvcf.example.com \
  --token=$ADMIN_JWT

# 破棄(常に先に plan-only を実行):
nvcf-cli self-hosted down --plan-only --cluster-name=ncp-local --json | jq
nvcf-cli self-hosted down --cluster-name=ncp-local

# プレーン単位のアンインストール(GitOps; インストールと同様):
nvcf-cli self-hosted uninstall --no-apply --compute-plane --cluster-name=ncp-local | kubectl delete -f -

up vs add-compute-plane。 up は常に両方のプレーンをインストールします — 最初の インストールに使用します。add-compute-plane は、コントロールプレーンが既に実行されており、N 番目のコンピュート クラスタをアタッチしたい場合に正しいサブコマンドです。

down は常に先に --plan-only で実行。 willUninstall.commands[] 配列をユーザーに表示した後、実際に実行します。

コアサブコマンド

サブコマンド	機能	使用時期
nvcf-cli self-hosted check --pre [--local-only | --control-plane-context=X | --compute-plane-context=Y]	プリフライト: ローカルホスト ツール + クラスタ側の前提条件	新しい環境では常に最初に実行
nvcf-cli self-hosted install --control-plane | kubectl apply -f -	コントロールプレーンのレンダリング + 適用	適用の手動制御が必要な場合(GitOps フレンドリー)
nvcf-cli self-hosted install --compute-plane --cluster-name=X | kubectl apply -f -	クラスタ登録 + コンピュートプレーンのレンダリング	同様 — 手動適用パス
nvcf-cli self-hosted up --cluster-name=X	ワンショット最初のインストール: プリフライト → コントロールプレーン → 登録 → コンピュートプレーン	標準インストール パス(両方のプレーンをゼロから)
nvcf-cli self-hosted up --plan-only --cluster-name=X	ドライラン: フェーズごとのプラン + ETA を出力(状態変更なし)	エージェント / CI プレビュー(コミット前)
nvcf-cli self-hosted add-compute-plane --cluster-name=X --compute-plane-context=Y --icms-url=… --token=$JWT	既存の コントロールプレーンに新しいコンピュートプレーンを追加(CP インストールなし)	初期 up 後、2 番目、3 番目、... の GPU クラスタを追加
nvcf-cli self-hosted uninstall --control-plane	プレーン単位のプリミティブ: コントロールプレーンで helmfile destroy を実行(登録済みコンピュートプレーンがある場合は拒否)	すべてのコンピュートプレーンが削除された後の最終破棄、またはスクリプト化されたパイプライン
nvcf-cli self-hosted uninstall --compute-plane --cluster-name=X	プレーン単位のプリミティブ: コンピュートプレーンで helmfile destroy を実行(ICMS 登録解除、ドレーンなし)	ICMS 側のクリーンアップなしで helm リリースを削除
nvcf-cli self-hosted uninstall --no-apply <plane>	helm get manifest 経由で delete YAML をレンダリング	GitOps; | kubectl delete -f - またはコミット + Argo で適用
nvcf-cli self-hosted down --cluster-name=X	オーケストレーター: ドレーン → uninstall --compute-plane → ICMS でのクラスタ削除	標準「1 つの GPU クラスタを削除」パス
nvcf-cli self-hosted down --all --confirm	オーケストレーター: 登録済みのすべてのコンピュートプレーン + コントロールプレーンを破棄	完全なアンインストール
nvcf-cli self-hosted down --plan-only --cluster-name=X	ドライラン プレビュー(フェーズ + helm リリース + ICMS 行 + ETA; helm/helmfile コンタクトなし)	実際の down を実行する前に常に実行
nvcf-cli self-hosted status [--cluster-name=X] [--watch] [--json]	クラスタ識別 + コンポーネント健全性 + 最近のイベントのスナップショット ダッシュボード	日常のヘルスチェック; --watch でライブ表示
nvcf-cli init	API キー サービス経由で公開 api ゲートウェイから管理トークンを生成	クラスタ管理操作の前; べき等
nvcf-cli cluster register --name=X --nca-id=Y --region=Z [--ignore-existing]	クラスタ JWKS+OIDC issuer を ICMS に登録	スタンドアロン登録(コンピュートプレーン インストールなし)
nvcf-cli cluster rotate --cluster-id=ID	ICMS でクラスタ JWKS をローテーション	NVCA の K8s 署名キーが変更され、PSAT 検証が 401 を返し始めたとき
nvcf-cli cluster delete --cluster-id=ID	ICMS からクラスタ登録を削除	ユーザーに確認。 クラスタの ICMS 状態を破棄します。
nvcf-cli api-key generate --description="…" --expires-in=1h	invoke_function スコープで API キーを生成	関数を呼び出す前; 管理トークンはデフォルトではこのスコープを持ちません
nvcf-cli function create --input-file=<json>	ICMS で関数メタデータを作成	関数デプロイの最初のステップ
nvcf-cli function deploy create --input-file=<json>	作成された関数のデプロイメントをスケジュール	ACTIVE になるまで待機(タイムアウト 900 秒)
nvcf-cli function invoke --input-file=<json>	デプロイされた関数を呼び出し	API キー(管理トークンではなく)が必要
nvcf-cli function delete --function-id=ID --version-id=VID	関数とそのデプロイメントを削除	ユーザーに確認。

一般的なワークフロー

ステップバイステップのプレイブックについては、ユーザーの意図に一致するプロンプトをロードします:

• ゼロからインストール。 prompts/install-from-scratch.md — k3d クラスタ → プリフライト → up → スモーク関数をデプロイ。
• 新しいコンピュートプレーンを追加。 prompts/add-compute-plane.md — 既存のコントロールプレーンに対するスプリットクラスタ up。
• 関数をデプロイして呼び出し。 prompts/deploy-and-invoke.md — create → deploy → API key → invoke。
• インストール失敗を診断。 prompts/diagnose-failed-install.md — status --json → 失敗コンポーネントを特定 → kubectl describe → 改善措置。
• JWKS をローテーション。 prompts/rotate-cluster-jwks.md — PSAT 認証が失敗し始めたときに実施。
• 破棄。 prompts/teardown.md — 最初に down --plan-only を実行、次に実際に実行。down --cluster-name=X で 1 つのコンピュートプレーン(オーケストレーター: ドレーン + アンインストール + クラスタ削除); uninstall --control-plane でコントロールプレーン(プレーン単位プリミティブ); down --all --confirm ですべて; uninstall --no-apply <plane> | kubectl delete -f - で GitOps。

リファレンス

• reference/commands.md — 完全なサブコマンド チートシート
• reference/flags.md — グローバル + コマンド単位のフラグ
• reference/exit-codes.md — 各ゼロ以外の終了コードの意味
• reference/troubleshooting.md — 既知エラー → 改善措置テーブル

セーフティ ルール — 重要

これらをユーザーの明示的な確認なしで実行しないでください:

• nvcf-cli self-hosted down または uninstall のいかなる形式 — 破壊的です。常に最初に --plan-only (down) または --no-apply (uninstall) で実行 し、ユーザーに何が起こるか表示します。どのコンピュートプレーンが削除されるか、また永続的な状態がワイプされるかどうかを明記します。
• nvcf-cli self-hosted down --remove-persistent (または uninstall --remove-persistent) — Cassandra 行、OpenBao シール キー、sr-default ユーザー データを削除します。損失は復旧不可能です。 これがユーザーが望むことであることを明示的に確認します。
• nvcf-cli self-hosted uninstall --control-plane --force-with-registered-clusters — すべての登録済みコンピュートプレーンをオーファン化します(PSAT 認証は即座に破損)。このフラグを渡す前に結果を明記します。
• nvcf-cli self-hosted down --all — すべてを破棄します。常にクラスタ リストを表示(nvcf-cli cluster list)し、確認を取得します。
• nvcf-cli cluster delete — クラスタの ICMS 登録を削除します; コンピュートプレーンは即座に認証できなくなります。
• nvcf-cli function delete — 関数と任意のアクティブなデプロイメントを削除します。
• 任意の生の helm uninstall または kubectl delete pvc/pv — 永続的な状態に影響します。nvcf-cli self-hosted down(オーケストレーター)または uninstall(プレーン単位)を推奨します。これらは安全に処理します。
• 任意の --force フラグ(--force-with-registered-clusters、非対話型コンテキストでの --confirm)。

常にこれらを実行してください:

• クラスタが存在する/健全であると仮定する前に nvcf-cli self-hosted status を実行します。
• 作成前に計画されたアクション(クラスタ名、関数名、GPU タイプ、既知のコスト)を表示します。
• 削除前に正確なリソース名を確認します — cluster list / function list の出力と照合します。
• CI / 非対話型コンテキストでは、--non-interactive --token=$JWT を使用します。$CI が設定されている場合、対話型 nvcf-cli init を提案しないでください。

チャット/ログ/フィードバックにこれらを貼り付けないでください:

• 管理トークン(完全な JWT)。参照する必要がある場合は最初の 8 文字 + ... を表示します。
• API キー(nvapi-…)。
• ~/.nvcf-cli.state またはいかなる kubeconfig の内容。
• helmfile 値でシークレットとしてマークされたデータ。

出力モード(エージェント パイピング用)

長時間実行する nvcf-cli サブコマンド(up、status、check)は 4 つの出力モードを受け入れます:

• --json — stderr 上の JSONL イベント; 行ごとに 1 イベント; 安定したスキーマ(schemaVersion: 2)。エージェント下で実行する場合はこれを使用。 jq -c . または json.loads() で行ごとにパース。
• --plain — 平文のタイムスタンプ付き行、RFC3339 UTC、[NN/8] フェーズ プレフィックス; grep フレンドリー。非 TTY ではデフォルト。
• --accessible — スピナーなしの平文出力、詳細な状態マーカー([completed]、[running]、[pending]、[failed])付き。スクリーンリーダーと制限されたターミナル用。
• (フラグなし) — Bubbletea TTY ダッシュボード。TTY ≥100×30 ではデフォルト。エージェント下では使用しないでください(カーソルアップ シーケンスはノイズになります)。

自動検出は、stdout/stderr がどのような場合でも適切なモードを選択します。CLI は NO_COLOR(任意の値 → 平文を強制)、TERM=dumb(平文を強制)、CI=truthy(疑似 TTY でも平文を強制)も尊重します。ターミナルが 100×30 より小さい場合、bubbletea レンダラーはコンパクト レイアウトにフォールバックします。明示的な --json はエージェント パイピングに最適です。

失敗時

nvcf-cli の失敗は JSON で構造化された phase_failed イベントを出力します:

{"event":"phase_failed","phaseNum":4,"phase":"apply-cp",
 "errCategory":"helm_apply","errMessage":"helm install api-keys: timed out",
 "retryClass":"backoff","retryAfterSec":60,
 "remediation":["kubectl describe pod -n cassandra-system cassandra-0",
                "Re-run with --debug for verbose helmfile output"],
 "raw":{"subprocess":"helmfile","exitCode":1,"stderrTail":"…","kubernetesReason":"FailedScheduling"}}

retryClass フィールドはエージェントに失敗の処理方法を伝えます:

retryClass	意味	エージェント アクション
immediate	一時的な障害	同じ up コマンドを今すぐ再試行
backoff	レート制限 / ペンディング操作	retryAfterSec 秒待機、次に再試行
after_remediation	オペレーターの介入が必要	errMessage + remediation を表示、停止。自動再試行しません。
none	非再試行可能	after_remediation と同じ — 表示して停止
unknown	分類子が不確実	保守的に扱う: 表示して停止

--force で再実行しないでください(どのコマンドもそれを受け入れません)。raw ブロックは基盤となるシグナル(サブプロセス終了、HTTP ステータス、K8s 理由)を格納します — ユーザーに失敗を説明する際に関連フィールドを引用しますが、シークレットをスキャンせずにチャットに stderrTail をダンプしないでください。

クイック コマンド リファレンス

nvcf-cli self-hosted check --pre              # プリフライト
nvcf-cli self-hosted up --cluster-name=NAME   # ワンショット インストール
nvcf-cli self-hosted status                   # スナップショット
nvcf-cli self-hosted status --watch           # ライブ表示
nvcf-cli init                                 # 管理トークンを生成
nvcf-cli cluster register …                   # クラスタを登録
nvcf-cli api-key generate --description=…     # 呼び出し用 API キーを生成
nvcf-cli function create --input-file=…       # 関数を作成
nvcf-cli function deploy create --input-file=…
nvcf-cli function invoke --input-file=…

フィードバック

ユーザーがバグまたは制限事項に遭遇した場合、プロジェクト トラッカーを通じてイシューを提出します。シークレットは含めません。