Condividi tramite

Connettere il cluster del servizio Azure Kubernetes agli agenti di intelligenza artificiale usando il server MCP (Model Context Protocol)

Il server MCP (Model Context Protocol) del servizio Azure Kubernetes consente agli assistenti di intelligenza artificiale di interagire con i cluster del servizio Azure Kubernetes con chiarezza, sicurezza e controllo. Funge da ponte tra gli strumenti di intelligenza artificiale (ad esempio GitHub Copilot, Claude e altri assistenti di intelligenza artificiale compatibili con MCP) e il servizio Azure Kubernetes, traducendo le richieste in linguaggio naturale nelle operazioni del servizio Azure Kubernetes e restituendo i risultati in un formato comprensibile degli strumenti di intelligenza artificiale.

Il server MCP del servizio Azure Kubernetes si connette ad Azure usando Azure SDK e fornisce un set di strumenti che gli assistenti di intelligenza artificiale possono usare per interagire con le risorse del servizio Azure Kubernetes. Questi strumenti consentono agli agenti di intelligenza artificiale di eseguire attività come:

  • Risoluzione dei problemi e diagnostica
  • Analizzare lo stato di salute del cluster
  • Operare le risorse AKS (CRUD)
  • Ottenere i dettagli correlati ai cluster AKS (reti virtuali, subnet, gruppi di sicurezza di rete (NSG), tabelle di routing, ecc.).
  • Abilitazione delle procedure consigliate e delle funzionalità consigliate
  • Gestire le operazioni della flotta di Azure per scenari multi-cluster

Il server MCP di AKS è un progetto completamente open source, con modelli di esempio e configurazioni Helm disponibili nel repository GitHub.

Quando usare il server MCP di AKS (Azure Kubernetes Service)

Il server MCP di AKS può essere utilizzato con qualsiasi assistente di intelligenza artificiale compatibile, inclusa la CLI agente per AKS e Microsoft Copilot. I casi d'uso comuni includono:

  • Porre domande sugli assistenti di intelligenza artificiale, ad esempio:
    • "Perché i pod sono in sospeso in questo cluster?"
    • Qual è la configurazione di rete del mio cluster AKS?
    • "Creare un posizionamento per distribuire carichi di lavoro nginx nei cluster con l'etichetta app=frontend".
  • Consentire agli strumenti di intelligenza artificiale di:
    • Leggere lo stato e la configurazione del cluster
    • Esaminare metriche, eventi e log
    • Correlare i segnali tra Kubernetes e le risorse di Azure
    • Applicare le modifiche e abilitare nuove funzionalità direttamente nel cluster

Tutte le azioni eseguite tramite il server MCP di Azure Kubernetes sono vincolate dal controllo degli accessi basato sui ruoli di Kubernetes (RBAC) e di Azure (RBAC Azure). Per impostazione predefinita, il server MCP del servizio Azure Kubernetes eredita le autorizzazioni dell'utente durante l'accesso alle risorse del cluster e di Azure. Per personalizzare i ruoli e le autorizzazioni del server MCP del servizio Azure Kubernetes, distribuire la modalità server MCP del servizio Azure Kubernetes remota con il controllo RBAC predefinito.

Strumenti disponibili

Il server MCP del servizio Azure Kubernetes offre un set completo di strumenti per interagire con i cluster del servizio Azure Kubernetes e le risorse associate. Per impostazione predefinita, il server usa strumenti unificati (call_az per le operazioni di Azure e call_kubectl per le operazioni Kubernetes) che offrono un'interfaccia più flessibile per interagire con Kubernetes e le risorse di Azure.

