Risoluzione dei problemi con i cluster e i nodi Amazon EKS

Questo capitolo presenta alcuni errori comuni che si potrebbero verificare durante l'uso di Amazon EKS e il modo in cui gestirli. Se devi risolvere problemi in aree specifiche di Amazon EKS, consulta gli argomenti separati Risoluzione dei problemi di IAM, Risoluzione dei problemi del connettore Amazon EKS e Risoluzione dei problemi di ADOT utilizzando i componenti aggiuntivi EKS.

Per altre informazioni sulla risoluzione dei problemi, consulta i Contenuti del Knowledge Center su Amazon Elastic Kubernetes Service su AWS re:Post.

Capacità insufficiente

Se ricevi il seguente errore mentre provi a creare un cluster Amazon EKS, significa che una delle zone di disponibilità indicate non dispone della capacità sufficiente per supportare un cluster.

Cannot create cluster 'example-cluster' because region-1d, the targeted Availability Zone, does not currently have sufficient capacity to support the cluster. Retry and choose from these Availability Zones: region-1a, region-1b, region-1c

Riprova a crearlo con le sottoreti del VPC del cluster ospitate nelle zone di disponibilità restituite da questo messaggio di errore.

Ci sono zone di disponibilità dove non è possibile farvi risiedere un cluster. Confronta le zone di disponibilità in cui si trovano le tue sottoreti con l’elenco delle zone di disponibilità in Requisiti e considerazioni sulle sottoreti.

Impossibile aggiungere i nodi al cluster

Ci sono diversi motivi comuni che impediscono l'aggiunta dei nodi di lavoro al cluster:

Per identificare e risolvere i problemi più comuni che impediscono ai nodi worker di unirsi a un cluster, puoi utilizzare il runbook AWSSupport-TroubleshootEKSWorkerNode. Per ulteriori informazioni, consulta AWSSupport-TroubleshootEKSWorkerNode nel Riferimento dei runbook AWSAutomation Systems Manager.

Accesso negato o non autorizzato (kubectl)

Se ricevi uno dei seguenti errori durante l’esecuzione di comandi kubectl, kubectl non è stato configurato correttamente per Amazon EKS o le credenziali del principale IAM (ruolo o utente) in uso non sono mappate a un nome utente Kubernetes con autorizzazioni sufficienti per gli oggetti Kubernetes nel tuo cluster Amazon EKS.

Questo potrebbe essere dovuto a uno dei seguenti fattori:

Se installi e configuri AWS CLI, è possibile configurare le credenziali IAM che utilizzi. Per ulteriori informazioni consulta Configurare AWS CLI nella Guida per l’utente dell’interfaccia a riga di comando AWS. È anche possibile configurare kubectl affinché utilizzi un ruolo IAM, se assumi un ruolo IAM per accedere agli oggetti Kubernetes sul cluster. Per ulteriori informazioni, consulta Connettere kubectl a un cluster EKS creando un file kubeconfig.

hostname doesn’t match

La versione Python del sistema deve essere 2.7.9 o successiva. In caso contrario, riceverai errori hostname doesn’t match con chiamate di AWS CLI ad Amazon EKS. Per ulteriori informazioni, consulta Cosa sono gli errori “hostname non corrispondente”? nelle Domande frequenti di Python Requests.

getsockopt: no route to host

Docker viene eseguito nell’intervallo CIDR 172.17.0.0/16 nei cluster Amazon EKS. Consigliamo che le sottoreti VPC del cluster non si sovrappongano a questo intervallo. In caso contrario, riceverai il seguente messaggio di errore:

Error: : error upgrading connection: error dialing backend: dial tcp 172.17.<nn>.<nn>:10250: getsockopt: no route to host

Instances failed to join the Kubernetes cluster

Se ricevi l’errore Instances failed to join the Kubernetes cluster in Console di gestione AWS, accertati che l’accesso all’endpoint privato del cluster sia abilitato o che siano stati configurati correttamente gli intervalli CIDR per l’accesso agli endpoint pubblici. Per ulteriori informazioni, consulta Endpoint del server API del cluster.

Codici di errore dei gruppi di nodi gestiti

