VMware AVI

VMware AVI

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

English | 中文

AVI（NSX Advanced Load Balancer）管理和 AKO Kubernetes 操作工具 — 涵盖 10 个类别的 28 个工具。

双模式：在一个技能中提供传统 AVI Controller 管理和 AKO K8s 操作。

配套技能负责其他所有功能：

技能	范围	安装
vmware-aiops	VM 生命周期、部署、来宾操作、集群	uv tool install vmware-aiops
vmware-monitor	只读：清单、健康状况、警报、事件	uv tool install vmware-monitor
vmware-storage	数据存储、iSCSI、vSAN 管理	uv tool install vmware-storage
vmware-vks	Tanzu 命名空间、TKC 集群生命周期	uv tool install vmware-vks
vmware-nsx	NSX 网络：网段、网关、NAT	uv tool install vmware-nsx-mgmt
vmware-nsx-security	DFW 防火墙规则、安全组	uv tool install vmware-nsx-security
vmware-aria	Aria Ops：指标、警报、容量	uv tool install vmware-aria

升级到 2.0

2.0 重命名了全部 28 个 MCP 工具，使每个名称都以动词开头（例如，ako_amko_status → get_ako_amko_status、ako_clusters → list_ako_clusters、ako_config_diff → diff_ako_config）。完整的新旧名称对照表请参阅 RELEASE_NOTES.md。其他内容均未更改：工具、参数、 安全门控和 CLI 命令都相同。如果 Agent 提示词、脚本或 ~/.vmware/rules.yaml 中使用了工具名称，请更新它们。不过，使用旧名称编写的拒绝规则仍可与 vmware-policy ≥ 1.18 配合使用（vmware-audit policy 会列出重命名后适用范围扩大的规则），vmware-pilot ≥ 1.13 会转换已保存工作流中的旧名称。 如果低于 2.0 的安装与其共用该 rules.yaml，也请将其升级到 vmware-policy ≥ 1.18.2：该版本会同时针对新旧名称匹配每条规则，因此一个文件即可供两者使用。

快速安装

# Via uv (recommended)
uv tool install vmware-avi

# Or via pip
pip install vmware-avi

# China mainland mirror
pip install vmware-avi -i https://pypi.tuna.tsinghua.edu.cn/simple

# Verify installation
vmware-avi doctor

离线／隔离网络安装（从源代码安装）

本项目使用现代 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-avi

功能概览

此 Skill 的功能

CLI 与 MCP：选择哪种模式

经验法则：追求成本效率或使用小型模型时，使用 CLI。需要借助大模型进行结构化自动化时，使用 MCP。

架构

User (Natural Language)
  |
AI CLI Tool (Claude Code / Gemini / Codex / Cursor / Trae)
  | reads SKILL.md
  |
vmware-avi CLI
  |--- avisdk (AVI REST API) ---> AVI Controller ---> Virtual Services / Pools / SEs
  |--- kubectl / kubernetes ---> K8s Cluster ---> AKO Pods / Ingress / Services

配置

步骤 1：创建配置目录

mkdir -p ~/.vmware-avi
vmware-avi init          # generates config.yaml and .env templates
chmod 600 ~/.vmware-avi/.env

步骤 2：编辑 config.yaml

controllers:
  - name: prod-avi
    host: avi-controller.example.com
    username: admin
    api_version: "22.1.4"
    tenant: admin
    port: 443
    verify_ssl: true

default_controller: prod-avi

ako:
  kubeconfig: ~/.kube/config
  default_context: ""
  namespace: avi-system

步骤 3：设置密码

创建 ~/.vmware-avi/.env：

# AVI Controller passwords
# Format: {CONTROLLER_NAME_UPPER}_PASSWORD
PROD_AVI_PASSWORD=your-password-here

密码环境变量命名约定：

{CONTROLLER_NAME_UPPER}_PASSWORD
# Replace hyphens with underscores, UPPERCASE
# Example: controller "prod-avi" -> PROD_AVI_PASSWORD
# Example: controller "staging-alb" -> STAGING_ALB_PASSWORD

步骤 4：验证

vmware-avi doctor    # checks Controller connectivity + kubeconfig + avisdk

CLI 用法

虚拟服务管理

# List all virtual services
vmware-avi vs list [--controller prod-avi]

# Check status of a specific VS
vmware-avi vs status my-webapp-vs

# Enable / disable a VS (disable requires double confirmation)
vmware-avi vs enable my-webapp-vs
vmware-avi vs disable my-webapp-vs

池成员排空/恢复

# List pool members and health status
vmware-avi pool members my-pool

# Graceful drain (disable) — double confirmation required
vmware-avi pool disable my-pool 10.1.1.5

# Restore traffic (enable)
vmware-avi pool enable my-pool 10.1.1.5

