用途
VMware AVI 是一个用于管理 AVI（NSX Advanced Load Balancer）并执行 AKO Kubernetes 运维的工具，作者为 VMware by Broadcom 的 Wei Zhou，属于社区驱动项目，并非官方 VMware 产品。它同时覆盖两条工作流：传统 AVI Controller 管理与 AKO K8s 操作，共提供 28 个工具，分布在 10 个类别中。
主要能力
工具围绕以下类别组织：虚拟服务管理、池成员 drain/restore、SSL 证书到期检查、分析与错误日志、Service Engine 健康、AKO 故障排查、AKO Helm 配置管理、Ingress 诊断、同步诊断、多集群 AKO。
在 AKO Helm 配置方面，AKO Helm release 会被自动发现；官方安装使用 helm install --generate-name，因此 release 不命名为 ako。升级时会拉取官方 Broadcom OCI chart：oci://projects.packages.broadcom.com/ako/helm-charts/ako，并使用 --reuse-values。
MCP 服务器通过 Model Context Protocol 暴露全部 28 个工具，兼容任何支持 MCP 的客户端，可用于结构化自动化。
使用方式
工具提供 CLI 与 MCP 两种模式。资料给出的经验法则是：追求成本效率、使用小模型时用 CLI；使用大模型做结构化自动化时用 MCP。
配置步骤：
- 创建配置目录；
- 编辑 config.yaml；
- 设置密码，创建
~/.vmware-avi/.env，密码环境变量遵循命名约定。
安装：项目使用 PEP 517 构建系统（hatchling），因此没有 setup.py 是设计如此。若安装较旧的 pip（低于 21.3）使用可编辑模式（-e）安装非 setuptools 后端项目会报错。编辑模式只是开发便利，并非运行工具所必需。对于完全气隙的主机，可先在联网机器上构建 wheels 再复制过去，目标机无需网络。
安装后可一条命令启动 MCP 服务器（v1.5.15+），Claude Desktop 配置可加入 claude_desktop_config.json。若处于企业 TLS 代理之后，uvx 可能报 invalid peer certificate: UnknownIssuer，建议使用推荐的 vmware-avi mcp 形式（不需要网络），或设置 UV_NATIVE_TLS=true。
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 中引用了工具名，需要更新。使用旧名称编写的 deny 规则在 vmware-policy ≥ 1.18 下仍可工作（vmware-audit policy 会列出因重命名而扩大的规则），vmware-pilot ≥ 1.13 会在已保存工作流中转换旧名称。若共享同一 rules.yaml 的旧安装早于 2.0，也建议使用 vmware-policy ≥ 1.18.2，因为它会对每条规则同时匹配旧名与新名，一个文件可同时服务两种版本。
常见工作流
维护窗口——排空池成员：列出池成员与健康状态（vmware-avi pool members my-pool）→ 禁用目标服务器进行优雅排空（vmware-avi pool disable my-pool 10.1.1.5）→ 监控分析确认活动连接正在排空（vmware-avi analytics my-vs）→ 对服务器执行维护 → 重新启用服务器（vmware-avi pool enable my-pool 10.1.1.5）→ 验证健康状态为绿色。
AKO Ingress 未创建 VS：验证 AKO 正在运行（vmware-avi ako status）→ 校验 Ingress 注解（vmware-avi ako ingress check <namespace>）→ 检查 K8s 与 Controller 之间的同步状态（vmware-avi ako sync status）→ 若注解错误，诊断具体 Ingress（vmware-avi ako ingress diagnose <ingress-name>）→ 若检测到同步漂移，审查 diff 并在需要时强制重新同步（vmware-avi ako sync diff、vmware-avi ako sync force）。
SSL 证书到期审计：检查 30 天内到期的所有证书（vmware-avi ssl expiry --days 30）→ 查看每张到期证书被哪个 VS 使用（输出包含 VS 映射）→ 与证书团队规划续期 → 续期后验证新证书就位（vmware-avi ssl list）。
故障排查
- “Controller unreachable”：运行
vmware-avi doctor验证连通性；检查~/.vmware-avi/config.yaml中的 controller 地址与端口；自签名证书可设置verify_ssl: false（仅限实验环境）。 - AKO Pod 处于 CrashLoopBackOff：查看日志
vmware-avi ako logs --tail 50；常见原因是 values.yaml 中 controller IP 错误、网络策略阻止 AKO 访问 Controller、凭据过期；检查配置vmware-avi ako config show，再用修正后的值执行vmware-avi ako config upgrade（release 自动发现，拉取官方 Broadcom OCI chart）。 - Ingress 已创建但 Controller 上无 VS：校验注解
vmware-avi ako ingress check <namespace>；查看 AKO 日志中的拒绝原因vmware-avi ako logs --since 5m；运行vmware-avi ako sync diff查看对象是否卡住。 - 池成员在 enable 后显示 “down”：健康监控可能仍失败，成员已启用但不健康。检查 Controller 侧实际健康状态，先修复后端服务，健康状态会自动恢复。
- SSL 到期检查显示 0 张证书：确认 controller 连接具备租户级访问权限，AVI 中证书是租户范围的，所配置用户可能只能看到其租户内的证书。
ako sync force无效：强制重新同步会触发 AKO 重新协调所有 K8s 对象；若漂移仍存在，问题可能在 K8s 资源定义本身（注解错误、Secret 缺失），可用vmware-avi ako ingress diagnose定位根因。
适用范围与限制
该工具面向 AVI（NSX Advanced Load Balancer）与 AKO Kubernetes 运维场景，适合在传统 Controller 管理和 K8s Ingress/AKO 运维之间切换使用。安全设计包括：配置文件 config.yaml 只存 controller 地址、用户名与 AKO 设置，不存密码或令牌，所有机密只存放在 .env；Webhook 数据传输默认关闭；TLS 校验默认启用，仅在自签名证书环境才建议关闭；对所有 AVI API 响应执行 _sanitize() 截断与控制字符清理以防护提示注入；建议最小权限，使用专用的 AVI 服务账号，AKO 操作仅需命名空间范围的 kubeconfig 访问。
其他限制与兼容性：pip 低于 21.3 时无法对非 setuptools 后端执行可编辑安装；企业 TLS 代理下 uvx 可能因证书问题失败，需改用 vmware-avi mcp 或设置 UV_NATIVE_TLS=true；2.0 重命名工具名后需同步更新脚本、agent 提示或 rules.yaml 中的引用。资料还列出 SDK、REST API 与 CLI 工具的官方地址，以及反馈问题可发送错误信息、日志或截图至 zhouwei008@gmail.com，欢迎贡献。