Se il gruppo di nodi gestiti rileva un problema di integrità hardware, Amazon EKS restituisce un codice di errore che consente di diagnosticare il problema. Questi controlli dell’integrità non rilevano problemi software perché si basano su controlli dell’integrità di Amazon EC2. Nel seguente elenco vengono descritti i codici di errore.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: eks:node-manager
rules:
- apiGroups:
  - ''
  resources:
  - pods
  verbs:
  - get
  - list
  - watch
  - delete
- apiGroups:
  - ''
  resources:
  - nodes
  verbs:
  - get
  - list
  - watch
  - patch
- apiGroups:
  - ''
  resources:
  - pods/eviction
  verbs:
  - create

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: eks:node-manager
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: eks:node-manager
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: eks:node-manager

kubectl describe clusterrole eks:node-manager

kubectl describe clusterrolebinding eks:node-manager

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: eks:node-manager
rules:
- apiGroups:
  - ''
  resources:
  - pods
  verbs:
  - get
  - list
  - watch
  - delete
- apiGroups:
  - ''
  resources:
  - nodes
  verbs:
  - get
  - list
  - watch
  - patch
- apiGroups:
  - ''
  resources:
  - pods/eviction
  verbs:
  - create
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: eks:node-manager
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: eks:node-manager
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: eks:node-manager

kubectl apply -f eks-node-manager-role.yaml

Not authorized for images

Una potenziale causa di un messaggio di errore Not authorized for images è l’utilizzo di un’AMI Windows di Amazon EKS privata per avviare gruppi di nodi gestiti da Windows. Dopo il rilascio di nuove AMI Windows, AWS rende private le AMI che hanno più di 4 mesi, rendendole non più accessibili. Se il tuo gruppo di nodi gestiti utilizza un’AMI Windows privata, considera la possibilità di aggiornare il gruppo di nodi gestito da Windows. Sebbene non possiamo garantire di poter fornire l’accesso alle AMI che sono state rese private, puoi richiederne l’accesso inviando un ticket al Supporto AWS. Per maggiori informazioni, consulta Patches nella Guida per l’utente di Amazon EC2.

Il nodo è in stato NotReady

Se il nodo entra in uno stato NotReady, ciò probabilmente indica che il nodo non è integro e non è disponibile per pianificare nuovi pod. Ciò può verificarsi per vari motivi, ad esempio se il nodo non dispone di risorse sufficienti per CPU, memoria o spazio disponibile su disco.

Per le AMI Windows ottimizzate per Amazon EKS, non è prevista alcuna prenotazione per le risorse di elaborazione specificate per impostazione predefinita nella configurazione kubelet. Per evitare problemi di risorse, è possibile prenotare le risorse di calcolo per i processi di sistema fornendo a kubelet i valori di configurazione per kube-reserved e/o system-reserved. È possibile eseguire questa operazione utilizzando il parametro della riga di comando -KubeletExtraArgs nello script di bootstrap. Per ulteriori informazioni, consulta Reserve Compute Resources for System Daemons nella documentazione di Kubernetes e Parametri di configurazione dello script di bootstrap in questa guida per l’utente.

Raccoglitore di log EKS

Per risolvere i problemi con i nodi Amazon EKS, è disponibile uno script predefinito sui nodi situati in /etc/eks/log-collector-script/eks-log-collector.sh. È possibile utilizzare lo script per raccogliere i registri diagnostici per i casi di supporto e per la risoluzione dei problemi generali.

Utilizza il comando seguente per eseguire lo script sul nodo:

sudo bash /etc/eks/log-collector-script/eks-log-collector.sh

curl -O https://amazon-eks.s3.amazonaws.com/support/log-collector-script/linux/eks-log-collector.sh
sudo bash eks-log-collector.sh

Lo script raccoglie le seguenti informazioni di diagnostica:

$ sudo bash /etc/eks/log-collector-script/eks-log-collector.sh

      This is version 0.7.8. New versions can be found at https://github.com/awslabs/amazon-eks-ami/blob/main/log-collector-script/

Trying to collect common operating system logs...
Trying to collect kernel logs...
Trying to collect mount points and volume information...
...
...

	Done... your bundled logs are located in /var/log/eks_i-EXAMPLE_2025-03-25_0000-UTC_0.7.8.tar.gz

