VMware VKS

VMware VKS

作成者: Wei Zhou、VMware by Broadcom — [email protected] これはVMwareのエンジニアによるコミュニティ主導のプロジェクトであり、VMwareの公式製品ではありません。 VMwareの公式開発者ツールについては、developer.broadcom.comをご覧ください。

英語 | 中国語

VMware vSphere Kubernetes Service（VKS）の管理に対応するMCPスキルとCLIです。Supervisorクラスタ、vSphere Namespaces、VKS Clusterのライフサイクルを管理します。MCPツールは24個です。

3.0へのアップグレード

3.0では、2つのkubeconfigツールの名前が変更されました。get_supervisor_kubeconfig → issue_supervisor_kubeconfig、 get_tkc_kubeconfig → issue_tkc_kubeconfigです。これらのツールは何かを読み取るのではなく、認証情報（Supervisorベアラートークン）を発行します。get_という名前では、エージェントに誤解を与えていました。パラメーター、アノテーション、安全性、CLIコマンド （vmware-vks kubeconfig supervisor / kubeconfig get）に変更はありません。旧名を呼び出している場合は、新しい名前に切り替えてください（保存済みのvmware-pilotワークフローは、Pilot ≥ 2.0.0で変換されます）。~/.vmware/rules.yamlに旧名を指定している拒否ルールは、vmware-policy ≥ 1.19.0で引き続き機能します。詳細は RELEASE_NOTES.mdをご覧ください。

2.0へのアップグレード

2.0では、VM Serviceツール3つの名前が変更されました。list_vm_snapshots → list_vm_service_snapshots、list_vm_groups → list_vm_service_groups、list_vm_network_interfaces → list_vm_service_network_interfacesです。名前が衝突するためです。このファミリーの2.0では、vmware-aiopsとvmware-monitorがvSphere VMのスナップショットツールをlist_vm_snapshotsと呼ぶ一方、これらのツールはKubernetes VM Service（vm-operator）オブジェクトを一覧表示します。注意： vmware-aiopsまたはvmware-monitorも読み込まれている状態で、エージェントのプロンプト、スクリプト、保存済みワークフローが引き続きlist_vm_snapshotsを呼び出すと、ここではなくvSphereツールが実行されます。更新してください。list_vm_snapshotsを指定したVKSスコープの拒否ルールは、aiops/monitorツールにも一致するようになりました（vmware-policy ≥ 1.18では両方の名前に一致します。該当するルールはvmware-audit policyで一覧表示できます）。パラメーター、安全性のゲート、CLIコマンドに変更はありません。全一覧はRELEASE_NOTES.mdをご覧ください。2.0より前のバージョンを同じrules.yamlと共有している場合は、そちらにもvmware-policy ≥ 1.18.2を使用してください。各ルールを旧名と新名の両方に照合するため、1つのファイルで両方に対応できます。

関連スキル

VMware MCP Skillsファミリーの一部です。 各スキルは異なる分野を担当します。必要なものだけをインストールしてください。

前提条件

• Python 3.10+ — uv tool installに必要です
• vSphere 8.0+ — Workload Management（Supervisor）APIにはvSphere 8.xが必要です
• Workload Managementが有効であること — 少なくとも1つのコンピュートクラスタでWCPを有効にする必要があります
• ライセンス — vSphere Kubernetes Service（Enterprise PlusまたはVMware Cloud Foundation）

セットアップ後にvmware-vks checkを実行し、すべての要件が満たされていることを確認してください。

クイックスタート

# Install
uv tool install vmware-vks

# Configure
mkdir -p ~/.vmware-vks
cp config.example.yaml ~/.vmware-vks/config.yaml
# Edit config.yaml with your vCenter host and username

# One password env var per target, named after the target in config.yaml:
# target "vcenter01" (the one config.example.yaml ships) -> VMWARE_VKS_VCENTER01_PASSWORD
echo "VMWARE_VKS_VCENTER01_PASSWORD=your_password" > ~/.vmware-vks/.env
chmod 600 ~/.vmware-vks/.env

# Verify
vmware-vks check

# Common operations
vmware-vks supervisor status domain-c1
vmware-vks namespace list
vmware-vks tkc list
vmware-vks tkc create my-cluster -n dev --version v1.28.4+vmware.1 --vm-class best-effort-large
vmware-vks tkc create my-cluster -n dev --apply

オフライン／エアギャップ環境へのインストール（ソースから）