SSL 证书到期检查

# List all certificates
vmware-avi ssl list

# Check certificates expiring within 30 days
vmware-avi ssl expiry --days 30

分析和错误日志

# VS analytics: throughput, latency, error rates
vmware-avi analytics my-webapp-vs

# Request error logs
vmware-avi logs my-webapp-vs --since 1h

服务引擎运行状况

# Name, mgmt IP, operational status, SE group — status sourced from the
# serviceengine-inventory endpoint (config + runtime merged)
vmware-avi se list

# Per-SE operational status + connected-VS counts
vmware-avi se health

AKO 故障排查

# Check AKO pod status
vmware-avi ako status [--context my-k8s-context]

# View AKO logs
vmware-avi ako logs [--tail 100] [--since 30m]

# Restart AKO pod (double confirmation)
vmware-avi ako restart

# Show AKO version
vmware-avi ako version

AKO Helm 配置管理

系统会自动发现 AKO Helm 版本（官方安装使用 helm install --generate-name，因此版本名称不是 ako）。升级时会使用 --reuse-values 拉取 Broadcom 官方 OCI Chart oci://projects.packages.broadcom.com/ako/helm-charts/ako。

# View current AKO Helm values (release auto-discovered)
vmware-avi ako config show

# Show pending changes (diff against the official OCI chart)
vmware-avi ako config diff

# Helm upgrade (double confirmation + --dry-run default)
vmware-avi ako config upgrade

Ingress 诊断

# Validate Ingress annotations
vmware-avi ako ingress check <namespace>

# Show Ingress-to-VS mapping
vmware-avi ako ingress map

# Diagnose why an Ingress has no VS
vmware-avi ako ingress diagnose <ingress-name>

同步诊断

# Check K8s-Controller sync status
vmware-avi ako sync status

# Show inconsistencies between K8s and Controller
vmware-avi ako sync diff

# Force AKO resync (double confirmation)
vmware-avi ako sync force

多集群 AKO

# List every kube-context and whether AKO runs there
vmware-avi ako clusters

# Cross-cluster AKO status overview
vmware-avi ako cluster-overview

# AMKO GSLB status
vmware-avi ako amko status

MCP 服务

MCP 服务通过 Model Context Protocol 提供全部 28 个工具。适用于任何兼容 MCP 的客户端。

执行 uv tool install vmware-avi 后，只需一条命令即可启动 MCP 服务（v1.5.15+）：

# Recommended — single command, no network re-resolve
vmware-avi mcp

# With custom config path
VMWARE_AVI_CONFIG=/path/to/config.yaml vmware-avi mcp

Claude Desktop 配置

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "vmware-avi": {
      "command": "vmware-avi",
      "args": ["mcp"],
      "env": {
        "VMWARE_AVI_CONFIG": "~/.vmware-avi/config.yaml"
      }
    }
  }
}

# Run without installing (requires PyPI access each launch)
uvx --from vmware-avi vmware-avi mcp

# Legacy entry point (still works, kept for backward compatibility)
vmware-avi-mcp

MCP 工具（28 个）

常见工作流

1. 维护窗口——排空池成员

将后端服务器下线以进行补丁维护时：

1. 列出池成员及其健康状态

   vmware-avi pool members my-pool
   

2. 禁用目标服务器（优雅排空）

   vmware-avi pool disable my-pool 10.1.1.5
   

3. 监控分析数据，确认活动连接正在排空

   vmware-avi analytics my-vs
   

4. 对服务器进行维护
5. 重新启用服务器

   vmware-avi pool enable my-pool 10.1.1.5
   

6. 确认健康状态为绿色

   vmware-avi pool members my-pool
   

2. AKO Ingress 未创建 VS

开发人员报告其 Ingress 未生成 Virtual Service 时：

1. 确认 AKO 正在运行

   vmware-avi ako status
   

2. 验证 Ingress 注解

   vmware-avi ako ingress check <namespace>
   

3. 检查 K8s 与 Controller 之间的同步状态

   vmware-avi ako sync status
   

4. 如果注解有误，诊断具体的 Ingress

   vmware-avi ako ingress diagnose <ingress-name>
   

5. 如果检测到同步偏差，检查差异，并在需要时强制重新同步

   vmware-avi ako sync diff
   vmware-avi ako sync force
   

3. SSL 证书到期审计

证书过期会导致服务中断。定期执行检查：

1. 检查所有将在 30 天内到期的证书

   vmware-avi ssl expiry --days 30
   

2. 查看每个即将到期的证书被哪些 VS 使用（输出包含 VS 映射）
3. 与证书团队规划续期
4. 续期后，确认新证书已就位

   vmware-avi ssl list
   

故障排除

“Controller 无法访问”错误

