Résolution des problèmes liés aux clusters et aux nœuds Amazon EKS

Ce chapitre traite de certaines erreurs courantes que vous pouvez rencontrer lorsque vous utilisez Amazon EKS, ainsi que des solutions. Si vous avez besoin de dépanner des zones spécifiques d'Amazon EKS, consultez les rubriques Dépannage IAM, Dépannage des problèmes liés à Amazon EKS Connector et Dépannage d'ADOT à l'aide de modules complémentaires EKS.

Pour plus d’informations sur la résolution des problèmes, consultez Contenu du centre de connaissances sur Amazon Elastic Kubernetes Service sur AWS re:Post.

Capacité insuffisante

Si vous recevez l’erreur suivante lorsque vous essayez de créer un cluster Amazon EKS, cela signifie que l’une des zones de disponibilité que vous avez spécifiées ne dispose pas d’une capacité suffisante pour prendre en charge 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

Essayez à nouveau de créer votre cluster avec des sous-réseaux de votre VPC de cluster hébergés dans les zones de disponibilité renvoyés par ce message d'erreur.

Il existe des zones de disponibilité dans lesquelles un cluster ne peut pas résider. Veuillez comparer les zones de disponibilité dans lesquelles se trouvent vos sous-réseaux avec la liste des zones de disponibilité dans les Exigences et considérations relatives aux sous-réseaux.

Les nœuds ne parviennent pas à joindre le cluster

Quelques raisons courantes empêchent les nœuds de joindre le cluster :

Pour identifier et résoudre les problèmes courants qui empêchent les composants master de rejoindre un cluster, vous pouvez utiliser le runbookAWSSupport-TroubleshootEKSWorkerNode. Pour plus d’informations, consultez AWSSupport-TroubleshootEKSWorkerNode dans Référence du dossier d’exploitation AWS Systems Manager Automation.

Accès non autorisé ou refusé (kubectl)

Si vous recevez l’une des erreurs suivantes lors de l’exécution des commandes kubectl, cela signifie que kubectl n’est pas correctement configuré pour Amazon EKS ou que les informations d’identification du principal IAM (rôle ou utilisateur) que vous utilisez ne correspondent pas à un nom d’utilisateur Kubernetes disposant des autorisations suffisantes pour les objets Kubernetes sur votre cluster Amazon EKS.

Cela peut être dû à l'une des raisons suivantes :

Si vous installez et configurez l’AWS CLI, vous pouvez configurer les informations d’identification IAM que vous utilisez. Pour plus d’informations, consultez la section Configuration de l’AWS CLI du Guide de l’utilisateur de l’interface de la ligne de commande AWS. Vous pouvez également configurer kubectl pour utiliser un rôle IAM, si vous assumez un rôle IAM pour accéder aux objets Kubernetes sur votre cluster. Pour de plus amples informations, consultez Connexion de kubectl à un cluster EKS en créant un fichier kubeconfig.

hostname doesn’t match

La version Python de votre système doit être 2.7.9 ou ultérieure. Sinon, vous recevrez des erreurs hostname doesn’t match avec les appels AWS CLI à Amazon EKS. Pour plus d’informations, consultez Que sont les erreurs « nom d’hôte ne correspond pas » ? dans les Questions fréquentes sur les demandes Python.

getsockopt: no route to host

Docker s'exécute dans la plage d'adresses CIDR 172.17.0.0/16 dans les clusters Amazon EKS. Nous vous recommandons de ne pas faire chevaucher cette plage par les sous-réseaux VPC de votre cluster. Sinon, vous recevrez l'erreur suivante :

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

Si vous recevez l’erreur Instances failed to join the Kubernetes cluster dans la AWS Management Console, assurez-vous que l’accès au point de terminaison privé du cluster est activé ou que vous avez correctement configuré les blocs d’adresse CIDR pour l’accès au point de terminaison public. Pour de plus amples informations, consultez Point de terminaison du serveur d’API du cluster.

Codes d'erreurs liées aux groupes de nœuds gérés

Si votre groupe de nœuds gérés rencontre un problème d'intégrité matérielle, Amazon EKS renvoie un code d'erreur pour vous aider à diagnostiquer le problème. Ces surveillances de l’état ne détectent pas les problèmes logiciels, car elles sont basées sur les surveillances de l’état Amazon EC2. La liste suivante décrit les codes d'erreur.

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

