内容
<!-- mcp-name: io.github.zw008/vmware-avi -->
# VMware AVI
> **作者**: 魏周 - VMware by Broadcom — wei-wz.zhou@broadcom.com
> 本项目是由VMware工程师发起的社区驱动项目，而非官方VMware产品。
> 有关官方VMware开发工具，请参见 [developer.broadcom.com](https://developer.broadcom.com)。
中文 | [English](../README.md)
AVI（NSX Advanced Load Balancer）管理和AKO Kubernetes操作工具 - 涵盖10个类别的28种工具。
> **双模式**: 传统的AVI控制器管理 + AKO K8s操作，合二为一。
>
> **配套技能** 处理其他所有事项：
>
> | 技能 | 范围 | 安装 |
> |-------|-------|---------|
> | **[vmware-aiops](https://github.com/zw008/VMware-AIops)** | VM生命周期，部署，访客操作，集群 | `uv tool install vmware-aiops` |
> | **[vmware-monitor](https://github.com/zw008/VMware-Monitor)** | 只读：库存，健康，警报，事件 | `uv tool install vmware-monitor` |
> | **[vmware-storage](https://github.com/zw008/VMware-Storage)** | 数据存储，iSCSI，vSAN管理 | `uv tool install vmware-storage` |
> | **[vmware-vks](https://github.com/zw008/VMware-VKS)** | Tanzu命名空间，TKC集群生命周期 | `uv tool install vmware-vks` |
> | **[vmware-nsx](https://github.com/zw008/VMware-NSX)** | NSX网络：分段，网关，NAT | `uv tool install vmware-nsx-mgmt` |
> | **[vmware-nsx-security](https://github.com/zw008/VMware-NSX-Security)** | DFW防火墙规则，安全组 | `uv tool install vmware-nsx-security` |
> | **[vmware-aria](https://github.com/zw008/VMware-Aria)** | Aria Ops：指标，警报，容量 | `uv tool install vmware-aria` |
[](https://pypi.org/project/vmware-avi/)
[](https://pypi.org/project/vmware-avi/)
[](LICENSE)
[](https://clawhub.ai/skills/vmware-avi)
---
## 快速安装
```bash
# 通过uv（推荐）
uv tool install vmware-avi
# 或通过pip
pip install vmware-avi
# 中国大陆镜像
pip install vmware-avi -i https://pypi.tuna.tsinghua.edu.cn/simple
# 验证安装
vmware-avi doctor
```
---
## 功能概述
### 本工具的作用
| 类别 | 工具 | 数量 |
|----------|-------|:-----:|
| **虚拟服务** | list, status, enable/disable | 3 |
| **池成员** | pool discovery, member list, enable/disable member (drain/restore traffic) | 4 |
| **SSL证书** | list, expiry check | 2 |
| **分析** | VS metrics overview, request error logs | 2 |
| **服务引擎** | list, health check | 2 |
| **AKO Pod操作** | status, logs, restart, version info | 4 |
| **AKO配置** | values.yaml view, Helm diff, Helm upgrade | 3 |
| **Ingress诊断** | annotation validation, VS mapping, error diagnosis, fix recommendation | 4 |
| **同步诊断** | K8s-Controller comparison, inconsistency list, force resync | 3 |
| **多集群** | cluster list, cross-cluster AKO overview, AMKO status | 3 |
### CLI vs MCP：选择哪种模式
| 场景 | 推荐 | 原因 |
|----------|:-----------:|-----|
| **本地/小模型** (Ollama, Qwen) | **CLI** | ~2K tokens vs ~8K for MCP |
| **云模型** (Claude, GPT-4o) | Either | MCP gives structured JSON I/O |
| **自动化管道** | **MCP** | Type-safe parameters, structured output |
| **AKO故障排除** | **CLI** | Interactive log tailing, Helm diff output |
> **经验法则**: 对于成本效率和小模型使用CLI。对于大型模型的自动化使用MCP。
### 架构
```
用户（自然语言）
|
AI CLI工具（Claude Code / Gemini / Codex / Cursor / Trae）
| 读取SKILL.md
|
vmware-avi CLI
|--- avisdk (AVI REST API) ---> AVI控制器 ---> 虚拟服务 / 池 / 服务引擎
|--- kubectl / kubernetes ---> K8s集群 ---> AKO Pod / Ingress / 服务
```
---
## 配置
### 步骤1：创建配置文件目录
```bash
mkdir -p ~/.vmware-avi
vmware-avi init # 生成config.yaml和.env模板
chmod 600 ~/.vmware-avi/.env
```
### 步骤2：编辑config.yaml
```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`:
```bash
# AVI控制器密码
# 格式：VMWARE_AVI_{CONTROLLER_NAME_UPPER}_PASSWORD
VMWARE_AVI_PROD_AVI_PASSWORD=your-password-here
```
密码环境变量命名约定：
```
VMWARE_AVI_{CONTROLLER_NAME_UPPER}_PASSWORD
# 替换短横线为下划线，大写
# 示例：控制器 "prod-avi" -> VMWARE_AVI_PROD_AVI_PASSWORD
# 示例：控制器 "staging-alb" -> VMWARE_AVI_STAGING_ALB_PASSWORD
```
### 步骤4：验证
```bash
vmware-avi doctor # 检查控制器连接 + kubeconfig + avisdk
```
---
## CLI用法
### 虚拟服务管理
```bash
# 列出所有虚拟服务
vmware-avi vs list [--controller prod-avi]
# 检查特定VS的状态
vmware-avi vs status my-webapp-vs
# 启用/禁用VS（禁用需要双重确认）
vmware-avi vs enable my-webapp-vs
vmware-avi vs disable my-webapp-vs
```
### 池成员排水/恢复
```bash
# 列出池成员和健康状态
vmware-avi pool members my-pool
# 优雅排水（禁用）- 需要双重确认
vmware-avi pool disable my-pool 10.1.1.5
# 恢复流量（启用）
vmware-avi pool enable my-pool 10.1.1.5
```
### SSL证书过期检查
```bash
# 列出所有证书
vmware-avi ssl list
# 检查30天内到期的证书
vmware-avi ssl expiry --days 30
```
### 分析和错误日志
```bash
# VS分析：吞吐量，延迟，错误率
vmware-avi analytics my-webapp-vs
# 请求错误日志
vmware-avi logs my-webapp-vs --since 1h
```
### 服务引擎健康
```bash
# 名称，管理IP，操作状态，服务引擎组 - 状态来自serviceengine-inventory端点（合并配置和运行时）
vmware-avi se list
# 每个服务引擎的操作状态 + 连接的VS计数
vmware-avi se health
```
### AKO故障排除
```bash
# 检查AKO Pod状态
vmware-avi ako status [--context my-k8s-context]
# 查看AKO日志
vmware-avi ako logs [--tail 100] [--since 30m]
# 重启AKO Pod（双重确认）
vmware-avi ako restart
# 显示AKO版本
vmware-avi ako version
```
### AKO Helm配置管理
AKO Helm版本会自动发现（官方安装使用`helm install --generate-name`，因此版本名称不是`ako`）。升级会拉取官方Broadcom OCI图表
`oci://projects.packages.broadcom.com/ako/helm-charts/ako`，并使用`--reuse-values`。
```bash
# 查看当前AKO Helm值（自动发现版本）
vmware-avi ako config show
# 显示待更改（与官方OCI图表对比）
vmware-avi ako config diff
# Helm升级（双重确认 + --dry-run默认）
vmware-avi ako config upgrade
```
### Ingress诊断
```bash
# 验证Ingress注解
vmware-avi ako ingress check <namespace>
# 显示Ingress到VS的映射
vmware-avi ako ingress map
# 诊断Ingress为何没有VS
vmware-avi ako ingress diagnose <ingress-name>
```
### 同步诊断
```bash
# 检查K8s-控制器同步状态
vmware-avi ako sync status
# 显示K8s和控制器之间的不一致性
vmware-avi ako sync diff
# 强制AKO重新同步（双重确认）
vmware-avi ako sync force
```
### 多集群AKO
```bash
# 列出部署AKO的集群
vmware-avi ako clusters
# 跨集群AKO状态概览
vmware-avi ako cluster-overview
# AMKO GSLB状态
vmware-avi ako amko status
```
---
## MCP服务器
MCP服务器通过[模型上下文协议](https://modelcontextprotocol.io)公开所有28种工具。与任何MCP兼容的客户端配合使用。
**在`uv tool install vmware-avi`后，使用一个命令启动MCP服务器** （v1.5.15+）：
```bash
# 推荐 - 单个命令，无需网络重新解析
vmware-avi mcp
# 使用自定义配置文件路径
VMWARE_AVI_CONFIG=/path/to/config.yaml vmware-avi mcp
```
### Claude Desktop配置
添加到`claude_desktop_config.json`:
```json
{
"mcpServers": {
"vmware-avi": {
"command": "vmware-avi",
"args": ["mcp"],
"env": {
"VMWARE_AVI_CONFIG": "~/.vmware-avi/config.yaml"
}
}
}
}
```
<details>
<summary>替代方案：uvx（无需安装）或旧入口点</summary>
```bash
# 无需安装运行（每次启动都需要PyPI访问）
uvx --from vmware-avi vmware-avi mcp
# 旧入口点（仍然有效，保持向后兼容）
vmware-avi-mcp
```
> **在企业TLS代理后面？** uvx可能会因`invalid peer certificate: UnknownIssuer`而失败。
> 使用上述推荐的`vmware-avi mcp`表单（无需网络），或设置`UV_NATIVE_TLS=true`。
</details>
### MCP工具（28个）
| 类别 | 工具 |
|----------|-------|
| 虚拟服务（3） | `vs_list`, `vs_status`, `vs_toggle` |
| 池成员（4） | `pool_list`, `pool_members`, `pool_member_enable`, `pool_member_disable` |
| SSL证书（2） | `ssl_list`, `ssl_expiry_check` |
| 分析（2） | `vs_analytics`, `vs_error_logs` |
| 服务引擎（2） | `se_list`, `se_health` |
| AKO Pod（4） | `ako_status`, `ako_logs`, `ako_restart`, `ako_version` |
| AKO配置（3） | `ako_config_show`, `ako_config_diff`, `ako_config_upgrade` |
| Ingress诊断（3） | `ako_ingress_check`, `ako_ingress_map`, `ako_ingress_diagnose` |
| 同步诊断（3） | `ako_sync_status`, `ako_sync_diff`, `ako_sync_force` |
| 多集群（2） | `ako_clusters`, `ako_amko_status` |
---
## 常见工作流
### 1. 维护窗口 - 排水池成员
当将后端服务器离线进行修补时：
1. 列出池成员和健康状态
```bash
vmware-avi pool members my-pool
```
2. 禁用目标服务器（优雅排水）
```bash
vmware-avi pool disable my-pool 10.1.1.5
```
3. 监控分析以确认活动连接正在排空
```bash
vmware-avi analytics my-vs
```
4. 对服务器进行维护
5. 重新启用服务器
```bash
vmware-avi pool enable my-pool 10.1.1.5
```
6. 验证健康状态变为绿色
```bash
vmware-avi pool members my-pool
```
### 2. AKO Ingress未创建VS
当开发人员报告他们的Ingress未生成虚拟服务时：
1. 验证AKO正在运行
```bash
vmware-avi ako status
```
2. 验证Ingress注解
```bash
vmware-avi ako ingress check <namespace>
```
3. 检查K8s和控制器之间的同步状态
```bash
vmware-avi ako sync status
```
4. 如果注解错误，诊断特定的Ingress
```bash
vmware-avi ako ingress diagnose <ingress-name>
```
5. 如果检测到同步漂移，请查看差异并强制重新同步（如果需要）
```bash
vmware-avi ako sync diff
vmware-avi ako sync force
```
### 3. SSL证书过期审计
过期证书会导致中断。运行定期检查：
1. 检查30天内到期的所有证书
```bash
vmware-avi ssl expiry --days 30
```
2. 审查哪些VS使用每个过期的证书（输出包括VS映射）
3. 与证书团队计划更新
4. 更新后，验证新证书已就位
```bash
vmware-avi ssl list
```
---
## 故障排除
### "控制器无法访问"错误
1. 运行`vmware-avi doctor`以验证连接性
2. 检查`~/.vmware-avi/config.yaml`中的控制器地址和端口是否正确
3. 自签名证书：仅在隔离的实验室环境中设置`verify_ssl: false`（仅限实验室环境）
### AKO Pod处于CrashLoopBackOff状态
1. 检查日志：`vmware-avi ako logs --tail 50`
2. 常见原因：values.yaml中的控制器IP错误，AKO到控制器的网络策略阻止，过期凭证
3. 修复配置：`vmware-avi ako config show`检查，然后`vmware-avi ako config upgrade`使用纠正的值（版本自动发现；拉取官方Broadcom OCI图表）
### Ingress创建但控制器上没有VS
1. 验证注解：`vmware-avi ako ingress check <namespace>`
2. 检查AKO日志以拒绝原因：`vmware-avi ako logs --since 5m`
3. 运行同步差异：`vmware-avi ako sync diff`查看对象是否卡住
### 池成员启用后显示“down”
健康监视器可能仍失败。成员已启用但不健康。先修复后端服务，然后健康状态将自动恢复。
### SSL过期检查显示0个证书
验证控制器连接具有租户级访问权限。证书在AVI中是租户范围的。配置的用户可能只能看到他们租户范围的。可能用户仅看到他们租户中的证书。
### AKO 同步强制无效果
强制重新同步触发AKO重新协调所有K8s对象。如果漂移仍然存在，问题可能在K8s资源定义本身（错误的注解，缺少的秘密）。使用`vmware-avi ako ingress diagnose`找到根本原因。
---
## 安全功能
| 功能 | 详情 |
|---------|---------|
| **双重确认** | 破坏性操作（VS禁用，池成员禁用，AKO重启，Helm升级，强制重新同步）需要2个连续确认 |
| **默认干运行** | `ako config upgrade` 默认 `--dry-run` 模式 - 用户必须显式确认才能应用 |
| **审计追踪** | 所有操作通过`@vmware_tool`装饰器记录到`~/.vmware/audit.db` |
| **密码保护** | `.env` 文件加载带有权限检查；绝不出现在 shell 历史记录中 |
| **SSL 支持** | 自签名证书时 `verify_ssl: false` 仅限隔离实验室环境 |
| **提示注入保护** | 所有 API 来源文本截断（最多 500 个字符）并剥离 C0/C1 控制字符 |
| **输入验证** | 池名称、VS 名称、IP地址和命名空间名称在 API 调用前验证 |
### 安全详情
- **源代码**: [github.com/zw008/VMware-AVI](https://github.com/zw008/VMware-AVI)
- **配置文件内容**: `config.yaml` 存储控制器地址、用户名和AKO设置。无密码或令牌。所有机密存储在 `.env`
- **Webhook 数据范围**: 默认禁用。无第三方数据传输
- **TLS 验证**: 默认启用。自签名证书环境中仅禁用
- **提示注入保护**: `_sanitize()` 截断 + 控制字符清理所有AVI API响应
- **最小权限**: 使用专用AVI服务帐户，权限最小。AKO操作仅需要命名空间范围的kubeconfig访问权限
---
## 配套技能
| 技能 | 范围 | 工具 | 安装 |
|-------|-------|:-----:|---------|
| **[vmware-avi](https://github.com/zw008/VMware-AVI)** | AVI负载均衡器，AKO K8s操作 | 28 | `uv tool install vmware-avi` |
| **[vmware-aiops](https://github.com/zw008/VMware-AIops)** | VM生命周期，部署，访客操作，集群 | 34 | `uv tool install vmware-aiops` |
| **[vmware-monitor](https://github.com/zw008/VMware-Monitor)** | 只读监控，警报，事件 | 7 | `uv tool install vmware-monitor` |
| **[vmware-storage](https://github.com/zw008/VMware-Storage)** | 数据存储，iSCSI，vSAN | 11 | `uv tool install vmware-storage` |
| **[vmware-vks](https://github.com/zw008/VMware-VKS)** | Tanzu命名空间，TKC集群生命周期 | 20 | `uv tool install vmware-vks` |
| **[vmware-nsx](https://github.com/zw008/VMware-NSX)** | NSX分段，网关，NAT，路由 | 32 | `uv tool install vmware-nsx-mgmt` |
| **[vmware-nsx-security](https://github.com/zw008/VMware-NSX-Security)** | DFW防火墙，安全组，IDS/IPS | 20 | `uv tool install vmware-nsx-security` |
| **[vmware-aria](https://github.com/zw008/VMware-Aria)** | Aria Ops：指标，警报，容量 | 27 | `uv tool install vmware-aria` |
---
## 版本兼容性
| AVI 控制器 / 环境 | 支持 | 备注 |
|------------------------------|---------|-------|
| AVI 30.x in VCF 9.1 | ✅ 完整 | avisdk 30.x线覆盖VCF 9.1捆绑包 |
| AVI 30.x in VCF 5.1 | ✅ 完整 | 标准AVI / NSX ALB集成 |
| AVI 22.x — 31.x独立 | ✅ 完整 | 固定`avisdk>=22.1,<31.0` |
| AKO 1.10+ | ✅ 完整 | 通过AKO ConfigMap / GatewayClass进行Kubernetes集成 |
#### 官方Broadcom参考资料
- **SDKs**: <https://developer.broadcom.com/sdks> — VCF Python SDK
- **REST APIs**: <https://developer.broadcom.com/xapis> — AVI控制器REST API
- **CLI 工具**: <https://developer.broadcom.com/tools> — VCF PowerCLI 9.1
---
## 故障排除和贡献
如果您遇到任何错误或问题，请将错误消息，日志或屏幕截图发送到 **zhouwei008@gmail.com**。欢迎贡献 - 随时加入我们维护和改进该项目！
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器