Sono disponibili tre set di autorizzazioni che è possibile abilitare per il server MCP del servizio Azure Kubernetes: sola lettura (impostazione predefinita), lettura/scrittura e amministratore. Alcuni strumenti richiedono autorizzazioni di lettura/scrittura o amministratore per eseguire azioni come la distribuzione di pod di debug o azioni CRUD nel cluster. Per abilitare le autorizzazioni di lettura/scrittura o amministratore per il server AKS-MCP, aggiungere il parametro del livello di accesso al file di configurazione MCP:

  1. Passare al file mcp.json oppure passare a MCP: Elenca server -> AKS-MCP -> Mostra dettagli di configurazione nel riquadro comandi (per VS Code; Ctrl+Shift+P in Windows/Linux o Cmd+Shift+P in macOS).
  2. Nella sezione "args" di AKS-MCP aggiungere i parametri seguenti: "--access-level", "readwrite" o "admin"

Per esempio:

"args": [
  "--transport",
  "stdio",
  "--access-level",
  "readwrite"
]

Questi strumenti sono progettati per offrire funzionalità complete tramite interfacce unificate:

Operazioni dell'interfaccia della riga di comando di Azure (strumento unificato)

Strumento:call_az

Strumento unificato per l'esecuzione diretta dei comandi dell'interfaccia della riga di comando di Azure. Questo strumento fornisce un'interfaccia flessibile per eseguire qualsiasi comando dell'interfaccia della riga di comando di Azure.

Parametri:

  • cli_command: comando completo della CLI di Azure da eseguire. Ad esempio, az aks list --resource-group myRG o az vm list --subscription <sub-id>.
  • timeout: timeout opzionale in secondi (valore predefinito: 120)

Esempio di utilizzo:

{
  "cli_command": "az aks list --resource-group myResourceGroup --output json"
}

Controllo di accesso:

  • readonly: sono consentite solo operazioni di lettura
  • readwrite/admin: sono consentite operazioni di lettura e scrittura

Importante

I comandi devono essere semplici chiamate dell'interfaccia della riga di comando di Azure senza funzionalità della shell come pipe (|), reindirizzamenti (>, <), sostituzione dei comandi o punto e virgola (;).

Operazioni Kubernetes (strumento unificato)

Strumento kubectl unificato

Strumento:call_kubectl

Strumento unificato per l'esecuzione diretta di comandi kubectl. Questo strumento fornisce un'interfaccia flessibile per eseguire qualsiasi kubectl comando con supporto completo degli argomenti.

Parametri:

  • args: argomenti del comando kubectl. Ad esempio, get pods, describe node mynode o apply -f deployment.yaml.

Esempio di utilizzo:

{
  "args": "get pods -n kube-system -o wide"
}

Controllo di accesso: Le operazioni sono limitate in base al livello di accesso configurato:

  • readonly: sono consentite solo operazioni di lettura (get, describe, logs e così via)
  • readwrite/admin: tutte le operazioni, inclusi i comandi di modifica (creazione, eliminazione, applicazione e così via)

Helm

Strumento:call_helm

Gestione pacchetti Helm per Kubernetes.

Cilium

Strumento:call_cilium

Interfaccia della riga di comando di Cilium per la sicurezza e la rete basata su eBPF.

Hubble

Strumento:call_hubble

Osservabilità della rete hubble per Cilium.

Gestione risorse di rete

Strumento:aks_network_resources

Strumento unificato per ottenere informazioni sulle risorse di rete di Azure usate dai cluster di AKS.

Tipi di risorse disponibili:

  • all: ottenere informazioni su tutte le risorse di rete
  • vnet: informazioni sulla rete virtuale
  • subnet: informazioni sulla subrete
  • nsg: informazioni sul gruppo di sicurezza di rete
  • route_table: informazioni sulla tabella di routing
  • load_balancer: informazioni sul servizio di bilanciamento del carico
  • private_endpoint: informazioni sull'endpoint privato
Monitoraggio e diagnostica

Strumento:aks_monitoring

Strumento unificato per le operazioni di monitoraggio e diagnostica di Azure per i cluster AKS.