Une cause potentielle du message d’erreur Not authorized for images est l’utilisation d’une AMI Windows Amazon EKS privée pour lancer des groupes de nœuds gérés Windows. Après avoir publié de nouvelles AMI Windows, AWS rend privées les AMI datant de plus de 4 mois, ce qui les rend inaccessibles. Si votre groupe de nœuds gérés utilise une AMI Windows privée, envisagez de mettre à jour votre groupe de nœuds gérés Windows. Bien que nous ne puissions garantir l’accès aux AMI qui ont été rendues privées, vous pouvez en faire la demande en soumettant un ticket au service d’assistance AWS. Pour plus d’informations, consultez Correctifs dans le Guide de l’utilisateur Amazon EC2.

Le nœud est dans l’état NotReady

Si votre nœud passe à l’état NotReady, cela indique probablement que le nœud est en mauvais état et indisponible pour planifier de nouveaux pods. Cela peut se produire pour diverses raisons, par exemple si le nœud ne dispose pas de ressources suffisantes pour le processeur, la mémoire ou l’espace disque disponible.

Pour les AMI Windows optimisées pour Amazon EKS, aucune réservation de ressources de calcul n’est spécifiée par défaut dans la configuration kubelet. Afin d’éviter les problèmes de ressources, vous pouvez réserver des ressources de calcul pour les processus système en fournissant au kubelet les valeurs de configuration pour kube-reserved et/ou system-reserved. Pour ce faire, utilisez le paramètre de ligne de commande -KubeletExtraArgs dans le script d’initialisation. Pour plus d’informations, consultez Réserver des ressources de calcul pour les démons système dans la documentation Kubernetes et Paramètres de configuration du script d'amorçage dans ce guide d’utilisation.

Collecteur de journaux EKS

Pour résoudre les problèmes liés aux nœuds Amazon EKS, un script pré-créé est disponible sur les nœuds à l’emplacement /etc/eks/log-collector-script/eks-log-collector.sh. Vous pouvez utiliser le script pour collecter des journaux de diagnostic pour les cas de support et le dépannage général.

Utilisez la commande suivante pour exécuter le script sur votre nœud :

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

Le script collecte les informations de diagnostic suivantes.

$ 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

Les informations de diagnostic sont collectées et stockés dans :

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

Pour récupérer le lot de journaux pour les nœuds Bottlerocket, veuillez vous reporter à la section Journal Bottlerocket pour plus de détails.

Le réseau d'exécution du conteneur n'est pas prêt

Vous pouvez recevoir une erreur Container runtime network not ready et des erreurs d'autorisation similaires aux suivantes :

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

Les raisons possibles sont les suivantes :

Délai d'expiration de la liaison TLS

Lorsqu'un nœud est incapable d'établir une connexion avec le point de terminaison du serveur d'API public, vous pouvez voir une erreur similaire à l'erreur suivante.

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\""

Le processus kubelet se reproduira continuellement et testera le point de terminaison du serveur d'API. L'erreur peut également se produire temporairement au cours de toute procédure qui effectue une mise à jour continue du cluster dans le plan de contrôle, telle qu'une modification de configuration ou une mise à jour de version.

Pour résoudre le problème, vérifiez la table de routage et les groupes de sécurité pour vous assurer que le trafic provenant des nœuds peut atteindre le point de terminaison public.

InvalidClientTokenId

Si vous utilisez des rôles IAM pour les comptes de service d’un pod ou d’un DaemonSet déployé sur un cluster dans une région AWS en Chine et que vous n’avez pas défini la variable d’environnement AWS_DEFAULT_REGION dans la spécification, le pod ou le DaemonSet peut recevoir l’erreur suivante :

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

Pour résoudre le problème, vous devez ajouter la variable d’environnement AWS_DEFAULT_REGION à la spécification de votre pod ou DaemonSet, comme indiqué dans l’exemple de spécification de pod suivant.

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"

Les groupes de nœuds doivent correspondre à la version Kubernetes avant de mettre à niveau le plan de contrôle

