vmware-avi 2.3.0__tar.gz → 2.4.0__tar.gz

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-avi",
   "displayName": "VMware AVI",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "VMware AVI (NSX ALB) load balancer plus AKO Kubernetes ops — 28 MCP tools.",
   "author": {
     "name": "Wei Zhou",

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-avi==2.3.0",
+        "vmware-avi==2.4.0",
         "vmware-avi-mcp"
       ]
     }

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-avi
-Version: 2.3.0
+Version: 2.4.0
 Summary: AVI (NSX Advanced Load Balancer) management and AKO Kubernetes operations tool
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-AVI
 Project-URL: Repository, https://github.com/vmware-skills/VMware-AVI
@@ -613,11 +613,18 @@ claude mcp add --transport http vmware-avi https://mcp.example.com:8443/mcp \
   before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
 - Behind a TLS-terminating reverse proxy on the same machine use `--transport http --host 127.0.0.1
   --public-name mcp.example.com` and pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine), list in `--public-name` the host name the balancer sends as `Host`, and have it forward `Authorization`.
+  Its health probe can use `GET /healthz`, which needs no token and returns only `{"status": "ok"}`
+  (vmware-policy ≥ 1.23.0).
+- Send `traceparent` or `X-Request-ID` with each request to have it stored on the audit row;
+  `vmware-audit log --correlation-id ID` then finds the calls behind one platform request.
 - The audit log records each caller as `token:<name>`. Calls run side by side: each holds its own session to a
   Controller (or Kubernetes context), up to `VMWARE_MCP_POOL_SIZE` (default 2) sessions per target. Each Controller
   session is a login on the Controller; a call waits at most 300 s for a free one.
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant
   nothing on the platform. Run one endpoint per privilege level.
