VMware-AVI

Purpose

VMware AVI is a tool for managing AVI (NSX Advanced Load Balancer) and performing AKO Kubernetes operations. The author is Wei Zhou of VMware by Broadcom. It is a community-driven project and not an official VMware product. It covers two workflows at the same time: traditional AVI Controller management and AKO K8s operations, providing a total of 28 tools across 10 categories.

Main Capabilities

The tools are organized around the following categories: virtual service management, pool member drain/restore, SSL certificate expiration checks, analytics and error logs, Service Engine health, AKO troubleshooting, AKO Helm configuration management, Ingress diagnostics, sync diagnostics, and multi-cluster AKO.

For AKO Helm configuration, the AKO Helm release is automatically discovered; the official installation uses helm install --generate-name, so the release is not named ako. During upgrades, the official Broadcom OCI chart is pulled:oci://projects.packages.broadcom.com/ako/helm-charts/ako, and --reuse-valuesis used.

The MCP server exposes all 28 tools through the Model Context Protocol, is compatible with any MCP-capable client, and can be used for structured automation.

Usage

The tools provide two modes: CLI and MCP. The rule of thumb given in the materials is: use CLI when pursuing cost efficiency and using small models; use MCP when using large models for structured automation.

Configuration steps:

1. Create the configuration directory;
2. Edit config.yaml;
3. Set the password, create ~/.vmware-avi/.env, and the password environment variable follows the naming convention.

Installation: the project uses the PEP 517 build system (hatchling), so the absence of setup.py is by design. If an older pip (below 21.3) is used to install a non-setuptools backend project in editable mode (-e), an error will occur. Editable mode is only a development convenience and is not required to run the tools. For fully air-gapped hosts, wheels can first be built on a networked machine and then copied over; the target machine does not need network access.

After installation, the MCP server can be started with a single command (v1.5.15+), and the Claude Desktop configuration can include claude_desktop_config.json. If behind an enterprise TLS proxy, uvx may report invalid peer certificate: UnknownIssuer. It is recommended to use the recommended vmware-avi mcp form (no network required), or set UV_NATIVE_TLS=true.

Changes in Version 2.0

2.0 renamed all 28 MCP tools so that each name starts with a verb, for example ako_amko_status → get_ako_amko_status，ako_clusters → list_ako_clusters，ako_config_diff → diff_ako_config. The complete old-to-new comparison table is in RELEASE_NOTES.md. Apart from the names, the tools, parameters, security gating, and CLI commands are unchanged. If tool names are referenced in agent prompts, scripts, or ~/.vmware/rules.yaml , they need to be updated. Deny rules written using the old names still work under vmware-policy ≥ 1.18 (vmware-audit policy will list rules expanded due to the rename), and vmware-pilot ≥ 1.13 will convert old names in saved workflows. If an old installation sharing the same rules.yaml predates 2.0, it is also recommended to use vmware-policy ≥ 1.18.2, because it matches both the old and new names for each rule, so one file can serve both versions.

Common Workflows

Maintenance window - draining pool members: list pool members and health status (vmware-avi pool members my-pool) → disable the target server for graceful draining (vmware-avi pool disable my-pool 10.1.1.5) → monitor analytics to confirm that active connections are draining (vmware-avi analytics my-vs) → perform maintenance on the server → re-enable the server (vmware-avi pool enable my-pool 10.1.1.5) → verify that the health status is green.

AKO Ingress did not create a VS: verify that AKO is running (vmware-avi ako status) → validate the Ingress annotations (vmware-avi ako ingress check <namespace>) → check the sync status between K8s and the Controller (vmware-avi ako sync status) → if the annotations are incorrect, diagnose the specific Ingress (vmware-avi ako ingress diagnose <ingress-name>) → If synchronization drift is detected, review the diff and force a resync if needed (vmware-avi ako sync diff、vmware-avi ako sync force).

SSL certificate expiration audit: check all certificates expiring within 30 days (vmware-avi ssl expiry --days 30) → see which VS each expiring certificate is used by (output includes VS mapping) → plan renewal with the certificate team → after renewal, verify the new certificate is in place (vmware-avi ssl list).

Troubleshooting

• "Controller unreachable": run vmware-avi doctor to verify connectivity; check the controller address and port in ~/.vmware-avi/config.yaml ; for self-signed certificates, you can set verify_ssl: false(lab environments only).
• AKO Pod in CrashLoopBackOff: check the logs vmware-avi ako logs --tail 50; common causes are an incorrect controller IP in values.yaml, network policies blocking AKO from accessing the Controller, or expired credentials; check the configuration vmware-avi ako config show, then run vmware-avi ako config upgradewith the corrected values (release auto-discovery, pulls the official Broadcom OCI chart).
• Ingress created but no VS on the Controller: verify the annotation vmware-avi ako ingress check <namespace>; check the rejection reason in the AKO logs vmware-avi ako logs --since 5m; run vmware-avi ako sync diff to see whether the object is stuck.
• Pool member shows "down" after enable: health monitoring may still be failing; the member is enabled but unhealthy. Check the actual health status on the Controller side, fix the backend service first, and the health status will recover automatically.
• SSL expiration check shows 0 certificates: confirm that the controller connection has tenant-level access permissions; certificates in AVI are tenant-scoped, and the configured user may only be able to see certificates within their tenant.
• ako sync force invalid: forcing a resync triggers AKO to reconcile all K8s objects; if the drift still exists, the problem may be in the K8s resource definition itself (incorrect annotation, missing Secret), and you can use vmware-avi ako ingress diagnose to locate the root cause.

Scope and Limitations

This tool is intended for AVI (NSX Advanced Load Balancer) and AKO Kubernetes operations scenarios, and is suitable for switching between traditional Controller management and K8s Ingress/AKO operations. Security design includes: the configuration file config.yaml stores only the controller address, username, and AKO settings, not passwords or tokens; all secrets are stored only in .env; Webhook data transmission is disabled by default; TLS verification is enabled by default and is only recommended to be disabled in self-signed certificate environments; _sanitize() truncation and control character sanitization are performed on all AVI API responses to protect against prompt injection; least privilege is recommended, using a dedicated AVI service account, and AKO operations require only namespace-scoped kubeconfig access.

Other limitations and compatibility: pip below 21.3 cannot perform editable installs for non-setuptools backends; under enterprise TLS proxies, uvx may fail due to certificate issues, and you need to switch to vmware-avi mcp or set UV_NATIVE_TLS=true; after the tool name was renamed in 2.0, references in scripts, agent prompts, or rules.yaml must be updated accordingly. The material also lists the official addresses for the SDK, REST API, and CLI tools, and for feedback you can send error messages, logs, or screenshots to zhouwei008@gmail.com; contributions are welcome.