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運用を1つのスキルで実行できます。

その他の機能には、関連スキルをご利用ください：

スキル	対象範囲	インストール
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 Namespaces、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コマンドは従来どおりです。エージェントのプロンプト、スクリプト、または~/.vmware/rules.yamlでツール名を指定している場合は、更新してください。ただし、以前の名前で記述された拒否ルールはvmware-policy ≥ 1.18で引き続き動作します（vmware-audit policyで、名前変更によって対象範囲が広がったルールを確認できます）。また、vmware-pilot ≥ 1.13では、保存済みワークフロー内の以前の名前が変換されます。 2.0より前のバージョンをインストールした環境でも同じrules.yamlを使用する場合は、vmware-policyも≥ 1.18.2にしてください。各ルールを変更前と変更後の両方の名前と照合するため、1つのファイルで両方に対応できます。

クイックインストール

# 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

機能の概要

このスキルでできること

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

Service Engine のヘルス

# 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 ではありません）。アップグレードでは 公式の Broadcom OCI チャート oci://projects.packages.broadcom.com/ako/helm-charts/ako を --reuse-values とともに取得します。

# 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 の実行後、1 つのコマンドで 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 を実行します（リリースは自動検出され、Broadcom の公式 OCI チャートが取得されます）

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 リソース定義自体（誤ったアノテーション、シークレットの不足など）にある可能性があります。vmware-avi ako ingress diagnose を使用して根本原因を特定してください。

安全機能

セキュリティの詳細

• ソースコード：github.com/vmware-skills/VMware-AVI
• 設定ファイルの内容：config.yaml には、コントローラーのアドレス、ユーザー名、AKO の設定が保存されます。パスワードやトークンは含まれません。すべてのシークレットは .env のみに保存されます
• Webhook データの範囲：デフォルトでは無効です。サードパーティへのデータ送信はありません
• TLS 検証：デフォルトで有効です。自己署名証明書を使用する環境でのみ無効にしてください
• プロンプトインジェクション保護：すべての AVI API レスポンスに対して、_sanitize() による切り詰めと制御文字の除去を行います
• 最小権限：権限を最小限に抑えた専用の AVI サービスアカウントを使用してください。AKO の操作に必要なのは、名前空間スコープの kubeconfig アクセスのみです

関連スキル

バージョンの互換性

Broadcom 公式リファレンス

• SDK: 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 で 1 つのローカルクライアントと通信し、すべてのツールを提供します。次の 2 つのオプションで変更できます （vmware-policy ≥ 1.21.0）。

HTTPS で提供すると、別のマシンにあるクライアントが接続できます。すべての呼び出し元にベアラートークンが必要です：

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 の例です。ストリーミング可能な 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}" }
    }
  }
}

• トークンがない場合、サーバーは起動しません。また、--public-name に指定した値以外の Host / Origin を拒否し、バインド前に認証されていないリクエストへ 401 を返すことを確認します。これらの名前について、クライアントが信頼する証明書を使用してください。
• 同じマシン上の TLS 終端リバースプロキシの背後で使用する場合は、--transport http --host 127.0.0.1 --public-name mcp.example.com を指定し、Authorization ヘッダーを転送してください。
• 別のマシン上のロードバランサーまたはゲートウェイの背後で使用する場合は、--transport https を維持してください（自己署名証明書でも構いません）。ロードバランサーが Host として送信するホスト名を --public-name に指定し、Authorization を転送するよう設定してください。 ヘルスプローブには GET /healthz を使用できます。このエンドポイントはトークン不要で、{"status": "ok"} のみを返します （vmware-policy ≥ 1.23.0）。
• 各リクエストに traceparent または X-Request-ID を指定すると、監査ログの行に保存されます。 vmware-audit log --correlation-id ID を実行すると、1 つのプラットフォームリクエストに関連する呼び出しを検索できます。
• 監査ログでは、各呼び出し元は token:<name> として記録されます。呼び出しは並行して実行され、それぞれが Controller（または Kubernetes コンテキスト）への独自のセッションを保持します。ターゲットごとのセッション数は最大 VMWARE_MCP_POOL_SIZE（デフォルトは 2）です。Controller セッションごとに Controller へログインします。空きセッションができるまで、呼び出しは最大 300 秒待機します。
• エンドポイントにアクセスできる全員が、このサーバーのアカウントで操作します。 トークンは呼び出し元を識別しますが、プラットフォーム上の権限は付与しません。権限レベルごとにエンドポイントを 1 つ実行してください。
• 1 つのエンドポイントを複数のユーザーやロールで共有する場合： vmware-audit roles enable を 1 回実行し、各トークンにロールを割り当てます（vmware-audit token create NAME --role reader、またはツールとターゲットを指定する roles.yaml 内のロール。vmware-policy ≥ 1.24.0）。ロールはこのエンドポイントでトークンが呼び出せるものを制限しますが、アカウントの権限を超えることはできません。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

提供されないツールは、クライアントのツール一覧に表示されません。不正な値または未知の書き込みツールが指定されると、サーバーは停止します（exit 2）。これはクライアントに提供するツールを制限するものであり、認可ではありません。そのため、アカウントには最小限の権限のみを付与してください。

詳細については、skills/vmware-avi/references/setup-guide.md の「Serving MCP over HTTPS」と「Limiting which tools are offered」を参照してください。

ライセンス

MIT