{
  "markdown": "<!-- mcp-name: io.github.vmware-skills/vmware-vks -->\n# VMware VKS\n\n> **Author**: Wei Zhou, VMware by Broadcom — wei-wz.zhou@broadcom.com\n> This is a community-driven project by a VMware engineer, not an official VMware product.\n> For official VMware developer tools see [developer.broadcom.com](https://developer.broadcom.com).\n\n[English](README.md) | [中文](README-CN.md)\n\nMCP Skill + CLI for VMware vSphere Kubernetes Service (VKS) management — Supervisor clusters, vSphere Namespaces, and VKS Cluster lifecycle. 23 MCP tools.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n## Companion Skills\n\n> **Part of the VMware MCP Skills family.** Each skill handles a distinct domain — install only what you need.\n\n| Skill | Scope | Tools | Install |\n|-------|-------|:-----:|---------|\n| **[vmware-aiops](https://github.com/vmware-skills/VMware-AIops)** ⭐ entry point | VM lifecycle, deployment, guest ops, clusters | 49 | `uv tool install vmware-aiops` |\n| **[vmware-monitor](https://github.com/vmware-skills/VMware-Monitor)** | Read-only monitoring, alarms, events, VM info | 27 | `uv tool install vmware-monitor` |\n| **[vmware-storage](https://github.com/vmware-skills/VMware-Storage)** | Datastores, iSCSI, vSAN | 11 | `uv tool install vmware-storage` |\n| **[vmware-nsx](https://github.com/vmware-skills/VMware-NSX)** | NSX networking: segments, gateways, NAT, IPAM | 33 | `uv tool install vmware-nsx-mgmt` |\n| **[vmware-nsx-security](https://github.com/vmware-skills/VMware-NSX-Security)** | DFW microsegmentation, security groups, Traceflow | 21 | `uv tool install vmware-nsx-security` |\n| **[vmware-aria](https://github.com/vmware-skills/VMware-Aria)** | Aria Ops metrics, alerts, capacity planning | 28 | `uv tool install vmware-aria` |\n\n## Prerequisites\n\n- **Python 3.10+** — required for `uv tool install`\n- **vSphere 8.0+** — Workload Management (Supervisor) APIs require vSphere 8.x\n- **Workload Management enabled** — WCP must be enabled on at least one compute cluster\n- **License** — vSphere Kubernetes Service (Enterprise Plus or VMware Cloud Foundation)\n\nRun `vmware-vks check` after setup to verify all requirements are met.\n\n## Quick Start\n\n```bash\n# Install\nuv tool install vmware-vks\n\n# Configure\nmkdir -p ~/.vmware-vks\ncp config.example.yaml ~/.vmware-vks/config.yaml\n# Edit config.yaml with your vCenter host and username\n\n# One password env var per target, named after the target in config.yaml:\n# target \"vcenter01\" (the one config.example.yaml ships) -> VMWARE_VKS_VCENTER01_PASSWORD\necho \"VMWARE_VKS_VCENTER01_PASSWORD=your_password\" > ~/.vmware-vks/.env\nchmod 600 ~/.vmware-vks/.env\n\n# Verify\nvmware-vks check\n\n# Common operations\nvmware-vks supervisor status domain-c1\nvmware-vks namespace list\nvmware-vks tkc list\nvmware-vks tkc create my-cluster -n dev --version v1.28.4+vmware.1 --vm-class best-effort-large\nvmware-vks tkc create my-cluster -n dev --apply\n```\n\n## Offline / Air-Gapped Install (from source)\n\nThis project uses the modern PEP 517 build system (hatchling), so there is **no\n`setup.py`** by design — that is expected, not a missing file. If you cloned the\nsource and hit `ERROR: File \"setup.py\" or \"setup.cfg\" not found ... editable mode\ncurrently requires a setuptools-based build`, your `pip` is older than 21.3 and\ncannot do an *editable* (`-e`) install with a non-setuptools backend. Editable\nmode is a developer convenience, not needed to run the tool — do one of:\n\n```bash\n# From the source tree — a normal (non-editable) install builds a wheel:\npip install .              # NOT  pip install -e .\n\n# ...or upgrade pip first, and editable works too:\npip install --upgrade pip && pip install -e .\n```\n\nFor a **truly air-gapped host**, build the wheels on a connected machine and copy\nthem over — the target then needs no network:\n\n```bash\n# On a connected machine, collect this package + its dependencies as wheels:\npip wheel . -w dist        # → dist/*.whl   (or: uv build, for just this package)\n\n# Copy dist/ to the air-gapped host, then install offline:\npip install --no-index --find-links dist vmware-vks\n```\n\n## Common Workflows\n\n### Deploy a New TKC Cluster\n\n1. Check compatibility → `vmware-vks check`\n2. List available K8s versions → `vmware-vks tkc versions -n dev`\n3. Create namespace (if needed) → `vmware-vks namespace create dev --cluster domain-c1 --storage-policy <policy-id> --cpu 16000 --memory 32768 --apply` (get the policy ID from `vmware-vks supervisor storage-policies`)\n4. 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`\n5. Get kubeconfig → `vmware-vks kubeconfig get dev-cluster -n dev`\n\n### Scale Workers for Load Testing\n\n1. Check current state → `vmware-vks tkc get dev-cluster -n dev`\n2. Scale up → `vmware-vks tkc scale dev-cluster -n dev --workers 6`\n3. Monitor progress → `vmware-vks tkc get dev-cluster -n dev` (watch phase)\n4. Scale back down after test\n\n### Namespace Resource Management\n\n1. List namespaces → `vmware-vks namespace list`\n2. Check usage → `vmware-vks storage -n dev`\n3. Update quota → `vmware-vks namespace update dev --cpu 32000 --memory 65536`\n\n## Tool Reference (20 tools)\n\n### Supervisor\n\n| Tool | Description | Type |\n|------|-------------|------|\n| `check_vks_compatibility` | vCenter version check + WCP status | Read |\n| `get_supervisor_status` | Supervisor cluster status and K8s API endpoint | Read |\n| `list_supervisor_storage_policies` | vCenter storage policies (policy ID, name, description) | Read |\n\n### Namespace\n\n| Tool | Description | Type |\n|------|-------------|------|\n| `list_namespaces` | All vSphere Namespaces with status | Read |\n| `get_namespace` | Namespace detail (quotas, storage, roles) | Read |\n| `create_namespace` | Create Namespace with dry-run preview | Write |\n| `update_namespace` | Modify quotas and storage policy | Write |\n| `delete_namespace` | Delete with TKC guard (rejects if clusters exist) | Write |\n| `list_vm_classes` | Available VM classes for TKC sizing | Read |\n\n### TKC\n\n| Tool | Description | Type |\n|------|-------------|------|\n| `list_tkc_clusters` | TanzuKubernetesCluster list with status | Read |\n| `get_tkc_cluster` | Cluster detail (nodes, health, conditions) | Read |\n| `get_tkc_available_versions` | Supported K8s versions on Supervisor | Read |\n| `create_tkc_cluster` | Create TKC with YAML plan + dry-run default | Write |\n| `scale_tkc_cluster` | Scale worker node count | Write |\n| `upgrade_tkc_cluster` | Upgrade K8s version | Write |\n| `delete_tkc_cluster` | Delete with workload guard | Write |\n\n### Access\n\n| Tool | Description | Type |\n|------|-------------|------|\n| `get_supervisor_kubeconfig` | Supervisor kubeconfig YAML | Read |\n| `get_tkc_kubeconfig` | TKC kubeconfig (stdout or file) | Write |\n| `get_harbor_info` | Embedded Harbor registry info (id, cluster, version, URL, health, storage used) | Read |\n| `list_namespace_storage_usage` | PVC list and capacity stats | Read |\n\n## Architecture\n\n```\nUser (Natural Language)\n  ↓\nAI Agent (Claude Code / Goose / Cursor)\n  ↓ reads SKILL.md\n  ↓\nvmware-vks CLI  ─── or ───  vmware-vks MCP Server (stdio)\n  │\n  ├─ Layer 1: pyVmomi (/sdk) + vSphere Automation REST (/api)\n  │   Supervisor status, storage policies, Namespace CRUD, VM classes, Harbor\n  │   Two session stores: the SOAP session from SmartConnect, and a separate\n  │     REST session id from POST /api/session (vmware-api-session-id header)\n  │\n  └─ Layer 2: kubernetes client → Supervisor K8s API endpoint\n      TKC CR apply / get / delete  (cluster.x-k8s.io API version auto-detected:\n        prefers v1 when Supervisor serves it, falls back to v1beta1 for vSphere 8.0)\n      Kubeconfig built in-memory from the POST /wcp/login bearer token\n        (a third credential, and no temp file on disk)\n  ↓\nvCenter Server 8.x+ (Workload Management enabled)\n  ↓\nSupervisor Cluster → vSphere Namespaces → TanzuKubernetesCluster\n```\n\n## CLI Reference\n\n```bash\n# Pre-flight diagnostics\nvmware-vks check\n\n# Supervisor\nvmware-vks supervisor status <cluster-id>\nvmware-vks supervisor storage-policies\n\n# Namespace\nvmware-vks namespace list\nvmware-vks namespace get <name>\nvmware-vks namespace create <name> --cluster <id> --storage-policy <policy>\nvmware-vks namespace create <name> --cluster <id> --storage-policy <policy> --apply\nvmware-vks namespace update <name> [--cpu <mhz>] [--memory <mib>]\nvmware-vks namespace delete <name>\nvmware-vks namespace vm-classes\n\n# VKS Cluster\nvmware-vks tkc list [-n <namespace>]\nvmware-vks tkc get <name> -n <namespace>\nvmware-vks tkc versions -n <namespace>\nvmware-vks tkc create <name> -n <namespace> [--version <v>] [--vm-class <c>]\nvmware-vks tkc create <name> -n <namespace> --apply\nvmware-vks tkc scale <name> -n <namespace> --workers <n>\nvmware-vks tkc upgrade <name> -n <namespace> --version <v>\nvmware-vks tkc delete <name> -n <namespace>\n\n# Kubeconfig\nvmware-vks kubeconfig supervisor -n <namespace>\nvmware-vks kubeconfig get <cluster-name> -n <namespace> [-o <path>]\n\n# Harbor & Storage\nvmware-vks harbor\nvmware-vks storage -n <namespace>\n```\n\n## MCP Server\n\n**After `uv tool install vmware-vks`, start the MCP server with one command** (v1.5.15+):\n\n```bash\n# Recommended — single command, no network re-resolve\nvmware-vks mcp\n\n# With a custom config path\nVMWARE_VKS_CONFIG=/path/to/config.yaml vmware-vks mcp\n```\n\n### Agent Configuration\n\nAdd to your AI agent's MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"vmware-vks\": {\n      \"command\": \"vmware-vks\",\n      \"args\": [\"mcp\"],\n      \"env\": {\n        \"VMWARE_VKS_CONFIG\": \"~/.vmware-vks/config.yaml\"\n      }\n    }\n  }\n}\n```\n\n<details>\n<summary>Alternative: uvx (no install) or legacy entry point</summary>\n\n```bash\n# Run without installing (requires PyPI access each launch)\nuvx --from vmware-vks vmware-vks mcp\n\n# Legacy entry point (still works, kept for backward compatibility)\nvmware-vks-mcp\n```\n\n> **Behind a corporate TLS proxy?** uvx may fail with `invalid peer certificate: UnknownIssuer`.\n> Use the recommended `vmware-vks mcp` form above (no network needed), or set `UV_NATIVE_TLS=true`.\n\n</details>\n\n## Safety\n\n| Feature | Description |\n|---------|-------------|\n| Read-heavy | 15/23 tools are read-only |\n| Dry-run default | `create_namespace`, `create_tkc_cluster`, `delete_namespace`, `delete_tkc_cluster` all default to `dry_run=True` |\n| TKC guard | `delete_namespace` rejects if TKC clusters exist inside |\n| Workload guard | `delete_tkc_cluster` rejects if Deployments/StatefulSets are running |\n| Credential safety | Passwords only from environment variables (`.env` file), never in `config.yaml` |\n| In-memory kubeconfig | Supervisor/TKC kubeconfig (with vCenter session bearer token) is built as an in-memory dict and loaded via `load_kube_config_from_dict()` — never written to a temp file on disk (v1.5.18+) |\n| Audit logging | All write operations logged to `~/.vmware-vks/audit.log` |\n| stdio transport | No network listener; MCP runs over stdio only |\n\n## Troubleshooting\n\n### \"VKS not compatible\" error\n\nWorkload Management must be enabled in vCenter. Check: vCenter UI -> Workload Management. Requires vSphere 8.x+ with Enterprise Plus or VCF license.\n\n### Every REST tool returns 401\n\nThe namespace, storage-policy and Supervisor-status tools authenticate against\nthe vSphere Automation REST API with a session id from `POST /api/session` —\n**not** the pyVmomi SOAP session key, which that API never issued and always\nrejects. A 401 is refreshed automatically once; if it persists, check whether a\nproxy between you and vCenter strips the `vmware-api-session-id` header. An\naccount short of Workload Management permissions gets a **403**, not a 401.\n\n### Namespace creation fails with \"storage policy not found\"\n\nList policies first: `vmware-vks supervisor storage-policies`, then pass the **Policy ID** column value (not the display name) as `--storage-policy`.\n\n### TKC cluster stuck in \"Creating\" phase\n\nCheck Supervisor events in vCenter. Common causes: insufficient resources on ESXi hosts, network issues with NSX-T, or storage policy not available on target datastore.\n\n### Kubeconfig retrieval fails\n\nSupervisor API endpoint must be reachable from the machine running vmware-vks. Check firewall rules for port 6443.\n\n### Scale operation has no effect\n\nVerify the cluster is in \"Running\" phase before scaling. Clusters in \"Creating\" or \"Updating\" phase reject scale operations.\n\n### Delete namespace rejected unexpectedly\n\nThe namespace delete guard prevents deletion when TKC clusters exist inside. Delete all TKC clusters in the namespace first, then retry.\n\n## Version Compatibility\n\n| vSphere / VCF | Support | Notes |\n|---------|---------|-------|\n| 9.0 / 9.1 | ⚠ Not yet verified | Workload Management (Supervisor / WCP) API surface in vSphere 9 has not been tested by maintainers. Existing vSphere 8.x code paths should work but no guarantees until a lab run is completed — basic CRUD likely works, corner cases may need testing. File issues with `check_vks_compatibility` output if you run this on VCF 9. |\n| 8.0+ | Full | Workload Management APIs available |\n| 7.x | Not supported | WCP API surface is different; use vSphere 8.x |\n\n#### Official Broadcom References\n\n- **SDKs**: <https://developer.broadcom.com/sdks> — VCF Python SDK (unified SDK in VCF 9+)\n- **REST APIs**: <https://developer.broadcom.com/xapis> — vSphere Automation API (Workload Management endpoints)\n- **CLI Tools**: <https://developer.broadcom.com/tools> — kubectl-vsphere, PowerCLI 9.1\n\n## Related Projects\n\n| Skill | Scope | Tools | Install |\n|-------|-------|:-----:|---------|\n| **[vmware-aiops](https://github.com/vmware-skills/VMware-AIops)** ⭐ entry point | VM lifecycle, deployment, guest ops, clusters | 49 | `uv tool install vmware-aiops` |\n| **[vmware-monitor](https://github.com/vmware-skills/VMware-Monitor)** | Read-only monitoring, alarms, events, VM info | 27 | `uv tool install vmware-monitor` |\n| **[vmware-storage](https://github.com/vmware-skills/VMware-Storage)** | Datastores, iSCSI, vSAN | 11 | `uv tool install vmware-storage` |\n| **[vmware-nsx](https://github.com/vmware-skills/VMware-NSX)** | NSX networking: segments, gateways, NAT, IPAM | 33 | `uv tool install vmware-nsx-mgmt` |\n| **[vmware-nsx-security](https://github.com/vmware-skills/VMware-NSX-Security)** | DFW microsegmentation, security groups, Traceflow | 21 | `uv tool install vmware-nsx-security` |\n| **[vmware-aria](https://github.com/vmware-skills/VMware-Aria)** | Aria Ops metrics, alerts, capacity planning | 28 | `uv tool install vmware-aria` |\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 14596,
  "sha": "37128e9d63cee3b186d985251ce522f4bbae5dca32eeaada1e6399c457621420",
  "repo_slug": "vmware-skills/vmware-vks",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vmware_skills_vmware_vks_dc7adaf1/readme"
}