Operazioni disponibili:

  • metrics: elencare i valori delle metriche per le risorse
  • resource_health: ottenere gli eventi di integrità delle risorse per i cluster AKS
  • app_insights: eseguire query KQL sui dati di telemetria di Application Insights
  • diagnostics: Controllare se il cluster AKS ha impostazioni diagnostiche configurate
  • control_plane_logs: eseguire query sui log del piano di controllo AKS con vincoli di sicurezza e convalida dell'intervallo temporale
Risorse di calcolo

Strumento:get_aks_vmss_info

  • Ottenere una configurazione dettagliata dei Set di Scalabilità delle Macchine Virtuali (pool di nodi) nel cluster AKS.
Gestione della flotta

Strumento:az_fleet

Gestione completa della flotta di Azure per scenari multi-cluster.

Operazioni disponibili:

  • Operazioni della flotta: list, show, create, update, delete, ottieni credenziali
  • Operazioni del membro: elenca, mostra, crea, aggiorna, elimina
  • Aggiornare le operazioni di esecuzione: elenco, visualizzazione, creazione, avvio, arresto, eliminazione
  • Operazioni di strategia di aggiornamento: elenco, visualizzazione, creazione, eliminazione
  • Operazioni ClusterResourcePlacement: elencare, mostrare, ottenere, creare, eliminare

Supporta sia la gestione della flotta di Azure che le operazioni CRD di Kubernetes ClusterResourcePlacement.

Rilevatori di diagnostica

Strumento:aks_detector

Strumento unificato per eseguire operazioni del detector diagnostico AKS.

Operazioni disponibili:

  • list: elenca tutti i rilevatori di cluster AKS disponibili
  • run: eseguire un detettore diagnostico specifico per AKS
  • run_by_category: eseguire tutti i rilevatori in una categoria specifica