Avant de mettre à niveau un plan de contrôle vers une nouvelle version Kubernetes, la version mineure des nœuds gérés et Fargate de votre cluster doit être identique à la version actuelle de votre plan de contrôle. L'API update-cluster-version Amazon EKS rejette les demandes tant que vous n'avez pas mis à niveau tous les nœuds gérés par Amazon EKS vers la version actuelle du cluster. Amazon EKS fournit des API pour mettre à niveau les nœuds gérés. Pour plus d’informations sur la mise à niveau de la version Kubernetes d’un groupe de nœuds gérés, consultez Mettre à jour un groupe de nœuds gérés pour votre cluster. Pour mettre à niveau la version d’un nœud Fargate, supprimez le pod représenté par le nœud et redéployez-le après avoir mis à niveau votre plan de contrôle. Pour de plus amples informations, consultez Mettre à jour un cluster existant vers une nouvelle version de Kubernetes.

Lors du lancement de nombreux nœuds, des erreurs Too Many Requests se produisent

Si vous lancez plusieurs nœuds simultanément, vous pouvez voir un message d'erreur dans les journaux d'exécution des données utilisateur Amazon EC2 indiquant Too Many Requests. Cela peut se produire parce que le plan de contrôle est surchargé d'appels describeCluster. Cette surcharge se traduit par une limitation, des nœuds qui ne parviennent pas à exécuter le script d'amorçage et des nœuds qui ne parviennent pas à rejoindre le cluster.

Assurez-vous que les arguments --apiserver-endpoint, --b64-cluster-ca et --dns-cluster-ip sont transmis au script de démarrage du nœud. Lorsque vous incluez ces arguments, le script d’initialisation n’a pas besoin d’effectuer d’appel describeCluster, ce qui permet d’éviter la surcharge du plan de contrôle. Pour de plus amples informations, consultez Fournissez des données utilisateur pour transmettre des arguments au fichier bootstrap.sh inclus avec une AMI Amazon Linux/Bottlerocket optimisée pour Amazon EKS.

Réponse d'erreur non autorisée HTTP 401 sur les requêtes du serveur API Kubernetes

Ces erreurs s’affichent si le jeton de compte de service d’un pod a expiré sur un cluster.

Le serveur API Kubernetes de votre cluster Amazon EKS rejette les demandes dont les jetons datent de plus de 90 jours. Dans les versions précédentes de Kubernetes, les jetons n'avaient pas de période d'expiration. Cela signifie que les clients qui s'appuient sur ces jetons doivent les actualiser dans l'heure. Pour éviter que le serveur API Kubernetes ne rejette votre demande en raison d’un jeton non valide, la version du kit SDK client Kubernetes utilisée par votre charge de travail doit être identique ou postérieure aux versions suivantes :

Vous pouvez identifier tous les pod existants dans votre cluster qui utilisent des jetons périmés. Pour de plus amples informations, consultez Jetons de compte de service.

La version de la plateforme Amazon EKS est inférieure de plus de deux versions à la version actuelle de la plateforme

Cela peut se produire lorsque Amazon EKS n’est pas en mesure de mettre à jour automatiquement la platform-version de votre cluster. Bien qu'il existe de nombreuses causes à cela, certaines des causes les plus courantes suivent. Si l’un de ces problèmes s’applique à votre cluster, celui-ci peut continuer à fonctionner, mais sa version de plateforme ne sera pas mise à jour par Amazon EKS.

Problème

Le Rôle IAM du cluster a été supprimé : ce rôle a été spécifié lors de la création du cluster. Vous pouvez voir quel rôle a été spécifié à l'aide de la commande suivante. Remplacez my-cluster par le nom de votre cluster.

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

L'exemple qui suit illustre un résultat.

eksClusterRole

Solution

Création d'un nouveau rôle IAM du cluster portant le même nom.

Problème

Un sous-réseau spécifié lors de la création du cluster a été supprimé : les sous-réseaux à utiliser avec le cluster ont été spécifiés lors de la création du cluster. Vous pouvez voir quels sous-réseaux ont été spécifiés à l'aide de la commande suivante. Remplacez my-cluster par le nom de votre cluster.

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

L'exemple qui suit illustre un résultat.

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

Solution

Vérifiez si les ID de sous-réseau existent dans votre compte.

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"

L'exemple qui suit illustre un résultat.

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

