Risolvere i problemi di connessione del cluster AKS con il server API

Sommario

Questo articolo illustra come risolvere Servizio Azure Kubernetes (AKS) problemi di connessione del cluster con il server API quando i client kubectl o REST non possono connettersi. Il flusso di risoluzione dei problemi controlla la risoluzione dei nomi di dominio (DNS), la connettività di rete e l'autenticazione e l'autorizzazione in ordine.

Prerequisiti

• Interfaccia della riga di comando di Azure.
• kubectl.
• curl.
• nslookup.
• Per un cluster privato, un client con connettività di rete alla rete virtuale del cluster.

Causa radice e soluzioni

Risolvere i problemi di connessione nelle fasi seguenti. Completare ogni fase prima di continuare con la fase successiva:

• Fase 1: Risoluzione DNS
• Fase 2: Connettività di rete
• Fase 3: Autenticazione e autorizzazione

Prima di iniziare

1. Usare az aks show per identificare il modello di accesso al server API e il nome di dominio completo che il client deve usare.

   az aks show \
     --resource-group <resource-group> \
     --name <cluster-name> \
     --query "{
       provisioningState:provisioningState,
       powerState:powerState.code,
       fqdn:fqdn,
       privateFqdn:privateFqdn,
       privateCluster:apiServerAccessProfile.enablePrivateCluster,
       apiServerVnetIntegration:apiServerAccessProfile.enableVnetIntegration,
       authorizedIpRanges:apiServerAccessProfile.authorizedIpRanges
     }" \
     --output yaml
   

   Se questo comando ha esito negativo, verificare il tenant Azure, la sottoscrizione, il gruppo di risorse e le autorizzazioni.

   Verificare che provisioningState sia Succeeded e powerState sia Running.

   Usare fqdn per un server API pubblico. Se privateCluster è true, usare privateFqdn da una rete con connettività alla rete virtuale del cluster. È possibile eseguire questi passaggi comuni per la risoluzione dei problemi per verificare la connettività al server API del cluster del servizio Azure Kubernetes:

Fase 1: Risoluzione DNS

2. Risolvere l'FQDN indicato al passaggio 1.

   nslookup <cluster-fqdn>
   

   • Per un server API pubblico, verificare che il nome di dominio completo pubblico si risolva in un indirizzo IP pubblico.
   • Per un server API privato, verificare che il nome di dominio completo privato si risolva in un indirizzo IP privato dalla rete connessa.
   • Se la risoluzione dei nomi privati ha esito negativo, verificare il collegamento della zona DNS privata, i server di inoltro condizionale DNS personalizzati o la configurazione di DNS di Azure Private Resolver prima di continuare.

   Annotazioni

   Quando si arresta e si riavvia un cluster AKS, l'indirizzo IP del server API può cambiare mentre il FQDN rimane invariato. Se i problemi di connessione si verificano dopo un'operazione di arresto/avvio, svuotare le cache DNS interessate e risolvere nuovamente l'FQDN. Per altre informazioni, vedere Arrestare e avviare un cluster del servizio Azure Kubernetes.

   Continuare con la fase 2 solo dopo che il nome di dominio completo viene risolto nell'indirizzo previsto.

Fase 2: Connettività di rete

1. Usare una richiesta a tempo curl per testare la connettività HTTPS al server API.

   • Bash
   • PowerShell

   curl -kv --connect-timeout 5 --max-time 15 https://<cluster-fqdn>/version
   

   Annotazioni

   L'opzione -k ignora la convalida del certificato. Usarlo solo per questo test di connettività.

   • curl: (28) Connection timed out dopo l'esito positivo del DNS significa che la connessione TCP alla porta 443 non è stata stabilita. Continuare con il passaggio 4 per un endpoint privato o il passaggio 5 per un endpoint pubblico.
   • HTTP 401 Unauthorized da /version conferma che la connettività di rete funziona e che la richiesta non autenticata ha raggiunto il server API. Continuare con la fase 3.

2. Se il client si connette a un endpoint privato, incluso un cluster privato o un cluster API Server VNet Integration in modalità privata, e la richiesta va in timeout, verificare il percorso di rete privata.

   Comprendere il percorso di accesso:

   • Un server API privato richiede la connettività di rete privata. Un FQDN pubblico in un cluster privato non rende il server API raggiungibile pubblicamente.
   • Con l'integrazione rete virtuale del server API, la connettività da nodo a server API è separata dal percorso usato da un client esterno.

   Verificare il percorso client:

   1. Verificare che la rete client si connetta alla rete virtuale del cluster tramite peering di rete virtuale, VPN, ExpressRoute o un altro percorso privato supportato.
   2. Verificare che le rotte, i gruppi di sicurezza di rete, i firewall e le altre appliance virtuali di rete consentano il traffico sulla porta TCP 443 dal client all'indirizzo IP del server API privato.
   3. Ripeti la richiesta temporizzata curl dopo aver corretto il percorso della rete privata.

   Test di isolamento facoltativo:

   Se la connettività privata diretta non è disponibile, usare le opzioni Esegui comando per la connessione al cluster privato. Se Run Command riesce, concentrate l'indagine sul percorso di rete privata del client. Run Command richiede autorizzazioni di Azure separate e può anche essere influenzato dai criteri o dalla pianificazione dei pod.