1. 运行 vmware-avi doctor 以验证连接
2. 检查 ~/.vmware-avi/config.yaml 中的 Controller 地址和端口是否正确
3. 对于自签名证书：在 config.yaml 中设置 verify_ssl: false（仅限实验室环境）

AKO Pod 处于 CrashLoopBackOff 状态

1. 检查日志：vmware-avi ako logs --tail 50
2. 常见原因：values.yaml 中的 Controller IP 错误、网络策略阻止 AKO 访问 Controller、凭据过期
3. 修复配置：使用 vmware-avi ako config show 检查，然后使用修正后的值运行 vmware-avi ako config upgrade（自动发现 release；拉取官方 Broadcom OCI chart）

已创建 Ingress，但 Controller 上没有 VS

1. 验证注解：vmware-avi ako ingress check <namespace>
2. 检查 AKO 日志中的拒绝原因：vmware-avi ako logs --since 5m
3. 运行同步差异检查：vmware-avi ako sync diff，查看对象是否卡住

池成员启用后仍显示为“down”

健康监视器可能仍然失败。该成员已启用，但处于不健康状态。检查 Controller 端的实际健康状态。先修复后端服务，健康状态随后会自动恢复。

SSL 到期检查显示 0 个证书

确认 Controller 连接具有租户级访问权限。AVI 中的证书按租户划分。配置的用户可能只能看到其所在租户中的证书。

AKO 强制同步无效

强制重新同步会触发 AKO 重新协调所有 K8s 对象。如果偏差仍然存在，问题可能出在 K8s 资源定义本身（注解错误、缺少 secret）。使用 vmware-avi ako ingress diagnose 确定根本原因。

安全功能

安全详情

• 源代码：github.com/vmware-skills/VMware-AVI
• 配置文件内容：config.yaml 存储控制器地址、用户名和 AKO 设置。不包含密码或令牌。所有机密信息仅存储在 .env 中
• Webhook 数据范围：默认禁用。不向第三方传输数据
• TLS 验证：默认启用。仅在使用自签名证书的环境中禁用
• 提示词注入防护：对所有 AVI API 响应执行 _sanitize() 截断处理和控制字符清理
• 最小权限：使用权限最少的专用 AVI 服务账户。AKO 操作仅需要命名空间范围的 kubeconfig 访问权限

配套技能

版本兼容性

Broadcom 官方参考资料

• SDKs：https://developer.broadcom.com/sdks — VCF Python SDK
• REST API：https://developer.broadcom.com/xapis — AVI Controller REST API
• CLI 工具：https://developer.broadcom.com/tools — VCF PowerCLI 9.1

故障排查与贡献

如果遇到任何错误或问题，请将错误消息、日志或屏幕截图发送至 [email protected]。欢迎贡献——欢迎加入我们，一起维护和改进此项目！

远程访问（HTTPS）与限制工具

默认情况下，vmware-avi 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-avi 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 为例；任何支持 streamable HTTP 和自定义标头的 MCP 客户端均可使用）：

claude mcp add --transport http vmware-avi https://mcp.example.com:8443/mcp \
    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"

{
  "mcpServers": {
    "vmware-avi": {
      "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，即可查找同一平台请求对应的调用。
• 审计日志会将每个调用方记录为 token:<name>。调用会并行运行：每个调用都使用自己面向 Controller（或 Kubernetes 上下文）的会话，每个目标最多有 VMWARE_MCP_POOL_SIZE 个会话（默认值为 2）。每个 Controller 会话都需要在 Controller 上登录；调用最多等待 300 s 以获取可用会话。
• 所有能够访问此端点的人，都会以此服务的账户身份操作。 Token 用于标识调用方；它们不会授予任何平台权限。请为每个权限级别运行一个端点。
• **同一端点上有多个用户或角色时：**运行一次 vmware-audit roles enable，然后为每个 token 分配一个角色（vmware-audit token create NAME --role reader，或在 roles.yaml 中指定角色可用的工具和目标；vmware-policy ≥ 1.24.0）。角色会限制 token 在此端点上可调用的工具，但不会授予超出账户自身权限的权限。请参阅 vmware-policy 的 README 中的“Roles for network callers”。

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

vmware-avi mcp --expose read --allow-write disable_lb_pool_member
# or: VMWARE_AVI_MCP_EXPOSE=read VMWARE_AVI_MCP_ALLOW_WRITE=disable_lb_pool_member vmware-avi mcp

未提供的工具不会显示在客户端的工具列表中。无效值或未知的写入工具会导致服务停止（退出码 2）。这限制了客户端可使用的工具；但这并非授权机制，因此账户本身应遵循最小权限原则。

详情：skills/vmware-avi/references/setup-guide.md（“Serving MCP over HTTPS”、“Limiting which tools are offered”）。

许可证

MIT