Le informazioni di diagnostica vengono raccolte e archiviate in:

/var/log/eks_i-EXAMPLE_2025-03-25_0000-UTC_0.7.8.tar.gz

Per recuperare il pacchetto di log per i nodi Bottlerocket, fai riferimento a Bottlerocket Log per maggiori dettagli.

Rete runtime container non pronta

Potresti visualizzare un errore Container runtime network not ready ed errori di autorizzazione analoghi al seguente:

4191 kubelet.go:2130] Container runtime network not ready: NetworkReady=false reason:NetworkPluginNotReady message:docker: network plugin is not ready: cni config uninitialized
4191 reflector.go:205] k8s.io/kubernetes/pkg/kubelet/kubelet.go:452: Failed to list *v1.Service: Unauthorized
4191 kubelet_node_status.go:106] Unable to register node "ip-10-40-175-122.ec2.internal" with API server: Unauthorized
4191 reflector.go:205] k8s.io/kubernetes/pkg/kubelet/kubelet.go:452: Failed to list *v1.Service: Unauthorized

Questo può verificarsi per uno dei seguenti motivi:

Timeout dell'handshake TLS

Quando un nodo non è in grado di stabilire una connessione all'endpoint del server API pubblico, è possibile che venga visualizzato un errore analogo al seguente.

server.go:233] failed to run Kubelet: could not init cloud provider "aws": error finding instance i-1111f2222f333e44c: "error listing AWS instances: \"RequestError: send request failed\\ncaused by: Post  net/http: TLS handshake timeout\""

Il processo kubelet riprenderà continuamente e testerà l'endpoint del server API. L'errore può verificarsi anche temporaneamente durante qualsiasi procedura che esegue un aggiornamento in sequenza del cluster nel piano di controllo, ad esempio una modifica della configurazione o un aggiornamento della versione.

Per risolvere il problema, controlla la tabella di routing e i gruppi di sicurezza per assicurarti che il traffico proveniente dai nodi possa raggiungere l'endpoint pubblico.

InvalidClientTokenId

Se utilizzi i ruoli IAM per gli account di servizio per un pod o un DaemonSet implementato in un cluster in una Regione AWS Cina e non hai impostato la variabile di ambiente AWS_DEFAULT_REGION nelle specifiche, il pod o il DaemonSet potrebbe ricevere il seguente errore:

An error occurred (InvalidClientTokenId) when calling the GetCallerIdentity operation: The security token included in the request is invalid

Per risolvere il problema, è necessario aggiungere la variabile di ambiente AWS_DEFAULT_REGION alla specifica del pod o DaemonSet, come mostrato nella specifica del pod di esempio seguente.

apiVersion: v1
kind: Pod
metadata:
  name: envar-demo
  labels:
    purpose: demonstrate-envars
spec:
  containers:
  - name: envar-demo-container
    image: gcr.io/google-samples/node-hello:1.0
    env:
    - name: AWS_DEFAULT_REGION
      value: "region-code"

Prima di poter aggiornare il piano di controllo, i gruppi di nodi devono corrispondere alla versione di Kubernetes

Prima di aggiornare il piano di controllo a una nuova versione di Kubernetes, assicurati che la versione secondaria dei nodi gestiti e Fargate nel cluster sia la stessa della versione corrente del piano di controllo. L'API update-cluster-version di Amazon EKS rifiuta le richieste fino a quando non si aggiornano tutti i nodi gestiti Amazon EKS alla versione corrente del cluster. Amazon EKS fornisce API per aggiornare i nodi gestiti. Per informazioni sull’aggiornamento delle versioni di Kubernetes del gruppo di nodi gestiti, consulta Aggiornamento del gruppo di nodi gestito per il cluster. Per aggiornare la versione di un nodo Fargate, elimina il pod rappresentato dal nodo e implementalo nuovamente dopo aver aggiornato il piano di controllo. Per ulteriori informazioni, consulta Aggiornamento del cluster esistente alla nuova versione di Kubernetes.

All'avvio di molti nodi, si verificano errori Too Many Requests