3. Se il client è destinato a un server API pubblico e si verifica il timeout della richiesta, controllare il percorso in uscita del client e gli intervalli IP autorizzati del server API.

   az aks show \
     --resource-group <resource-group> \
     --name <cluster-name> \
     --query apiServerAccessProfile.authorizedIpRanges
   

   • Se il risultato è null o vuoto, gli intervalli IP autorizzati non sono abilitati. Controllare il routing, la VPN, il proxy e le regole del firewall del client per la porta TCP in uscita 443.
   • Se gli intervalli sono configurati, consultare L'indirizzo IP del client non può accedere al server dell'API per verificare e aggiornare l'indirizzo IP pubblico di origine effettivo del client. Prendere in considerazione reti di gestione, VPN o SNAT (Firewall Source Network Address Translation), agenti di automazione, indirizzi in uscita del cluster e prefissi IP pubblici del nodo.

   Attendere che un aggiornamento si propaghi e ripetere la richiesta temporizzata curl. Durante la propagazione, le singole connessioni possono produrre risultati diversi, quindi non dichiarare il ripristino o l'errore da una singola richiesta.

Fase 3: Autenticazione e autorizzazione

1. Dopo che la curl richiesta restituisce HTTP 401 Unauthorized, usare kubectl per convalidare le credenziali in kubeconfig e l'accesso dell'utente alle risorse del cluster.

   kubectl get --raw=/version --request-timeout=10s
   kubectl get nodes --request-timeout=10s
   

   • Se entrambi i comandi hanno esito positivo, l'autenticazione funziona e l'utente può elencare i nodi del cluster.
   • Unauthorized o You must be logged in to the server indica un problema di autenticazione o credenziali. Continuare con il passaggio 7.
   • Se la richiesta di versione ha esito positivo ma kubectl get nodes restituisce Forbidden, l'autenticazione è riuscita ma l'utente non è autorizzato ad elencare i nodi. Continuare con il passaggio 8.

2. Se l'autenticazione non riesce, controllare la toolchain di configurazione e autenticazione del client.

   • Seguire Il file di configurazione non è disponibile durante la connessione se kubeconfig manca, non è valido o fa riferimento all'endpoint sbagliato.
   • Per i cluster integrati Microsoft Entra, verificare che kubelogin sia installato quando kubeconfig usa un plug-in credenziali exec e verificare che il metodo di autenticazione selezionato sia compatibile con i criteri di accesso condizionale applicabili.
   • Mantenere kubectl all'interno di una versione secondaria del server API, in entrambe le direzioni, in base ai criteri di asimmetria della versione di Kubernetes. Usare az aks install-cli o le istruzioni di installazione kubectl specifiche della piattaforma quando è necessario un aggiornamento.

   Ripetere i kubectl comandi nel passaggio 6 dopo aver corretto il problema di autenticazione.

3. Se kubectl restituisce Forbidden, seguire User can't get cluster resources (Non è possibile ottenere risorse cluster). Verificare se il cluster usa Kubernetes RBAC o Azure RBAC per l'autorizzazione di Kubernetes e verificare l'assegnazione di ruolo o il binding di ruolo per l'operazione specifica che non è riuscita.

   Ripetere kubectl get nodes --request-timeout=10s dopo aver corretto il problema di autorizzazione.

Controllo aggiuntivo per le operazioni specifiche del nodo

1. Se i comandi del passaggio 6 hanno esito positivo, ma kubectl logs, attachexec, o port-forward hanno esito negativo, controllare il percorso da server API a nodo.

   • Seguire le indicazioni in Risolvere i problemi di connettività del tunnel e verificare che i controlli di sicurezza di rete associati ai nodi di AKS consentano la comunicazione necessaria dal piano di controllo al kubelet sulla porta TCP 10250.
   • Se i nodi o le estensioni non riescono a raggiungere gli endpoint del servizio Azure Kubernetes necessari, verificare le regole di uscita minime necessarie per il servizio Azure Kubernetes, tra cui proxy, firewall, ispezione TLS e comportamento ALPN.
   • Gli errori della porta TCP 10250 possono influire solo su alcune operazioni dipendenti dal nodo. Confrontare l'operazione con esito negativo con i comandi riusciti del passaggio 6 invece di considerarlo come un errore generale da client a API-server.

Per altri scenari di timeout, vedere Timeout TCP quando kubectl o altri strumenti di terze parti si connettono al server API.