このプロジェクトでは最新の PEP 517 ビルドシステム（hatchling）を使用しているため、設計上 setup.py はありません。これは想定どおりであり、ファイルが欠落しているわけではありません。ソースをクローンして、ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build というエラーが発生した場合は、pip のバージョンが 21.3 より古く、setuptools 以外のバックエンドでは 編集可能な（-e）インストールを実行できません。編集可能モードは開発者向けの利便機能であり、ツールの実行には必要ありません。次のいずれかを行ってください。

# From the source tree — a normal (non-editable) install builds a wheel:
pip install .              # NOT  pip install -e .

# ...or upgrade pip first, and editable works too:
pip install --upgrade pip && pip install -e .

完全なエアギャップ環境のホストでは、ネットワークに接続されたマシンで wheel をビルドしてコピーしてください。そうすれば、対象ホストでネットワークは不要です。

# On a connected machine, collect this package + its dependencies as wheels:
pip wheel . -w dist        # → dist/*.whl   (or: uv build, for just this package)

# Copy dist/ to the air-gapped host, then install offline:
pip install --no-index --find-links dist vmware-vks

よくあるワークフロー

新しい TKC クラスターをデプロイする

1. 互換性を確認します → vmware-vks check
2. 利用可能な K8s バージョンを一覧表示します → vmware-vks tkc versions -n dev
3. 名前空間を作成します（必要な場合）→ vmware-vks namespace create dev --cluster domain-c1 --storage-policy <policy-id> --cpu 16000 --memory 32768 --apply（ポリシー ID は vmware-vks supervisor storage-policies で取得します）
4. TKC クラスターを作成します → vmware-vks tkc create dev-cluster -n dev --version v1.28.4+vmware.1 --control-plane 1 --workers 3 --vm-class best-effort-large --apply
5. kubeconfig を取得します（認証情報。クラスターへのアクセスが必要な場合のみ）→ vmware-vks kubeconfig get dev-cluster -n dev -o ./kubeconfig — トークンを表示する代わりに、所有者のみがアクセスできるファイルに書き込みます

負荷テストに向けてワーカーノードをスケールする

1. 現在の状態を確認します → vmware-vks tkc get dev-cluster -n dev
2. スケールアップします → vmware-vks tkc scale dev-cluster -n dev --workers 6
3. 進行状況を監視します → vmware-vks tkc get dev-cluster -n dev（フェーズを確認）
4. テスト後にスケールダウンします

名前空間のリソース管理

1. 名前空間を一覧表示します → vmware-vks namespace list
2. 使用状況を確認します → vmware-vks storage -n dev
3. クォータを更新します → vmware-vks namespace update dev --cpu 32000 --memory 65536

ツールリファレンス（24 個のツール）

Supervisor

Namespace

TKC

Access

VM サービス（vm-operator）

権限

アーキテクチャ

User (Natural Language)
  ↓
AI Agent (Claude Code / Goose / Cursor)
  ↓ reads SKILL.md
  ↓
vmware-vks CLI  ─── or ───  vmware-vks MCP Server (stdio)
  │
  ├─ Layer 1: pyVmomi (/sdk) + vSphere Automation REST (/api)
  │   Supervisor status, storage policies, Namespace CRUD, VM classes, Harbor
  │   Two session stores: the SOAP session from SmartConnect, and a separate
  │     REST session id from POST /api/session (vmware-api-session-id header)
  │
  └─ Layer 2: kubernetes client → Supervisor K8s API endpoint
      TKC CR apply / get / delete  (cluster.x-k8s.io API version auto-detected:
        prefers v1 when Supervisor serves it, falls back to v1beta1 for vSphere 8.0)
      Kubeconfig built in-memory from the POST /wcp/login bearer token
        (a third credential, and no temp file on disk)
  ↓
vCenter Server 8.x+ (Workload Management enabled)
  ↓
Supervisor Cluster → vSphere Namespaces → TanzuKubernetesCluster

CLI リファレンス

# Pre-flight diagnostics
vmware-vks check

# Supervisor
vmware-vks supervisor status <cluster-id>
vmware-vks supervisor storage-policies

# Namespace
vmware-vks namespace list
vmware-vks namespace get <name>
vmware-vks namespace create <name> --cluster <id> --storage-policy <policy>
vmware-vks namespace create <name> --cluster <id> --storage-policy <policy> --apply
vmware-vks namespace update <name> [--cpu <mhz>] [--memory <mib>]
vmware-vks namespace delete <name>
vmware-vks namespace vm-classes