+- **Several people or roles on one endpoint:** run `vmware-audit roles enable` once, then give each token a role (`vmware-audit token create NAME --role reader`, or a role in `roles.yaml` naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".
 
 **Offer only read tools, plus the writes you choose:**
 

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/README-CN.md

@@ -571,11 +571,17 @@ claude mcp add --transport http vmware-avi https://mcp.example.com:8443/mcp \
   证书要用客户端信任、且覆盖这些名字的证书。
 - 在同一台机器上由反向代理终结 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:<名字>`。调用并行执行：每个调用独占一个到 Controller（或 Kubernetes context）的
   会话，每个 target 最多 `VMWARE_MCP_POOL_SIZE`（默认 2）个会话。每个 Controller 会话都是在 Controller 上的一次登录；
   调用最多等待 300 秒拿到空闲会话。
 - **能连到这个端点的人，都以该 server 配置的账号操作。** token 只用来识别调用者，不在平台上授予任何权限。
   每个权限级别单独起一个端点。
+- **一个端点给多人或多种角色用：** 先运行一次 `vmware-audit roles enable`，再给每个 token 指定角色（`vmware-audit token create 名字 --role reader`，或在 `roles.yaml` 里定义可用的工具和 target；需 vmware-policy ≥ 1.24.0）。角色只能限定这个 token 在本端点上能调用什么，不能超出账号本身的权限。详见 vmware-policy README 的「网络调用者的角色」一节。
 
 **只提供读工具，加上你选定的写工具：**
 

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/README.md

@@ -591,11 +591,18 @@ claude mcp add --transport http vmware-avi https://mcp.example.com:8443/mcp \
   before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
 - Behind a TLS-terminating reverse proxy on the same machine use `--transport http --host 127.0.0.1
   --public-name mcp.example.com` and pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine), list in `--public-name` the host name the balancer sends as `Host`, and have it forward `Authorization`.
+  Its health probe can use `GET /healthz`, which needs no token and returns only `{"status": "ok"}`
+  (vmware-policy ≥ 1.23.0).
+- Send `traceparent` or `X-Request-ID` with each request to have it stored on the audit row;
+  `vmware-audit log --correlation-id ID` then finds the calls behind one platform request.
 - The audit log records each caller as `token:<name>`. Calls run side by side: each holds its own session to a
   Controller (or Kubernetes context), up to `VMWARE_MCP_POOL_SIZE` (default 2) sessions per target. Each Controller
   session is a login on the Controller; a call waits at most 300 s for a free one.
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant
   nothing on the platform. Run one endpoint per privilege level.
+- **Several people or roles on one endpoint:** run `vmware-audit roles enable` once, then give each token a role (`vmware-audit token create NAME --role reader`, or a role in `roles.yaml` naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".
 
 **Offer only read tools, plus the writes you choose:**
 

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/RELEASE_NOTES.md

@@ -1,3 +1,11 @@
+## v2.4.0 — roles for network callers (HLD §18)
+
+* Declares the role metadata vmware-policy ≥ 1.24.0 needs to apply **roles** to this server over HTTPS
+  (HLD §18): how a missing controller resolves, that tools without a `controller` argument act on the default controller, that the AKO tools act on a Kubernetes context (so a controller-limited role cannot use them), and that `diff_ako_config` and `upgrade_ako_config` escape a role (their Helm values can hold the controller password). With an older vmware-policy nothing changes. Once an operator runs
+  `vmware-audit roles enable`, a token's role decides which tools and targets it may use here; a refused call is
+  audited as `denied`. See vmware-policy's README, "Roles for network callers".
+* README and setup guide: one endpoint for several people or roles.
+
 ## v2.3.0 — calls run side by side
 
 **Calls no longer wait for each other** (HLD §16 D-13(2), via vmware-policy 1.22.0). When one server serves several

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-avi==2.3.0",
+        "vmware-avi==2.4.0",
         "vmware-avi-mcp"
       ]
     }

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/vmware-avi",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "VMware AVI (NSX ALB) load balancer plus AKO Kubernetes ops — 28 MCP tools.",
   "private": true,
   "license": "MIT",

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-avi"
-version = "2.3.0"
+version = "2.4.0"
 description = "AVI (NSX Advanced Load Balancer) management and AKO Kubernetes operations tool"
 readme = "README.md"
 license = "MIT"

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/vmware-skills/VMware-AVI",
     "source": "github"
   },
-  "version": "2.3.0",
+  "version": "2.4.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-avi",
-      "version": "2.3.0",
+      "version": "2.4.0",
       "runtimeHint": "uvx",
       "packageArguments": [
         {

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/skills/vmware-avi/SKILL.md

@@ -53,7 +53,7 @@ AVI (NSX Advanced Load Balancer) application delivery and AKO Kubernetes operati
 ## Quick Install
 
 ```bash
-uv tool install vmware-avi==2.3.0
+uv tool install vmware-avi==2.4.0
 vmware-avi doctor            # checks Controller connectivity + kubeconfig + avisdk
 ```
 
@@ -235,7 +235,7 @@ Force resync triggers AKO to re-reconcile all K8s objects. If the drift persists
 ## Setup
 
 ```bash
-uv tool install vmware-avi==2.3.0
+uv tool install vmware-avi==2.4.0
 mkdir -p ~/.vmware-avi
 vmware-avi init              # generates config.yaml and .env templates
 chmod 600 ~/.vmware-avi/.env

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/skills/vmware-avi/references/capabilities.md

@@ -37,7 +37,7 @@ All 28 MCP tools exposed by `vmware-avi mcp` (v1.5.15+; legacy entry point: `vmw
 | `vmware-avi mcp` (CLI subcommand, stdio) | ✅ Full | ✅ v1.5.15+ default — no PyPI re-resolve, works behind corporate TLS proxies. |
 | `vmware-avi-mcp` (legacy console script, stdio) | ✅ Full | Kept for backward compatibility with pre-1.5.15 configs. |
 | `python -m vmware_avi.mcp_server` (stdio, via `__main__.py`) | ✅ Full | Docker image `CMD` only — not for end-user CLI install, and no longer used by `smithery.yaml` (which now calls the `vmware-avi mcp` entry point). Added v1.5.22. |
-| `uvx --from vmware-avi==2.3.0 vmware-avi-mcp` | ⚠ Fallback | Re-resolves PyPI on each launch; fails behind corporate TLS proxies (踩坑 #25). Use `UV_NATIVE_TLS=true` workaround. |
+| `uvx --from vmware-avi==2.4.0 vmware-avi-mcp` | ⚠ Fallback | Re-resolves PyPI on each launch; fails behind corporate TLS proxies (踩坑 #25). Use `UV_NATIVE_TLS=true` workaround. |
 
 ## Automation Level Reference
 

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/skills/vmware-avi/references/setup-guide.md

@@ -21,7 +21,7 @@ Complete installation, configuration, and AI platform integration guide for the
 ### Standard Install (recommended)
 
 ```bash
-uv tool install vmware-avi==2.3.0
+uv tool install vmware-avi==2.4.0
 ```
 
 This installs the CLI (`vmware-avi`, with `vmware-avi mcp` subcommand for the MCP server in v1.5.15+), the legacy `vmware-avi-mcp` entry point (for backward compatibility), and all Python dependencies in an isolated environment.
@@ -29,7 +29,7 @@ This installs the CLI (`vmware-avi`, with `vmware-avi mcp` subcommand for the MC
 ### Development Install
 
 ```bash
-git clone --branch v2.3.0 https://github.com/vmware-skills/VMware-AVI.git
+git clone --branch v2.4.0 https://github.com/vmware-skills/VMware-AVI.git
 cd VMware-AVI
 uv pip install -e ".[dev]"
 ```
@@ -43,7 +43,7 @@ For platforms that prefer containerized MCP servers (e.g., Smithery registry, Ku
 Build and run the MCP server in a container. The image uses `python:3.12-slim` with `uv` for dependency installation and runs `python -m vmware_avi.mcp_server` on stdio (no port exposed — MCP uses stdin/stdout).
 
 ```bash
-git clone --branch v2.3.0 https://github.com/vmware-skills/VMware-AVI.git
+git clone --branch v2.4.0 https://github.com/vmware-skills/VMware-AVI.git
 cd VMware-AVI
 
 # Build
@@ -72,7 +72,7 @@ Users can install via the Smithery UI or CLI without managing Python environment
 
 | Deployment | Best For |
 |------------|----------|
-| `uv tool install vmware-avi==2.3.0` + `vmware-avi mcp` | Local developer workstation, single-user CLI + MCP |
+| `uv tool install vmware-avi==2.4.0` + `vmware-avi mcp` | Local developer workstation, single-user CLI + MCP |
 | Docker image | Self-hosted agents, CI runners, isolated environments, multi-user servers |
 | Smithery | Zero-install agent integration, registry-managed discovery, hosted-MCP workflows |
 
@@ -257,6 +257,13 @@ vmware-avi mcp --transport https --host 0.0.0.0 --port 8443 \
 - Behind a reverse proxy that terminates TLS (Nginx, HAProxy) on the same machine, use
   `--transport http --host 127.0.0.1 --public-name mcp.example.com` (the names the proxy forwards in `Host`), and
   have the proxy pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine: the balancer is the client that has to trust it), list in `--public-name` the host name the balancer sends
+  as `Host`, and have it forward `Authorization`. Point its health probe at `GET /healthz`: it needs no token, returns
+  only `{"status": "ok"}` and accepts any `Host` (vmware-policy ≥ 1.23.0). Every other path still needs the token.
+- Correlation: each audit row stores the caller's `traceparent` trace-id, else its `X-Request-ID` /
+  `X-Correlation-ID`. Have the agent platform send one, and `vmware-audit log --correlation-id ID` lists the calls
+  behind one platform request.
 - `vmware-audit token list` / `token revoke NAME` manage callers; a revoked token is refused from its next request.
   Replace a leaked token under a new name.
 - The server will not start without at least one token, and checks before it binds that unauthenticated requests
@@ -267,6 +274,7 @@ vmware-avi mcp --transport https --host 0.0.0.0 --port 8443 \
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant
   nothing on the platform. Run one endpoint per privilege level (for example a read-only account behind
   `--expose read`, and a separate endpoint for operators).
+- **Several people or roles on one endpoint:** run `vmware-audit roles enable` once, then give each token a role (`vmware-audit token create NAME --role reader`, or a role in `roles.yaml` naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".
 
 ## Security
 

vmware_avi-2.4.0/tests/test_policy_roles.py

@@ -0,0 +1,69 @@
+"""HLD §18: the role metadata this skill declares matches its real tools."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from vmware_avi import policy_roles
+
+
+def _registry() -> set[str]:
+    from vmware_avi.mcp_server.server import mcp
+
+    return {t.name for t in asyncio.run(mcp.list_tools())}
+
+
+@pytest.mark.unit
+def test_every_declared_name_is_a_real_tool():
+    named = set(policy_roles.ESCAPES) | set(getattr(policy_roles, "AKO_TOOLS", ()))
+    assert named - _registry() == set(), sorted(named - _registry())
+
+
+@pytest.mark.unit
+def test_metadata_is_declared_when_policy_has_roles():
+    roles = pytest.importorskip("vmware_policy.roles")
+    import vmware_avi.mcp_server.server  # noqa: F401  (registers the metadata on import)
+
+    meta = roles.metadata("avi")
+    assert meta is not None and meta.version == 1
+    assert meta.escapes == policy_roles.ESCAPES
+    assert (meta.resolver is not None) is True
+
+
+#: Reviewed: these act on the default Controller (``untagged_scope="one"``).
+_DEFAULT_CONTROLLER_TOOLS = frozenset(
+    {
+        "check_ssl_cert_expiry",
+        "disable_lb_pool_member",
+        "enable_lb_pool_member",
+        "get_service_engine_health",
+        "get_virtual_service_analytics",
+        "get_virtual_service_error_logs",
+        "get_virtual_service_status",
+        "list_lb_pool_members",
+        "list_lb_pools",
+        "list_service_engines",
+        "list_ssl_certs",
+        "set_virtual_service_enabled",
+    }
+)
+
+
+@pytest.mark.unit
+def test_every_tool_without_a_controller_argument_is_classified():
+    """Review L1: a new Kubernetes tool must not inherit 'acts on the default Controller'."""
+    from vmware_avi.mcp_server.server import mcp
+
+    untargeted = {
+        t.name
+        for t in asyncio.run(mcp.list_tools())
+        if "controller" not in (t.inputSchema.get("properties") or {})
+    }
+    unclassified = untargeted - policy_roles.AKO_TOOLS - _DEFAULT_CONTROLLER_TOOLS
+    assert not unclassified, (
+        f"add to policy_roles.AKO_TOOLS (acts on Kubernetes) or to the reviewed "
+        f"default-Controller list here: {sorted(unclassified)}"
+    )
+    assert not (_DEFAULT_CONTROLLER_TOOLS - untargeted), "reviewed list names a stale tool"

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/uv.lock

@@ -1423,7 +1423,7 @@ wheels = [
 
 [[package]]
 name = "vmware-avi"
-version = "2.3.0"
+version = "2.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "avisdk" },
@@ -1466,16 +1466,16 @@ dev = [
 
 [[package]]
 name = "vmware-policy"
-version = "1.22.0"
+version = "1.24.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "pyyaml" },
     { name = "rich" },
     { name = "typer" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/d7/52/405a9d5e88d79649f4d7bddade8248f38ab6a508007a7500a3cdcf81897a/vmware_policy-1.22.0.tar.gz", hash = "sha256:e1a96b44ddf3c4d00fb8bdcaae4e1a059b03f343a84df9de23f865122d3dc280", size = 319890, upload-time = "2026-10-15T14:39:45.757Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/4a/62/3a3cb83af77e3dd3c8fc92cb3b7968bfda04a2f71bf0d6f9b72ee3198441/vmware_policy-1.24.0.tar.gz", hash = "sha256:fba12732ccbd4371232c15d9fd014f9f5d697497210aedff2515d1d205ed3577", size = 361302, upload-time = "2026-10-16T07:18:28.317Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/73/b5/2536cc8750c3ecb0a57c573def664989642ccae1a4f4a8b4283e34877721/vmware_policy-1.22.0-py3-none-any.whl", hash = "sha256:ca8afc5731e926b5eb1b93e26e14763b477bd45c33d3808138fb72903e2af664", size = 108585, upload-time = "2026-10-15T14:39:43.888Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/f2/fe3d9d384712023916e2cacddc385f14b095509c5e00aea417d1a9550e98/vmware_policy-1.24.0-py3-none-any.whl", hash = "sha256:cf615d0256134f01fb84c39b083649281a66d2c064c2eaa28786a0fa95ec6e58", size = 131460, upload-time = "2026-10-16T07:18:26.907Z" },
 ]
 
 [[package]]

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/vmware_avi/__init__.py

@@ -1,3 +1,3 @@
 """VMware AVI - AVI (NSX ALB) management and AKO Kubernetes operations."""
 
-__version__ = "2.3.0"
+__version__ = "2.4.0"

{vmware_avi-2.3.0 → vmware_avi-2.4.0}/vmware_avi/policy_environment.py

@@ -54,3 +54,7 @@ def _environment_for(target: str | None) -> str:
 # to ALLOW. Keyed, a resolver only ever answers for its own skill, so
 # registering at import time is safe again.
 set_environment_resolver(_environment_for, skill=skill_name(__name__))
+
+
+# Role metadata (HLD §18) is declared beside the environment resolver, on every surface.
+import vmware_avi.policy_roles  # noqa: E402,F401

vmware_avi-2.4.0/vmware_avi/policy_roles.py

@@ -0,0 +1,69 @@
+"""What vmware-policy needs to apply roles to this skill (HLD §18 D-21/D-22).
+
+Policy cannot see which tools escape a role or how a missing target resolves; this
+module declares them. Imported by ``policy_environment``, so the MCP server and
+the CLI both register it. With a vmware-policy that has no roles module (< 1.24)
+nothing is declared.
+"""
+
+from __future__ import annotations
+
+from vmware_policy import skill_name
+
+from vmware_avi.policy_environment import _cached_config
+
+#: AKO tools act on a Kubernetes context, not on an AVI controller target, so a
+#: controller-limited role cannot use them (scope "all"). Every other tool without a
+#: ``controller`` argument acts on the default controller (``untagged_scope="one"``).
+AKO_TOOLS = frozenset(
+    {
+        "check_ako_ingress",
+        "diagnose_ako_ingress",
+        "diff_ako_config",
+        "diff_ako_sync",
+        "force_ako_sync",
+        "get_ako_amko_status",
+        "get_ako_config",
+        "get_ako_logs",
+        "get_ako_status",
+        "get_ako_sync_status",
+        "get_ako_version",
+        "list_ako_clusters",
+        "list_ako_ingresses",
+        "restart_ako",
+        "upgrade_ako_config",
+    }
+)
+
+#: Tools that give their holder more than a role. The AKO config tools return Helm
+#: values that can hold the controller password. ``get_ako_config`` is not one: it
+#: redacts credential values and withholds output it cannot redact. Host-path tools
+#: are added by policy while a file root is set.
+ESCAPES = frozenset(
+    {
+        "diff_ako_config",
+        "upgrade_ako_config",
+    }
+)
+
+
+def _target_name(target: str | None) -> str:
+    """The target the connection layer would use for ``target`` (or the default)."""
+    config = _cached_config()
+    return (config.get_controller(target) if target else config.active_controller).name
+
+
+try:
+    from vmware_policy.roles import declare_role_metadata
+except ImportError:  # vmware-policy without roles: nothing to declare
+    declare_role_metadata = None
+
+if declare_role_metadata is not None:
+    declare_role_metadata(
+        skill_name(__name__),
+        escapes=ESCAPES,
+        resolver=_target_name,
+        target_param="controller",
+        untagged_scope="one",
+        target_scope={name: "all" for name in AKO_TOOLS},
+    )