VMware VKS

VMware VKS

For a read-only check of this skill with your model and agent host, use the shared model-fit self-test in the marketplace root.

Author: Wei Zhou, VMware by Broadcom — wei-wz.zhou@broadcom.com

This is a community-driven project by a VMware engineer, not an official VMware product.

For official VMware developer tools see developer.broadcom.com.

English | 中文

MCP Skill + CLI for VMware vSphere Kubernetes Service (VKS) management — Supervisor clusters, vSphere Namespaces, and VKS Cluster lifecycle. 25 MCP tools.

Upgrading to 3.0

3.0 renames the two kubeconfig tools: get_supervisor_kubeconfig → issue_supervisor_kubeconfig, get_tkc_kubeconfig → issue_tkc_kubeconfig. They issue a credential (a Supervisor bearer token) rather than read something, and a get_ name told agents otherwise. Parameters, annotations, safety and CLI commands (vmware-vks kubeconfig supervisor / kubeconfig get) are unchanged; callers of the old names must switch (saved vmware-pilot workflows are translated by Pilot ≥ 2.0.0). Deny rules in ~/.vmware/rules.yaml naming the old names keep working with vmware-policy ≥ 1.19.0. Details in RELEASE_NOTES.md.

Upgrading to 2.0

2.0 renames the three VM Service tools: list_vm_snapshots → list_vm_service_snapshots, list_vm_groups → list_vm_service_groups, list_vm_network_interfaces → list_vm_service_network_interfaces. The reason is a name clash: in the family's 2.0, vmware-aiops and vmware-monitor call their vSphere VM snapshot tool list_vm_snapshots, while these list Kubernetes VM Service (vm-operator) objects. Trap: an agent prompt, script or saved workflow that still calls list_vm_snapshots with vmware-aiops or vmware-monitor also loaded now reaches the vSphere tool, not this one — update it. A VKS-scoped deny rule naming list_vm_snapshots now also matches the aiops/monitor tool (vmware-policy ≥ 1.18 matches both names; vmware-audit policy lists such rules). Parameters, safety gates and CLI commands are unchanged; the full table is in RELEASE_NOTES.md. If an install older than 2.0 shares that rules.yaml, give it vmware-policy ≥ 1.18.2 too: it matches each rule against both the old and the new name, so one file serves both.

Companion Skills

Part of the VMware MCP Skills family. Each skill handles a distinct domain — install only what you need.

Prerequisites

• Python 3.10+ — required for uv tool install
• vSphere 8.0+ — Workload Management (Supervisor) APIs require vSphere 8.x
• Workload Management enabled — WCP must be enabled on at least one compute cluster
• License — vSphere Kubernetes Service (Enterprise Plus or VMware Cloud Foundation)

Run vmware-vks check after setup to verify all requirements are met.

Quick Start

# 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

Offline / Air-Gapped Install (from source)

This project uses the modern PEP 517 build system (hatchling), so there is no `setup.py` by design — that is expected, not a missing file. If you cloned the source and hit ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build, your pip is older than 21.3 and cannot do an *editable* (-e) install with a non-setuptools backend. Editable mode is a developer convenience, not needed to run the tool — do one of:

# 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 .

For a truly air-gapped host, build the wheels on a connected machine and copy them over — the target then needs no network:

# 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

Common Workflows

Deploy a New TKC Cluster

1. Check compatibility → vmware-vks check
2. List available K8s versions → vmware-vks tkc versions -n dev
3. Create namespace (if needed) → vmware-vks namespace create dev --cluster domain-c1 --storage-policy --cpu 16000 --memory 32768 --apply (get the policy ID from vmware-vks supervisor storage-policies)
4. Create TKC cluster → 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. Get kubeconfig (credential; only when you need cluster access) → vmware-vks kubeconfig get dev-cluster -n dev -o ./kubeconfig — writes an owner-only file instead of printing the token

Scale Workers for Load Testing

1. Check current state → vmware-vks tkc get dev-cluster -n dev
2. Scale up → vmware-vks tkc scale dev-cluster -n dev --workers 6
3. Monitor progress → vmware-vks tkc get dev-cluster -n dev (watch phase)
4. Scale back down after test

Namespace Resource Management

1. List namespaces → vmware-vks namespace list
2. Check usage → vmware-vks storage -n dev
3. Update quota → vmware-vks namespace update dev --cpu 32000 --memory 65536

Tool Reference (25 tools)

Supervisor

For an upgrade from vCenter 8.0 Update 3 or 9.0.0–9.0.2 to 9.1.0/9.1.1, run supervisor upgrade-risk before scheduling. Its report cannot inspect the VUMDB schema or establish upgrade clearance. If a Supervisor/VKS environment is in scope, follow the Broadcom checker and remediation instructions or VDT, then back up vCenter and Supervisor before upgrading.

Namespace

TKC

Access

VCF 9.1 TKC access: In one live 9.1 report, issue_tkc_kubeconfig put a Supervisor JWT into the guest kubeconfig and the TKC API rejected it with 401. Treat the generated file as unverified for guest access; test it against the guest API before use. See issue #27. Supervisor-scoped TKC reads are unaffected in that report.

VM Service (vm-operator)

Permissions

Architecture

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 Reference

# Pre-flight diagnostics

vmware-vks check

#