# VKS Cluster
vmware-vks tkc list [-n <namespace>]
vmware-vks tkc get <name> -n <namespace>
vmware-vks tkc versions -n <namespace>
vmware-vks tkc create <name> -n <namespace> [--version <v>] [--vm-class <c>]
vmware-vks tkc create <name> -n <namespace> --apply
vmware-vks tkc scale <name> -n <namespace> --workers <n>
vmware-vks tkc upgrade <name> -n <namespace> --version <v>
vmware-vks tkc delete <name> -n <namespace>

# Kubeconfig
vmware-vks kubeconfig supervisor -n <namespace> [-o <path>]
vmware-vks kubeconfig get <cluster-name> -n <namespace> [-o <path>]

# Harbor & Storage
vmware-vks harbor
vmware-vks storage -n <namespace>

MCP サーバー

uv tool install vmware-vks の実行後、1 つのコマンドで MCP サーバーを起動できます（v1.5.15 以降）：

# Recommended — single command, no network re-resolve
vmware-vks mcp

# With a custom config path
VMWARE_VKS_CONFIG=/path/to/config.yaml vmware-vks mcp

エージェントの設定

AI エージェントの MCP 設定に追加します：

{
  "mcpServers": {
    "vmware-vks": {
      "command": "vmware-vks",
      "args": ["mcp"],
      "env": {
        "VMWARE_VKS_CONFIG": "~/.vmware-vks/config.yaml"
      }
    }
  }
}

# Run without installing (requires PyPI access each launch)
uvx --from vmware-vks vmware-vks mcp

# Legacy entry point (still works, kept for backward compatibility)
vmware-vks-mcp

安全性

トラブルシューティング

「VKS not compatible」エラー

vCenter で Workload Management を有効にする必要があります。確認するには、vCenter UI -> Workload Management に移動してください。vSphere 8.x 以降と Enterprise Plus または VCF ライセンスが必要です。

すべてのコマンドが「session is not authenticated」で失敗する

パスワードは正しいものです。セッションの期限が切れている（コマンドを再実行すると、新しいセッションが開かれます）か、アカウントに vSphere ロールがないため、vCenter にセッションが表示されず、すべての呼び出しが失敗しています。VKS は接続時にこのようなログインを拒否しません。Supervisor Namespace の権限だけを持つアカウントも同じ状態に見え、正常に動作する場合があるためです。ロールが必要な最初の呼び出しでエラーが発生します。Administration > Access Control > Global Permissions で、vCenter のルートフォルダーにアカウントのロール（Read-Only 以上）を割り当ててください。Namespace および TKC を操作するには、Workload Management 権限も必要です。

すべての REST ツールが 401 を返す

名前空間、ストレージポリシー、Supervisor ステータスのツールは、POST /api/session で取得したセッション ID を使って vSphere Automation REST API に認証します。pyVmomi の SOAP セッションキーではありません。この API はそのキーを発行しておらず、常に拒否します。401 は自動的に一度再試行されます。それでも解決しない場合は、あなたと vCenter の間にあるプロキシが vmware-api-session-id ヘッダーを削除していないか確認してください。Workload Management の権限が不足しているアカウントで返されるのは 401 ではなく、403 です。

名前空間の作成時に「storage policy not found」と表示される

まずポリシーを一覧表示します：vmware-vks supervisor storage-policies。次に、--storage-policy には表示名ではなく、Policy ID 列の値を渡します。

TKC クラスターが「Creating」フェーズで停止する

vCenter の Supervisor イベントを確認してください。よくある原因は、ESXi ホストのリソース不足、NSX-T のネットワーク問題、またはターゲットデータストアでストレージポリシーを利用できないことです。

Kubeconfig の取得に失敗する

Supervisor API エンドポイントに vmware-vks の実行マシンから接続できる必要があります。ポート 6443 のファイアウォールルールを確認してください。

スケール操作の効果がない

スケールする前に、クラスターが「Running」フェーズであることを確認してください。「Creating」または「Updating」フェーズのクラスターでは、スケール操作が拒否されます。

名前空間の削除が予期せず拒否される

名前空間内に TKC クラスターがある場合、名前空間の削除ガードによって削除が阻止されます。まず名前空間内の TKC クラスターをすべて削除してから、もう一度試してください。

バージョン互換性

Broadcom 公式リファレンス

• SDK：https://developer.broadcom.com/sdks — VCF Python SDK（VCF 9+ の統合 SDK）
• REST API：https://developer.broadcom.com/xapis — vSphere Automation API（Workload Management エンドポイント）
• CLI ツール：https://developer.broadcom.com/tools — kubectl-vsphere、PowerCLI 9.1

関連プロジェクト