Parametri:

  • operation (obbligatorio): operazione da eseguire (list, runo run_by_category)
  • aks_resource_id (obbligatorio): ID risorsa cluster del servizio Azure Kubernetes
  • detector_name (obbligatorio per run l'operazione): nome del rilevatore da eseguire
  • category (necessario per l'operazione di run_by_category): categoria rilevatore
  • start_time (obbligatorio per run le operazioni e run_by_category ): ora di inizio in formato ISO UTC (negli ultimi 30 giorni)
  • end_time (obbligatorio per run le operazioni e run_by_category ): ora di fine in formato ISO UTC (negli ultimi 30 giorni, massimo 24 ore dall'inizio)

Categorie disponibili:

  • Migliori pratiche
  • Disponibilità e prestazioni del piano di controllo e del cluster
  • Problemi di connettività
  • Creare, aggiornare, eliminare e ridimensionare
  • Elementi deprecati
  • Identità e sicurezza
  • Integrità nodo
  • Storage

Esempio di utilizzo:

Strumento:run_detectors_by_category

{
  "operation": "list",
  "aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx"
}

{
  "operation": "run",
  "aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx",
  "detector_name": "node-health-detector",
  "start_time": "2025-01-15T10:00:00Z",
  "end_time": "2025-01-15T12:00:00Z"
}
Azure Advisor

Strumento:aks_advisor_recommendation

Recuperare e gestire i consigli di Azure Advisor per i cluster AKS.

Operazioni disponibili:

  • list: elencare le raccomandazioni con le opzioni di filtro
  • report: Generare rapporti di raccomandazione
  • Opzioni filtro: resource_group, cluster_names, categoria (Costo, HighAvailability, Prestazioni, Sicurezza), gravità (Alto, Medio, Basso)
Osservabilità in tempo reale

Strumento:inspektor_gadget_observability

Strumento di osservabilità in tempo reale per i cluster del servizio Azure Kubernetes usando eBPF.

Azioni disponibili:

  • deploy: distribuire Inspektor Gadget nel cluster
  • undeploy: Rimuovere l'ispettore Gadget dal cluster
  • is_deployed: controllare lo stato della distribuzione
  • run: eseguire gadget a singolo uso
  • start: avviare gadget continui
  • stop: arresta l'esecuzione di widget
  • get_results: recuperare i risultati dei gadget
  • list_gadgets: Elenca i gadget disponibili

Gadget disponibili:

  • observe_dns: monitorare le richieste e le risposte DNS
  • observe_tcp: monitorare le connessioni TCP
  • observe_file_open: monitorare le operazioni del file system
  • observe_process_execution: monitorare l'esecuzione del processo
  • observe_signal: monitorare il recapito dei segnali
  • observe_system_calls: monitorare le chiamate di sistema
  • top_file: file principali per operazioni di I/O
  • top_tcp: connessioni TCP principali per traffico
  • tcpdump: Acquisizione di pacchetti di rete

Introduzione al server MCP di AKS

Il server AKS MCP ha due modalità: locale e remoto. In questa sezione vengono illustrati i casi d'uso e i processi di installazione per entrambe le modalità.

Server MCP locale

In modalità locale, il server MCP viene eseguito nel computer locale di uno sviluppatore e si connette al servizio Azure Kubernetes usando le autorizzazioni esistenti dello sviluppatore. Questa modalità è ideale per configurare rapidamente il tuo agente AI locale con esperienza e strumenti di AKS, in assenza di componenti lato cluster. La modalità locale può utilizzare il contesto del cluster corrente e applica le autorizzazioni Kubernetes e le RBAC di Azure dello sviluppatore. Per impostazione predefinita, il server MCP del servizio Azure Kubernetes locale supporta le modalità di trasporto STDIO e SSE.

Prerequisiti

Prima di installare il server MCP di AKS, configurare l'Azure CLI ed eseguire l'autenticazione:

az login

Il modo più semplice per iniziare a usare AKS-MCP consiste nell'usare l'estensione del servizio Azure Kubernetes per VS Code. L'estensione del servizio Azure Kubernetes gestisce automaticamente i download binari, gli aggiornamenti e la configurazione, assicurandosi di avere sempre la versione più recente con impostazioni ottimali.

Passaggio 1: Installare l'estensione AKS

  1. Aprire VS Code e passare a Estensioni (Ctrl+Shift+X in Windows/Linux o Cmd+Shift+X in macOS).
  2. Cercare il servizio Azure Kubernetes.
  3. Installare l'estensione ufficiale Microsoft AKS.

Passaggio 2: Avviare il server AKS-MCP

  1. Aprire il riquadro comandi (Ctrl+Shift+P in Windows/Linux o Cmd+Shift+P in macOS).
  2. Cercare ed eseguire: AKS: Configurare il server MCP AKS.

Al termine dell'installazione, il server viene visualizzato in MCP: Elenco server (tramite Palette dei comandi). Da qui è possibile avviare il server MCP o visualizzarne lo stato.

Passaggio 3: Iniziare a usare AKS-MCP

Dopo l'avvio, il server MCP viene visualizzato nell'elenco a discesa Copilot Chat: Configure Tools in MCP Server: AKS MCP, pronto per migliorare le richieste contestuali in base al tuo ambiente AKS. Per impostazione predefinita, tutti gli strumenti server AKS-MCP sono abilitati. È possibile esaminare l'elenco degli strumenti disponibili e disabilitare qualsiasi elemento non necessario per lo scenario in uso.

Provare un prompt come "Elenca tutti i miei cluster AKS" per iniziare a usare gli strumenti dal server AKS-MCP.

Suggerimento

Configurazione WSL: se si usa VS Code in Windows con WSL, usare "command": "wsl" per richiamare il file binario WSL. Se VS Code è in esecuzione in WSL (Remote-WSL), chiamare direttamente il file binario o usare un wrapper bash.

Server MCP remoto

In modalità remota, il server MCP viene eseguito come carico di lavoro all'interno del cluster AKS o su qualsiasi risorsa computazionale a tua scelta. Questa modalità è ideale per gli ambienti di produzione con strumenti condivisi, autorizzazioni coerenti tra gli utenti e controllo di accesso completo usando Kubernetes ServiceAccount e Identità del carico di lavoro. Il server MCP del servizio Azure Kubernetes remoto usa il protocollo HTTP per facilitare le interazioni tra assistente intelligenza artificiale e cluster del servizio Azure Kubernetes.

Prerequisiti

  • Cluster AKS con Kubernetes 1.19+
  • Helm 3.8+
  • CLI di Azure installata e autenticata (az login)

Eseguire l'installazione con l'Helm Chart

Clonare il repository e installare il grafico Helm AKS-MCP:

git clone https://github.com/Azure/aks-mcp.git
cd aks-mcp/chart

helm install aks-mcp . --namespace aks-mcp --create-namespace

Per l'elenco completo dei parametri di configurazione, vedere la documentazione del grafico Helm.

Configurare l'autenticazione

Scegliere un metodo di autenticazione in base ai requisiti di sicurezza e dell'ambiente:

L'identità del carico di lavoro fornisce l'autenticazione senza password collegando un account del servizio Kubernetes a un'identità gestita di Azure.

1. Abilitare OIDC nel cluster AKS

az aks update \
  --resource-group <your-resource-group> \
  --name <your-aks-cluster> \
  --enable-oidc-issuer \
  --enable-workload-identity

2. Creare un'identità gestita e conferire le autorizzazioni RBAC

# Create identity
az identity create --resource-group <your-resource-group> --name aks-mcp-identity --location <your-location>

# Get IDs
IDENTITY_CLIENT_ID=$(az identity show --resource-group <your-resource-group> --name aks-mcp-identity --query "clientId" -o tsv)
IDENTITY_PRINCIPAL_ID=$(az identity show --resource-group <your-resource-group> --name aks-mcp-identity --query "principalId" -o tsv)

# Assign Reader role (use Contributor for readwrite access)
az role assignment create --role "Reader" --assignee-object-id $IDENTITY_PRINCIPAL_ID --assignee-principal-type ServicePrincipal --scope "/subscriptions/<subscription-id>"

3. Creare credenziali di identità federate

AKS_OIDC_ISSUER=$(az aks show --resource-group <your-resource-group> --name <your-aks-cluster> --query "oidcIssuerProfile.issuerUrl" -o tsv)

az identity federated-credential create \
  --name "aks-mcp-federated-credential" \
  --identity-name aks-mcp-identity \
  --resource-group <your-resource-group> \
  --issuer $AKS_OIDC_ISSUER \
  --subject "system:serviceaccount:aks-mcp:aks-mcp" \
  --audience api://AzureADTokenExchange

Importante

Creare le credenziali federate prima di installare il grafico Helm.

4. Installare con Workload Identity abilitata

helm install aks-mcp . \
  --namespace aks-mcp \
  --create-namespace \
  --set workloadIdentity.enabled=true \
  --set azure.clientId=$IDENTITY_CLIENT_ID \
  --set azure.subscriptionId=<your-subscription-id>

Abilitare l'ingresso con il routing delle app di Azure

Esporre il server MCP esternamente tramite Routing app di Azure:

# Enable App Routing on your cluster
az aks approuting enable --resource-group <your-resource-group> --name <your-cluster-name>

# Install with Ingress enabled
helm install aks-mcp . \
  --namespace aks-mcp \
  --create-namespace \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=aks-mcp.example.com \
  --set ingress.hosts[0].paths[0].path=/ \
  --set ingress.hosts[0].paths[0].pathType=Prefix \
  --set azure.existingSecret=azure-credentials

Connettere il client MCP

Dopo la distribuzione, connettere l'assistente di intelligenza artificiale al server MCP remoto:

# Port forward for local testing
kubectl port-forward svc/aks-mcp 8000:8000 -n aks-mcp

Configurare il client MCP per la connessione:

{
  "mcpServers": {
    "aks-mcp": {
      "url": "http://localhost:8000",
      "transport": "streamable-http"
    }
  }
}

Per l'accesso in cluster, usare: http://aks-mcp.aks-mcp.svc.cluster.local:8000

Informazioni di riferimento sulla configurazione Helm

Parametro Descrzione Impostazione predefinita
workloadIdentity.enabled Abilitare l'identità del carico di lavoro di Azure false
azure.clientId Azure Client ID ""
azure.tenantId ID tenant di Azure ""
azure.clientSecret Segreto client di Azure ""
azure.subscriptionId ID dell'Abbonamento Azure ""
azure.existingSecret Usare un segreto Kubernetes esistente ""
app.accessLevel Livello di accesso: readonly, readwrite, admin readonly
app.transport Trasporto: stdio, sse, streamable-http streamable-http
oauth.enabled Abilitare l'autenticazione OAuth false
ingress.enabled Abilitare l'ingresso false

Disinstallare il server AKS MCP

Il processo di disinstallazione del server MCP di AKS dipende dalla modalità di distribuzione e dall'ambiente in cui è attualmente in esecuzione.

VS Code con estensione AKS (Azure Kubernetes Service)

  1. Aprire il riquadro comandi (Ctrl+Shift+P in Windows/Linux o Cmd+Shift+P in macOS).
  2. Eseguire MCP: Mostra Server.
  3. Selezionare AKS MCP dall'elenco.
  4. Selezionare Arresta server per arrestare il server in esecuzione.
  5. Per rimuovere la configurazione, selezionare Elimina configurazione server.

In alternativa, rimuovere manualmente la configurazione del server:

  1. Aprire il .vscode/mcp.json file o le impostazioni utente di VS Code.
  2. Eliminare l'aks-mcp-server elemento dall'oggetto servers o github.copilot.chat.mcp.servers.
  3. Eliminare il file binario AKS-MCP dal sistema (il percorso varia in base al metodo di installazione).

Docker

Se si usa Docker MCP Toolkit:

  1. Aprire Docker Desktop.
  2. Selezionare MCP Toolkit nella barra laterale sinistra.
  3. Trovare il server AKS-MCP e disabilitarlo.

Se si usa una configurazione conteneurizzata, arrestare e rimuovere il container:

docker stop <container-id>
docker rm <container-id>

Altri clienti MCP

Rimuovere la voce aks o aks-mcp dal file di configurazione del client MCP, ad esempio Claude Desktop di claude_desktop_config.json.

Problemi comuni e risoluzione dei problemi

Questa sezione descrive i problemi comuni di installazione e runtime, i relativi sintomi e come risolverli.

Il server MCP del servizio Azure Kubernetes non può accedere al cluster

Sintomi:

  • Gli strumenti restituiscono errori di autorizzazione
  • Nessuna risorsa visibile

Cause probabili:

  • L'identità utente o MCP non dispone di autorizzazioni sufficienti
  • Associazione ServiceAccount non corretta
  • Contesto kubeconfig configurato in modo errato (modalità locale)

Risoluzione:

  • Modalità locale: verificare di disporre di autorizzazioni sufficienti per accedere al cluster. Verificare di essere nel contesto corretto del cluster e della sottoscrizione.
  • Modalità remota: verificare le associazioni ClusterRole per ServiceAccount usato dal server MCP

Le chiamate API di Azure hanno esito negativo

Sintomi:

  • gli strumenti di call_az restituiscono errori di autenticazione o autorizzazione

Cause possibili:

  • Identità del carico non abilitata per il cluster
  • ServiceAccount non federato
  • Assegnazioni di Azure RBAC mancanti

Risoluzione:

  • Verifica che Workload Identity sia abilitato nel tuo cluster
  • Verificare la configurazione dell'identità federata
  • Assegnare ruoli di Azure appropriati all'identità gestita

Passaggi successivi

Altre informazioni sulle funzionalità intelligenti integrate in modo nativo per AKS:

  • Informazioni sulla CLI agente per il servizio Azure Kubernetes (AKS)
  • Installare e utilizzare l'agentic CLI per AKS
  • Last updated on