VMware VKS

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. 20 MCP tools.

Companion Skills

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

Prerequisites

• 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

echo "VMWARE_MY_VCENTER_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

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 vSAN --cpu 16000 --memory 32768 --apply

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 → vmware-vks kubeconfig get dev-cluster -n dev

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 (20 tools)

Supervisor

Namespace

TKC

Access

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 → vCenter REST API
  │   Supervisor status, storage policies, Namespace CRUD, VM classes, Harbor
  │
  └─ Layer 2: kubernetes client → Supervisor K8s API endpoint
      TKC CR apply / get / delete  (cluster.x-k8s.io/v1beta1)
      Kubeconfig built from Layer 1 session token
  ↓
vCenter Server 8.x+ (Workload Management enabled)
  ↓
Supervisor Cluster → vSphere Namespaces → TanzuKubernetesCluster

CLI Reference

# 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>
vmware-vks kubeconfig get <cluster-name> -n <namespace> [-o <path>]

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

MCP Server

After uv tool install vmware-vks, start the MCP server with one command (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

Agent Configuration

Add to your AI agent's MCP config:

{
  "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

Behind a corporate TLS proxy? uvx may fail with invalid peer certificate: UnknownIssuer. Use the recommended vmware-vks mcp form above (no network needed), or set UV_NATIVE_TLS=true.

Safety

Troubleshooting

"VKS not compatible" error

Workload Management must be enabled in vCenter. Check: vCenter UI -> Workload Management. Requires vSphere 8.x+ with Enterprise Plus or VCF license.

Namespace creation fails with "storage policy not found"

List available policies first: vmware-vks supervisor storage-policies. Policy names are case-sensitive.

TKC cluster stuck in "Creating" phase

Check Supervisor events in vCenter. Common causes: insufficient resources on ESXi hosts, network issues with NSX-T, or storage policy not available on target datastore.

Kubeconfig retrieval fails

Supervisor API endpoint must be reachable from the machine running vmware-vks. Check firewall rules for port 6443.

Scale operation has no effect

Verify the cluster is in "Running" phase before scaling. Clusters in "Creating" or "Updating" phase reject scale operations.

Delete namespace rejected unexpectedly

The namespace delete guard prevents deletion when TKC clusters exist inside. Delete all TKC clusters in the namespace first, then retry.

Version Compatibility

Related Projects

License

MIT