Se si avviano più nodi contemporaneamente, si potrebbe visualizzare il messaggio di errore Too Many Requests nei registri di esecuzione dei dati utente di Amazon EC2. Ciò può verificarsi perché il piano di controllo è sovraccarico di chiamate describeCluster. Il sovraccarico si traduce in limitazione (della larghezza di banda della rete), nodi che non eseguono lo script bootstrap e nodo che non vengono aggiunti al cluster.

Assicurarti che gli argomenti --apiserver-endpoint, --b64-cluster-ca e --dns-cluster-ip siano trasferiti allo script di bootstrap del nodo. Quando includi questi argomenti, non è necessario che lo script bootstrap crei una chiamata describeCluster. Ciò contribuisce a impedire che il piano di controllo si sovraccarichi. Per ulteriori informazioni, consulta Fornisci i dati utente per passare argomenti al file bootstrap.sh incluso nell’AMI Linux/Bottlerocket ottimizzata per Amazon EKS.

Risposta agli errori HTTP 401 Unauthorized (Autorizzazione negata) per le richieste del server API Kubernetes

Questi errori sono visualizzati se il token dell’account di servizio di un pod è scaduto in un cluster.

Il server API Kubernetes del cluster Amazon EKS rifiuta le richieste con token più vecchi di 90 giorni. Nelle versioni Kubernetes precedenti, i token non avevano una scadenza. Di conseguenza, i client che si basano su questi token devono aggiornarli entro un'ora. Per impedire al server API Kubernetes di rifiutare la richiesta a causa di un token non valido, la versione dell’SDK client Kubernetes utilizzata dal carico di lavoro deve essere uguale o successiva alle versioni riportate di seguito:

È possibile identificare tutti i pod esistenti nel cluster che utilizzano token obsoleti. Per ulteriori informazioni, consulta Token dell'account di servizio.

La versione della piattaforma Amazon EKS è più avanti di due versioni rispetto all'attuale versione della piattaforma

Ciò può accadere quando Amazon EKS non è in grado di aggiornare automaticamente la versione della piattaforma del cluster. Sebbene ci siano molte cause, di seguito riportiamo quelle più comuni. Se uno di questi problemi si applica al tuo cluster, potrebbe ancora funzionare, ma la sua versione della piattaforma non sarà aggiornata da Amazon EKS.

Problema

Il ruolo IAM del cluster è stato eliminato: questo ruolo è stato specificato al momento della creazione del cluster. Puoi visualizzare quale ruolo è stato specificato con il seguente comando. Sostituisci my-cluster con il nome del tuo cluster.

aws eks describe-cluster --name my-cluster --query cluster.roleArn --output text | cut -d / -f 2

Di seguito viene riportato un output di esempio:

eksClusterRole

Soluzione

Crea un nuovo ruolo IAM del cluster con lo stesso nome.

Problema

Una sottorete specificata durante la creazione del cluster è stata eliminata: le sottoreti da utilizzare con il cluster sono state specificate durante la creazione del cluster. Puoi visualizzare le sottoreti specificate con il seguente comando. Sostituisci my-cluster con il nome del tuo cluster.

aws eks describe-cluster --name my-cluster --query cluster.resourcesVpcConfig.subnetIds

Di seguito viene riportato un output di esempio:

[
"subnet-EXAMPLE1",
"subnet-EXAMPLE2"
]

Soluzione

Verifica se gli ID di sottorete esistono nel tuo account.

vpc_id=$(aws eks describe-cluster --name my-cluster --query cluster.resourcesVpcConfig.vpcId --output text)
aws ec2 describe-subnets --filters "Name=vpc-id,Values=$vpc_id" --query "Subnets[*].SubnetId"

Di seguito viene riportato un output di esempio:

[
"subnet-EXAMPLE3",
"subnet-EXAMPLE4"
]

Nel caso in cui gli ID di sottorete restituiti nell’output non corrispondano agli ID di sottorete specificati al momento della creazione del cluster, se desideri che Amazon EKS aggiorni il cluster, devi modificare le sottoreti utilizzate dal cluster. Questo perché se hai specificato più di due sottoreti al momento della creazione del cluster, Amazon EKS seleziona in modo casuale le sottoreti specificate in cui creare nuove interfacce di rete elastiche. Queste interfacce di rete consentono al piano di controllo di comunicare con i nodi. Amazon EKS non aggiornerà il cluster se la sottorete selezionata non esiste. Non hai alcun controllo su quale delle sottoreti specificate al momento della creazione del cluster Amazon EKS sceglie per creare una nuova interfaccia di rete.

