VMware VKS

Disclaimer: This is a community-maintained open-source project and is not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom Inc. "VMware" and "vSphere" are trademarks of Broadcom. Source code is publicly auditable at github.com/zw008/VMware-VKS under the MIT license.

AI-powered VMware vSphere Kubernetes Service (VKS) management — 20 MCP tools.

Requires vSphere 8.x+ with Workload Management enabled. Companion skills: vmware-aiops (VM lifecycle), vmware-monitor (monitoring), vmware-storage (storage), vmware-nsx (NSX networking), vmware-nsx-security (DFW/firewall), vmware-aria (metrics/alerts/capacity), vmware-avi (AVI/ALB/AKO). | vmware-pilot (workflow orchestration) | vmware-policy (audit/policy)

What This Skill Does

Quick Install

uv tool install vmware-vks
vmware-vks doctor

When to Use This Skill

• Check if vSphere environment supports VKS
• Create, update, or delete Supervisor Namespaces with resource quotas
• Deploy, scale, upgrade, or delete TKC (TanzuKubernetesCluster) clusters
• Get kubeconfig for Supervisor or TKC clusters
• Check Harbor registry info or storage usage

Use companion skills for:

• VM lifecycle, deployment → vmware-aiops
• Inventory, health, alarms → vmware-monitor
• iSCSI, vSAN, datastore → vmware-storage
• Load balancing, AVI/ALB, AKO, Ingress → vmware-avi

Related Skills — Skill Routing

Common Workflows

Deploy a New TKC Cluster

1. Check compatibility → vmware-vks supervisor check --target prod
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

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

Usage Mode

MCP Tools (20 — 12 read, 8 write)

All accept optional target parameter to specify a named vCenter.

create_namespace / create_tkc_cluster — defaults to dry_run=True, returns a YAML plan for review. Pass dry_run=False to apply.

delete_namespace — requires confirmed=True and rejects if TKC clusters still exist (prevents orphaned clusters).

delete_tkc_cluster — requires confirmed=True and checks for running workloads. Rejects if found unless force=True.

Credential handling: get_supervisor_kubeconfig and get_tkc_kubeconfig return short-lived session tokens (not long-lived credentials). Tokens are derived from the authenticated vCenter session and expire when the session ends. Kubeconfig output is intended for local kubectl use — agents should write it to a file (-o \x3Cpath>) rather than displaying tokens in conversation context.

Full capability details and safety features: see references/capabilities.md

CLI Quick Reference

# Supervisor
vmware-vks check [--target \x3Cname>]
vmware-vks supervisor status \x3Ccluster-id> [--target \x3Cname>]
vmware-vks supervisor storage-policies [--target \x3Cname>]

# Namespace
vmware-vks namespace list [--target \x3Cname>]
vmware-vks namespace get \x3Cname> [--target \x3Cname>]
vmware-vks namespace create \x3Cname> --cluster \x3Cid> [--cpu \x3Cn>] [--memory \x3Cmb>] [--storage-policy \x3Cname>] [--apply]
vmware-vks namespace update \x3Cname> [--cpu \x3Cn>] [--memory \x3Cmb>] [--target \x3Cname>]
vmware-vks namespace delete \x3Cname> [--target \x3Cname>]

# TKC Clusters
vmware-vks tkc list [-n \x3Cnamespace>] [--target \x3Cname>]
vmware-vks tkc create \x3Cname> -n \x3Cns> [--version \x3Cv>] [--workers \x3Cn>] [--vm-class \x3Cname>] [--apply]
vmware-vks tkc scale \x3Cname> -n \x3Cns> --workers \x3Cn> [--target \x3Cname>]
vmware-vks tkc upgrade \x3Cname> -n \x3Cns> --version \x3Cv> [--target \x3Cname>]
vmware-vks tkc delete \x3Cname> -n \x3Cns> [--force] [--target \x3Cname>]

# Kubeconfig
vmware-vks kubeconfig supervisor -n \x3Cnamespace> [--target \x3Cname>]
vmware-vks kubeconfig get \x3Ccluster-name> -n \x3Cnamespace> [-o \x3Cpath>] [--target \x3Cname>]

# Harbor & Storage
vmware-vks harbor [--target \x3Cname>]
vmware-vks storage -n \x3Cnamespace> [--target \x3Cname>]

Full CLI reference with all flags and interactive creation: see references/cli-reference.md

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.

Prerequisites

• vSphere 8.x+ with Workload Management enabled
• Enterprise Plus or VCF license
• NSX-T (recommended) or VDS + HAProxy networking
• Supervisor Cluster configured and running

Setup

uv tool install vmware-vks
mkdir -p ~/.vmware-vks
vmware-vks init

All tools are automatically audited via vmware-policy. Audit logs: vmware-audit log --last 20

Full setup guide, security details, and AI platform compatibility: see references/setup-guide.md

Audit & Safety

All operations are automatically audited via vmware-policy (@vmware_tool decorator):

• Every tool call logged to ~/.vmware/audit.db (SQLite, framework-agnostic)
• Policy rules enforced via ~/.vmware/rules.yaml (deny rules, maintenance windows, risk levels)
• Risk classification: each tool tagged as low/medium/high/critical
• View recent operations: vmware-audit log --last 20
• View denied operations: vmware-audit log --status denied

vmware-policy is automatically installed as a dependency — no manual setup needed.

License

MIT — github.com/zw008/VMware-VKS