VMware VKS

VMware VKS

作者：Wei Zhou，VMware by Broadcom — [email protected] 这是由 VMware 工程师发起的社区项目，并非 VMware 官方产品。 如需了解 VMware 官方开发者工具，请访问 developer.broadcom.com。

English | 中文

用于管理 VMware vSphere Kubernetes Service (VKS) 的 MCP 技能 + CLI — Supervisor 集群、vSphere 命名空间和 VKS 集群生命周期管理。24 个 MCP 工具。

升级到 3.0

3.0 重命名了两个 kubeconfig 工具：get_supervisor_kubeconfig → issue_supervisor_kubeconfig， get_tkc_kubeconfig → issue_tkc_kubeconfig。它们用于签发凭据（Supervisor bearer token），而不是读取内容；使用 get_ 名称会让 Agent 产生误解。参数、注解、安全机制和 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 工具：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）对象。注意： 如果 Agent 提示词、脚本或已保存的工作流仍使用 list_vm_snapshots，且同时加载了 vmware-aiops 或 vmware-monitor，现在调用到的将是 vSphere 工具，而非此工具 — 请更新。VKS 范围内使用 list_vm_snapshots 的拒绝规则现在也会匹配 aiops/monitor 工具（vmware-policy ≥ 1.18 会匹配新旧两个名称；vmware-audit policy 可列出此类规则）。参数、安全门控和 CLI 命令均未更改；完整表格请参阅 RELEASE_NOTES.md。 如果低于 2.0 的安装与其共用同一个 rules.yaml，也请将其 vmware-policy 升级到 ≥ 1.18.2：它会针对旧名称和新名称检查每条规则，因此同一个文件可供两者使用。

配套技能

属于 VMware MCP Skills 系列。 每项技能负责不同领域 — 仅安装所需的技能。

前提条件

• Python 3.10+ — uv tool install 所需
• vSphere 8.0+ — Workload Management (Supervisor) API 需要 vSphere 8.x
• 已启用 Workload Management — 至少一个计算集群必须启用 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（从 vmware-vks supervisor storage-policies 获取策略 ID）
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

命名空间

TKC

访问

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 后，只需一条命令即可启动 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

Agent 配置

将以下内容添加到 AI Agent 的 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 不会为其显示会话，导致每次调用都失败。由于仅拥有 Supervisor 命名空间权限的账户看起来可能相同且仍能正常工作，因此 VKS 连接时不会拒绝此类登录；只有在首次调用需要角色的操作时才会出现错误。请在 Administration > Access Control > Global Permissions 下，为该账户分配 vCenter 根文件夹上的角色（Read-Only 或更高）。命名空间和 TKC 操作还需要 Workload Management 权限。

每个 REST 工具都返回 401

命名空间、存储策略和 Supervisor 状态工具通过 POST /api/session 获取会话 ID，并使用该 ID 对 vSphere Automation REST API 进行身份验证——而不是 pyVmomi SOAP 会话密钥，因为该 API 从未签发过此密钥，并且始终会拒绝它。401 错误会自动刷新一次；如果问题仍然存在，请检查你与 vCenter 之间的代理是否剥除了 vmware-api-session-id 标头。Workload Management 权限不足的账户会收到 403，而不是 401。

创建命名空间时失败，并显示“未找到存储策略”

先列出策略：vmware-vks supervisor storage-policies，然后将 Policy ID 列中的值（而不是显示名称）作为 --storage-policy 传入。

TKC 集群卡在“Creating”阶段

检查 vCenter 中的 Supervisor 事件。常见原因包括：ESXi 主机资源不足、NSX-T 网络问题，或目标数据存储上没有可用的存储策略。

获取 Kubeconfig 失败

运行 vmware-vks 的计算机必须能够访问 Supervisor API 端点。检查端口 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 与一个本地客户端通信，并提供所有工具。两种选项可更改此设置 （vmware-policy ≥ 1.21.0）。

通过 HTTPS 提供服务，以便其他机器上的客户端可以连接。每个调用方都需要一个 bearer token：

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

• 没有 token 时，服务不会启动；它会拒绝 --public-name 之外的 Host/Origin 值，并在绑定端口前检查未认证请求是否会收到 401。请使用客户端信任的证书，并确保其名称匹配。
• 如果在同一台机器上使用终止 TLS 的反向代理，请使用 --transport http --host 127.0.0.1 --public-name mcp.example.com，并透传 Authorization 请求头。
• 如果在另一台机器上使用负载均衡器或网关，请保留 --transport https（自签名证书也可以），在 --public-name 中列出负载均衡器发送的 Host 名称，并让其转发 Authorization。其健康探测可使用 GET /healthz，此请求无需 token，且只返回 {"status": "ok"} （vmware-policy ≥ 1.23.0）。
• 每个请求都发送 traceparent 或 X-Request-ID，即可将其记录在审计行中；随后使用 vmware-audit log --correlation-id ID 查找同一平台请求背后的调用。
• 在此服务上读取或写入文件的工具（此处为 issue_*_kubeconfig(output_path)）绝不会访问其配置、token、审计日志或 TLS 密钥；通过网络使用时，除非 VMWARE_MCP_FILE_ROOT 指定了这些工具可访问的目录，否则它们处于关闭状态 （vmware-policy ≥ 1.23.1）。
• 审计日志会将每个调用方记录为 token:<name>。调用可以并行运行，即使目标相同也不例外：服务会为每个目标保留最多 VMWARE_MCP_POOL_SIZE 个会话（默认值为 2），每个会话都会登录该目标；调用最多等待 300 s 以获取空闲会话（vmware-policy ≥ 1.22.0）。
• 所有能够访问此端点的人，都会以此服务的账户身份执行操作。 Token 用于识别调用方，不会授予其任何平台权限。请为每个权限级别运行一个端点。vmware-vks access-info 会显示该账户及其可执行的操作。
• **在一个端点上为多个人员或角色提供访问：**运行一次 vmware-audit roles enable，然后为每个 token 指定一个角色（vmware-audit token create NAME --role reader，或在 roles.yaml 中指定工具和目标的角色；vmware-policy ≥ 1.24.0）。角色会限制 token 在此端点上可调用的内容，但不能授予超出该账户权限的权限。请参阅 vmware-policy 的 README 中的“网络调用方的角色”。

仅提供只读工具，以及你选择的写入工具：

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（“通过 HTTPS 提供 MCP 服务”“限制提供的工具”）。

许可证

MIT