リモートアクセス（HTTPS）とツールの制限

デフォルトでは、vmware-vks mcp は stdio で 1 つのローカルクライアントと通信し、すべてのツールを提供します。次の 2 つのオプションで動作を変更できます （vmware-policy ≥ 1.21.0）。

HTTPS 経由で提供すると、ほかのマシン上のクライアントも接続できます。呼び出し元はすべてベアラートークンが必要です。

vmware-audit token create alice          # prints the token once; give it to alice
vmware-audit token list                  # names only
vmware-audit token revoke alice          # refused from its next request, no restart
vmware-vks mcp --transport https --host 0.0.0.0 --port 8443 \
    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
    --public-name mcp.example.com

クライアントを接続します（Claude Code の例です。ストリーム可能な HTTP とカスタムヘッダーに対応する MCP クライアントであれば使用できます）。

claude mcp add --transport http vmware-vks https://mcp.example.com:8443/mcp \
    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"

{
  "mcpServers": {
    "vmware-vks": {
      "type": "http",
      "url": "https://mcp.example.com:8443/mcp",
      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
    }
  }
}

• トークンがないとサーバーは起動せず、--public-name 以外の Host/Origin 値を拒否します。また、バインド前に未認証のリクエストが 401 を返すことを確認します。クライアントがこれらの名前を信頼できる証明書を使用してください。
• 同じマシン上の TLS 終端リバースプロキシの背後では、--transport http --host 127.0.0.1 --public-name mcp.example.com を使用し、Authorization ヘッダーを転送してください。
• 別のマシン上のロードバランサーまたはゲートウェイの背後では、--transport https を維持してください（自己署名証明書でもかまいません）。ロードバランサーが Host として送信するホスト名を --public-name に指定し、Authorization を転送するようにしてください。 ヘルスプローブには、トークン不要で {"status": "ok"} のみを返す GET /healthz を使用できます （vmware-policy ≥ 1.23.0）。
• 各リクエストに traceparent または X-Request-ID を付けると、監査ログの行に保存されます。 vmware-audit log --correlation-id ID を使うと、1 つのプラットフォームリクエストに関連する呼び出しを検索できます。
• このサーバー上のファイルを読み書きするツール（ここでは issue_*_kubeconfig(output_path)）は、サーバーの設定、トークン、監査ログ、TLS キーには決して触れません。また、ネットワーク経由では VMWARE_MCP_FILE_ROOT にツール用のディレクトリを指定しない限り無効です （vmware-policy ≥ 1.23.1）。
• 監査ログでは、呼び出し元はそれぞれ token:<name> として記録されます。呼び出しは同時に実行され、同じターゲットへの呼び出しも並行します。サーバーはターゲットごとに最大 VMWARE_MCP_POOL_SIZE（デフォルトは 2）個のセッションを保持します。各セッションはそのターゲットへのログインであり、空きセッションができるまでの待機時間は最大 300 s です（vmware-policy ≥ 1.22.0）。
• エンドポイントにアクセスできるすべてのユーザーは、このサーバーのアカウントで操作します。 トークンは呼び出し元を識別しますが、プラットフォーム上の権限は付与しません。権限レベルごとにエンドポイントを 1 つ実行してください。vmware-vks access-info で、そのアカウントと実行可能な操作を確認できます。
• 1 つのエンドポイントで複数のユーザーまたはロールを使用する場合： vmware-audit roles enable を 1 回実行し、各トークンにロールを割り当てます（vmware-audit token create NAME --role reader、またはツールとターゲットを指定した roles.yaml 内のロールを使用します。vmware-policy ≥ 1.24.0）。ロールは、このエンドポイントでトークンが呼び出せるものを制限します。アカウントが持つ権限を超える権限は付与できません。vmware-policy の README の「Roles for network callers」を参照してください。

読み取りツールと、選択した書き込みツールのみを提供する：

vmware-vks mcp --expose read --allow-write create_namespace
# or: VMWARE_VKS_MCP_EXPOSE=read VMWARE_VKS_MCP_ALLOW_WRITE=create_namespace vmware-vks mcp

提供しないツールは、クライアントのツール一覧に表示されません。不正な値または不明な書き込みツールを指定すると、サーバーは停止します（終了コード 2）。これはクライアントに提供するツールを制限するものであり、認可ではありません。そのため、アカウント自体にも最小権限を適用してください。

詳細については、skills/vmware-vks/references/setup-guide.md（「Serving MCP over HTTPS」、「Limiting which tools are offered」）を参照してください。

ライセンス

MIT