Quando avvii un aggiornamento della versione di Kubernetes per il cluster, l’aggiornamento può non riuscire per lo stesso motivo.

Problema

Un gruppo di sicurezza specificato durante la creazione del cluster è stato eliminato: se durante la creazione del cluster hai specificato dei gruppi di sicurezza, puoi visualizzarne gli ID con il seguente comando. Sostituisci my-cluster con il nome del tuo cluster.

aws eks describe-cluster --name my-cluster --query cluster.resourcesVpcConfig.securityGroupIds

Di seguito viene riportato un output di esempio:

[
    "sg-EXAMPLE1"
]

Se [] è restituito, non sono stati specificati gruppi di sicurezza al momento della creazione del cluster e il problema non è dato dalla mancanza di un gruppo di sicurezza. Se vengono restituiti i gruppi di sicurezza, conferma che i gruppi di sicurezza sono presenti nel tuo account.

Soluzione

Verifica se questi gruppi di sicurezza esistono nel tuo account.

vpc_id=$(aws eks describe-cluster --name my-cluster --query cluster.resourcesVpcConfig.vpcId --output text)
aws ec2 describe-security-groups --filters "Name=vpc-id,Values=$vpc_id" --query "SecurityGroups[*].GroupId"

Di seguito viene riportato un output di esempio:

[
"sg-EXAMPLE2"
]

Se desideri che Amazon EKS aggiorni il cluster, nel caso in cui gli ID dei gruppi di sicurezza restituiti nell’output non corrispondano agli ID dei gruppi di sicurezza specificati al momento della creazione del cluster, devi modificare i gruppi di sicurezza utilizzati dal cluster. Amazon EKS non aggiornerà un cluster se gli ID dei gruppi di sicurezza specificati al momento della creazione del cluster non esistono.

Quando avvii un aggiornamento della versione di Kubernetes per il cluster, l’aggiornamento può non riuscire per lo stesso motivo.

Domande frequenti sull’integrità del cluster e codici di errore con percorsi di risoluzione

Amazon EKS rileva problemi con i cluster EKS e l’infrastruttura del cluster e li archivia nell’oggetto integrità della risorsa del cluster EKS. Grazie alle informazioni sull'integrità del cluster è possibile rilevare, risolvere e affrontare più rapidamente eventuali problemi. Ciò consente di creare ambienti applicativi più sicuri e aggiornati. Inoltre, è possibile che tu non possa effettuare l’aggiornamento a versioni più recenti di Kubernetes o che Amazon EKS non sia in grado di installare aggiornamenti di sicurezza su un cluster degradato a causa di problemi relativi all’infrastruttura necessaria o alla configurazione del cluster. Amazon EKS può impiegare tre ore per rilevare problemi o verificare che un problema è stato risolto.

L'integrità di un cluster Amazon EKS rappresenta una responsabilità condivisa tra Amazon EKS e i suoi utenti. Sei responsabile dell'infrastruttura indispensabile per i ruoli IAM e le sottoreti Amazon VPC, nonché di altre infrastrutture necessarie, che devono essere fornite anticipatamente. Amazon EKS rileva le modifiche nella configurazione di questa infrastruttura e del cluster.

Per accedere all’integrità del cluster nella console Amazon EKS, è necessario trovare una tabella denominata Problemi di integrità nella scheda Problemi di integrità del cluster nella dashboard di osservabilità a cui si accede dalla pagina dei dettagli del cluster Amazon EKS. Questi dati saranno disponibili anche richiamando l’azione DescribeCluster nell’API EKS, ad esempio dall’interno della linea a riga di comando AWS.

Le prime due colonne sono quelle necessarie per i valori di risposta dell'API. Il terzo campo dell’oggetto Problemi di integrità del cluster è ResourceIds, e il valore restituito varia in base al tipo di problema.