Si les ID de sous-réseau renvoyés dans la sortie ne correspondent pas aux ID de sous-réseau spécifiés lors de la création du cluster, vous devez modifier les sous-réseaux utilisés par le cluster si vous voulez qu’Amazon EKS mette à jour le cluster. En effet, si vous avez spécifié plus de deux sous-réseaux lors de la création de votre cluster, Amazon EKS sélectionne de manière aléatoire les sous-réseaux que vous avez spécifiés pour y créer de nouvelles interfaces réseau Elastic. Ces interfaces réseau permettent au plan de contrôle de communiquer avec vos nœuds. Amazon EKS ne mettra pas à jour le cluster si le sous-réseau qu’il sélectionne n’existe pas. Vous n'avez aucun contrôle sur les sous-réseaux que vous avez spécifiés lors de la création du cluster dans lesquels Amazon EKS choisit de créer une nouvelle interface réseau.

Lorsque vous lancez une mise à jour de la version Kubernetes pour votre cluster, la mise à jour peut échouer pour la même raison.

Problème

Un groupe de sécurité spécifié lors de la création du cluster a été supprimé : si vous avez spécifié des groupes de sécurité lors de la création du cluster, vous pouvez voir leurs ID à l'aide de la commande suivante. Remplacez my-cluster par le nom de votre cluster.

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

L'exemple qui suit illustre un résultat.

[
    "sg-EXAMPLE1"
]

Si [] est renvoyé, cela signifie qu’aucun groupe de sécurité n’a été spécifié lors de la création du cluster et que l’absence de groupe de sécurité n’est pas le problème. Si des groupes de sécurité sont renvoyés, vérifiez qu'ils existent dans votre compte.

Solution

Vérifiez si ces groupes de sécurité existent dans votre compte.

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"

L'exemple qui suit illustre un résultat.

[
"sg-EXAMPLE2"
]

Si les ID de groupe de sécurité renvoyés dans la sortie ne correspondent pas aux ID de groupe de sécurité qui ont été spécifiés lors de la création du cluster, et si vous voulez qu’Amazon EKS mette à jour le cluster, vous devez modifier les groupes de sécurité utilisés par le cluster. Amazon EKS ne mettra pas à jour un cluster si les ID de groupe de sécurité spécifiés lors de la création du cluster n’existent pas.

Lorsque vous lancez une mise à jour de la version Kubernetes pour votre cluster, la mise à jour peut échouer pour la même raison.

Foire aux questions sur l’intégrité du cluster et codes d’erreur avec chemins de résolution

Amazon EKS détecte les problèmes liés à vos clusters EKS et à l’infrastructure du cluster, puis les stocke dans l’objet health de votre ressource de cluster EKS. Vous pouvez détecter et résoudre les problèmes de cluster plus rapidement à l'aide des informations relatives à l'état du cluster. Cela vous permet de créer des environnements d'applications plus sécurisés et à jour. De plus, il peut vous être impossible de mettre à niveau vers des versions plus récentes de Kubernetes ou d’Amazon EKS d’installer des mises à jour de sécurité sur un cluster dégradé en raison de problèmes liés à l’infrastructure nécessaire ou à la configuration du cluster. Amazon EKS peut mettre 3 heures pour détecter les problèmes ou détecter qu'un problème est résolu.

La santé d'un cluster Amazon EKS est une responsabilité partagée entre Amazon EKS et ses utilisateurs. Vous êtes responsable de l'infrastructure préalable des rôles IAM et des sous-réseaux Amazon VPC, ainsi que des autres infrastructures nécessaires, qui doivent être fournies à l'avance. Amazon EKS détecte les modifications apportées à la configuration de cette infrastructure et du cluster.

Pour accéder à l’état de santé de votre cluster dans la console Amazon EKS, recherchez un tableau intitulé Problèmes de santé dans l’onglet Problèmes de santé du cluster du tableau de bord d’observabilité accessible depuis la page de détails du cluster Amazon EKS. Ces données seront également disponibles en appelant l’action DescribeCluster dans l’API EKS, par exemple à partir de l’interface de ligne de commande AWS.

Les deux premières colonnes sont celles qui sont nécessaires pour les valeurs de réponse de l'API. Le troisième champ de l’objet Health ClusterIssue est resourceIds, dont le retour dépend du type de problème.