Résoudre les problèmes des clusters Amazon EKS locaux sur des AWS Outposts

Cette rubrique traite de certaines erreurs courantes que vous pourriez rencontrer lorsque vous utilisez des clusters locaux, ainsi que des solutions. Les clusters locaux sont similaires aux clusters Amazon EKS dans le cloud, mais il existe quelques différences dans la façon dont ils sont gérés par Amazon EKS.

Important

Ne terminez jamais une instance de plan de contrôle Kubernetes de cluster local EKS géré s’exécutant sur Outpost, sauf instruction contraire explicite de l’assistance AWS. La fermeture de ces instances présente un risque pour la disponibilité du service de cluster local, notamment la perte du cluster local en cas de fermeture simultanée de plusieurs instances. Les instances du plan de contrôle Kubernetes du cluster local EKS sont identifiées par la balise eks-local:controlplane-name sur la console de l’instance EC2.

Les clusters locaux sont créés via l'API Amazon EKS, mais sont exécutés de manière asynchrone. Cela signifie que les demandes adressées à l'API Amazon EKS aboutissent immédiatement pour les clusters locaux. Toutefois, ces demandes peuvent aboutir, effectuer une interruption immédiate en raison d'erreurs de validation d'entrée, ou échouer et comporter des erreurs de validation descriptives. Ce comportement est similaire à celui de l’API Kubernetes.

Les clusters locaux ne passent pas à l’état FAILED. Amazon EKS tente de rapprocher l'état du cluster de l'état souhaité demandé par l'utilisateur de manière continue. Par conséquent, un cluster local peut rester dans l'état CREATING pendant une longue période, jusqu'à ce que le problème sous-jacent soit résolu.

Les problèmes liés aux clusters locaux peuvent être détectés à l’aide de la commande CLI AWS Amazon EKS describe-cluster. Les problèmes liés aux clusters locaux sont signalés par le champ cluster.health de la réponse de la commande describe-cluster. Le message contenu dans ce champ inclut un code d'erreur, un message descriptif et les ID de ressources connexes. Ces informations sont disponibles via l’API et la CLI AWS Amazon EKS uniquement. Dans la commande suivante, remplacez my-cluster par le nom de votre cluster local.


aws eks describe-cluster --name my-cluster --query 'cluster.health'

L'exemple qui suit illustre un résultat.


{
    "issues": [
        {
            "code": "ConfigurationConflict",
            "message": "The instance type 'm5.large' is not supported in Outpost 'my-outpost-arn'.",
            "resourceIds": [
                "my-cluster-arn"
            ]
        }
    ]
}

Si le problème est irréparable, vous devrez peut-être supprimer le cluster local et en créer un nouveau. Par exemple, essayez d’allouer un cluster avec un type d’instance qui n’est pas disponible sur votre Outpost. Le tableau suivant répertorie les erreurs courantes liées à l'état.

Scénario d'erreur	Code	Message	ResourceIds
Les sous-réseaux fournis sont introuvables.	`ResourceNotFound`	`The subnet ID subnet-id does not exist`	Tous les ID de sous-réseaux fournis
Les sous-réseaux fournis n’appartiennent pas au même VPC.	`ConfigurationConflict`	`Subnets specified must belong to the same VPC`	Tous les ID de sous-réseaux fournis
Certains sous-réseaux fournis n’appartiennent pas à l’Outpost spécifié.	`ConfigurationConflict`	`Subnet subnet-id expected to be in outpost-arn, but is in other-outpost-arn`	ID de sous-réseau problématique
Certains sous-réseaux fournis n’appartiennent à aucun Outpost.	`ConfigurationConflict`	`Subnet subnet-id is not part of any Outpost`	ID de sous-réseau problématique
Certains sous-réseaux fournis ne disposent pas de suffisamment d’adresses libres pour créer des interfaces réseau Elastic pour les instances du plan de contrôle.	`ResourceLimitExceeded`	`The specified subnet does not have enough free addresses to satisfy the request.`	ID de sous-réseau problématique
Le type d’instance du plan de contrôle spécifié n’est pas pris en charge sur votre Outpost.	`ConfigurationConflict`	`The instance type type is not supported in Outpost outpost-arn`	ARN de cluster
Vous avez résilié une instance Amazon EC2 du plan de contrôle ou la commande `run-instance` a réussi, mais l'état observé est passé à `Terminated`. Cela peut se produire pendant un certain temps une fois que votre Outpost se reconnecte et que des erreurs internes d'Amazon EBS entraînent l'échec d'un flux interne Amazon EC2.	`InternalFailure`	`EC2 instance state "Terminated" is unexpected`	ARN de cluster
Vous avez une capacité insuffisante sur votre Outpost. Cela peut également se produire lors de la création d’un cluster si un Outpost est déconnecté de la région AWS.	`ResourceLimitExceeded`	`There is not enough capacity on the Outpost to launch or start the instance.`	ARN de cluster
Votre compte a dépassé votre quota de groupes de sécurité.	`ResourceLimitExceeded`	Message d'erreur renvoyé par l'API Amazon EC2	ID du VPC cible
Votre compte a dépassé votre quota d'interface réseau Elastic.	`ResourceLimitExceeded`	Message d'erreur renvoyé par l'API Amazon EC2	l'ID du sous-réseau cible
Les instances du plan de contrôle n’étaient pas accessibles via AWS Systems Manager. Pour la résolution, consultez Les instances du plan de contrôle ne sont pas accessibles via AWS Systems Manager..	`ClusterUnreachable`	Les instances du plan de contrôle Amazon EKS ne sont pas accessibles via SSM. Vérifiez votre SSM et votre configuration réseau, et consultez la documentation de résolution des problèmes EKS sur les Outposts.	ID de l'instance Amazon EC2
Une erreur s'est produite lors de l'obtention de détails pour un groupe de sécurité géré ou une interface réseau Elastic.	Basée sur le code d'erreur du client Amazon EC2.	Message d'erreur renvoyé par l'API Amazon EC2	Tous les ID des groupes de sécurité gérés
Une erreur s'est produite lors de l'autorisation ou de la révocation des règles d'entrée du groupe de sécurité. Cela s'applique à la fois aux groupes de sécurité du cluster et du plan de contrôle.	Basée sur le code d'erreur du client Amazon EC2.	Message d'erreur renvoyé par l'API Amazon EC2	ID de groupe de sécurité problématique
Une erreur s'est produite lors de la suppression d'une interface réseau Elastic d'une instance du plan de contrôle.	Basée sur le code d'erreur du client Amazon EC2.	Message d'erreur renvoyé par l'API Amazon EC2	ID d'interface réseau Elastoc problématique

Le tableau suivant répertorie les erreurs provenant d’autres services AWS qui sont présentes dans le champ de santé de la réponse describe-cluster.

Code d'erreur Amazon EC2	Code de problème de santé du cluster	Description
`AuthFailure`	`AccessDenied`	Cette erreur peut se produire pour différentes raisons. La raison la plus courante est que vous avez accidentellement supprimé une balise que le service utilise pour réduire la portée de la politique de rôle lié à un service du plan de contrôle. Si cela se produit, Amazon EKS ne peut plus gérer et surveiller ces ressources AWS.
`UnauthorizedOperation`	`AccessDenied`	Cette erreur peut se produire pour différentes raisons. La raison la plus courante est que vous avez accidentellement supprimé une balise que le service utilise pour réduire la portée de la politique de rôle lié à un service du plan de contrôle. Si cela se produit, Amazon EKS ne peut plus gérer et surveiller ces ressources AWS.
`InvalidSubnetID.NotFound`	`ResourceNotFound`	Cette erreur se produit lorsque l’ID de sous-réseau pour les règles d’entrée d’un groupe de sécurité est introuvable.
`InvalidPermission.NotFound`	`ResourceNotFound`	Cette erreur se produit lorsque les autorisations pour les règles d’entrée d’un groupe de sécurité ne sont pas correctes.
`InvalidGroup.NotFound`	`ResourceNotFound`	Cette erreur se produit lorsque le groupe des règles d’entrée d’un groupe de sécurité est introuvable.
`InvalidNetworkInterfaceID.NotFound`	`ResourceNotFound`	Cette erreur se produit lorsque l’ID de l’interface réseau pour les règles d’entrée d’un groupe de sécurité est introuvable.
`InsufficientFreeAddressesInSubnet`	`ResourceLimitExceeded`	Cette erreur se produit lorsque le quota de ressources du sous-réseau est dépassé.
`InsufficientCapacityOnOutpost`	`ResourceLimitExceeded`	Cette erreur se produit lorsque le quota de capacité de l'avant-poste est dépassé.
`NetworkInterfaceLimitExceeded`	`ResourceLimitExceeded`	Cette erreur se produit lorsque le quota de l'interface réseau Elastic est dépassé.
`SecurityGroupLimitExceeded`	`ResourceLimitExceeded`	Cette erreur se produit lorsque le quota du groupe de sécurité est dépassé.
`VcpuLimitExceeded`	`ResourceLimitExceeded`	Cette erreur est observée lors de la création d'une instance Amazon EC2 dans un nouveau compte. L'erreur peut être similaire à ce qui suit : "`You have requested more vCPU capacity than your current vCPU limit of 32 allows for the instance bucket that the specified instance type belongs to. Please visit http://aws.amazon.com/contact-us/ec2-request to request an adjustment to this limit."`
`InvalidParameterValue`	`ConfigurationConflict`	Amazon EC2 renvoie ce code d’erreur si le type d’instance spécifié n’est pas pris en charge sur l’Outpost.
Toutes les autres erreurs	`InternalFailure`	Aucune

Les clusters locaux nécessitent des autorisations et des politiques différentes de celles des clusters Amazon EKS qui sont hébergés dans le cloud. Lorsque la création d’un cluster échoue et produit une erreur InvalidPermissions, vérifiez que le rôle de cluster que vous utilisez possède la politique gérée AmazonEKSLocalOutpostClusterPolicy qui lui est associée. Tous les autres appels d'API nécessitent le même ensemble d'autorisations que les clusters Amazon EKS dans le cloud.

Le temps nécessaire à la création d'un cluster local varie en fonction de plusieurs facteurs. Ces facteurs comprennent la configuration de votre réseau, la configuration d’Outpost et la configuration du cluster. En général, un cluster local est créé et passe à l'état ACTIVE dans les 15 à 20 minutes. Si un cluster local reste dans l'état CREATING, vous pouvez appeler describe-cluster pour obtenir des informations sur la cause dans le champ de sortie cluster.health.

Les problèmes les plus courants sont les suivants :

Votre cluster ne peut pas se connecter à l’instance du plan de contrôle à partir de la région AWS dans laquelle se trouve Systems Manager. Vous pouvez le vérifier en appelant aws ssm start-session --target instance-id depuis un hôte bastion de la région. Si cette commande ne fonctionne pas, vérifiez si Systems Manager est exécuté sur l’instance du plan de contrôle. Une autre solution consiste à supprimer le cluster, puis à le recréer.
Les instances du plan de contrôle ne peuvent pas être créées en raison des autorisations de clé KMS pour les volumes EBS. Avec les clés KMS gérées par l’utilisateur pour les volumes EBS chiffrés, les instances du plan de contrôle seront interrompues si la clé n’est pas accessible. Si les instances sont arrêtées, passez à une clé KMS gérée par AWS ou assurez-vous que votre stratégie de clé gérée par l’utilisateur accorde les autorisations nécessaires au rôle du cluster.
Il se peut que les instances du plan de contrôle de Systems Manager n'aient pas accès à Internet. Vérifiez si le sous-réseau que vous avez fourni lors de la création du cluster possède une passerelle NAT et un VPC avec une passerelle Internet. Utilisez l'analyseur d'accessibilité VPC pour vérifier si l'instance du plan de contrôle peut atteindre la passerelle Internet. Pour plus d'informations, consultez Getting started with VPC Reachability Analyzer (langue française non garantie).
Le rôle ARN que vous avez fourni ne contient pas de politiques. Vérifiez si la politique gérée AWS AmazonEKSLocalOutpostClusterPolicy a été supprimée du rôle. Cela peut également se produire si une pile AWS CloudFormation est mal configurée.
Tous les sous-réseaux fournis doivent être associés au même Outpost et pouvoir communiquer entre eux. Lorsque plusieurs sous-réseaux sont spécifiés lors de la création d'un cluster, Amazon EKS tente de répartir les instances du plan de contrôle sur plusieurs sous-réseaux.
Les groupes de sécurité gérés par Amazon EKS sont appliqués sur l'interface réseau Elastic. Cependant, d'autres éléments de configuration tels que les règles de pare-feu NACL peuvent entrer en conflit avec les règles de l'interface réseau Elastic.

La configuration du VPC et du DNS du sous-réseau est mal configurée ou manquante

Révision Créer un VPC et des sous-réseaux pour les clusters Amazon EKS sur AWS Outposts.

Amazon EKS met automatiquement à jour tous les clusters locaux existants vers les dernières versions de plateforme correspondant à leur version mineure Kubernetes. Pour plus d’informations sur les versions de plateforme, veuillez consulter Découvrez les versions des plateformes Kubernetes et Amazon EKS pour AWS Outposts.

Lors d’un déploiement automatique de la version de plateforme, l’état du cluster passe à UPDATING. Le processus de mise à jour consiste à remplacer toutes les instances du plan de contrôle Kubernetes par de nouvelles instances contenant les derniers correctifs de sécurité et les dernières corrections de bogues publiés pour la version mineure respective de Kubernetes. En général, le processus de mise à jour d’une plateforme de cluster local s’effectue en moins de 30 minutes, après quoi le cluster revient à son état ACTIVE. Si un cluster local reste dans l’état UPDATING pendant une période prolongée, vous pouvez appeler describe-cluster pour obtenir des informations sur la cause dans le champ de sortie cluster.health.

Amazon EKS garantit qu’au moins deux des trois instances du plan de contrôle Kubernetes sont des nœuds de cluster sains et opérationnels afin de maintenir la disponibilité du cluster local et d’éviter toute interruption de service. Si un cluster local est bloqué dans un état UPDATING, c’est généralement parce qu’un problème d’infrastructure ou de configuration empêche de garantir la disponibilité minimale de deux instances dans le cas où le processus se poursuit. Le processus de mise à jour s’arrête donc afin de protéger le service de cluster local contre toute interruption.

Il est important de dépanner un cluster local bloqué dans son état UPDATING et de traiter la cause profonde afin que le processus de mise à jour puisse s’achever et restaurer le cluster local sur ACTIVE avec la haute disponibilité de 3 instances du plan de contrôle Kubernetes.

Ne terminez aucune instance Kubernetes de cluster local EKS géré sur Outposts, sauf instruction contraire explicite de l’assistance AWS. Ceci est particulièrement important pour les clusters locaux bloqués dans un état UPDATING, car il y a une forte probabilité qu’un autre nœud du plan de contrôle ne soit pas entièrement opérationnel et que la fermeture de la mauvaise instance puisse entraîner une interruption du service et un risque de perte de données du cluster local.

Les problèmes les plus courants sont les suivants :

Une ou plusieurs instances du plan de contrôle ne parviennent pas à se connecter à System Manager en raison d’une modification de la configuration réseau depuis la création initiale du cluster local. Vous pouvez le vérifier en appelant aws ssm start-session --target instance-id depuis un hôte bastion de la région. Si cette commande ne fonctionne pas, vérifiez si Systems Manager est exécuté sur l’instance du plan de contrôle.
Les nouvelles instances du plan de contrôle ne peuvent pas être créées en raison des autorisations de clé KMS pour les volumes EBS. Avec les clés KMS gérées par l’utilisateur pour les volumes EBS chiffrés, les instances du plan de contrôle seront interrompues si la clé n’est pas accessible. Si les instances sont arrêtées, passez à une clé KMS gérée par AWS ou assurez-vous que votre stratégie de clé gérée par l’utilisateur accorde les autorisations nécessaires au rôle du cluster.
Les instances du plan de contrôle Systems Manager ont peut-être perdu leur accès à Internet. Vérifiez si le sous-réseau que vous avez fourni lors de la création du cluster possède une passerelle NAT et un VPC avec une passerelle Internet. Utilisez l'analyseur d'accessibilité VPC pour vérifier si l'instance du plan de contrôle peut atteindre la passerelle Internet. Pour plus d'informations, consultez Getting started with VPC Reachability Analyzer (langue française non garantie). Si vos réseaux privés ne disposent pas d’une connexion Internet sortante, assurez-vous que tous les points de terminaison d’un VPC et le point de terminaison de passerelle requis sont toujours présents dans le sous-réseau régional de votre cluster (voir Accès au sous-réseau pour les services AWS).
Le rôle ARN que vous avez fourni ne contient pas de politiques. Vérifiez si la politique gérée par AWS : AmazonEKSLocalOutpostClusterPolicy n’a pas été supprimée du rôle.
L’une des nouvelles instances du plan de contrôle Kubernetes a peut-être subi une défaillance inattendue lors du démarrage. Veuillez envoyer une demande au centre d’assistance AWS pour obtenir des conseils supplémentaires sur le dépannage et la collecte des journaux dans ce cas exceptionnel.

Problèmes AMI :
- Vous utilisez une AMI non prise en charge. Vous devez utiliser la version v20220620 ou ultérieure pour créer des nœuds avec des AMI Amazon Linux optimisées pour Amazon EKS optimisées pour Amazon Linux.
- Si vous avez utilisé un modèle AWS CloudFormation pour créer vos nœuds, assurez-vous qu’il n’utilisait pas une AMI non prise en charge.
Le ConfigMap de l’authentificateur AWS IAM est manquant : s’il est manquant, vous devez le créer. Pour plus d’informations, consultez Appliquer la ConfigMap aws-auth à votre cluster.
Le mauvais groupe de sécurité est utilisé – Assurez-vous d'utiliser eks-cluster-sg-cluster-name-uniqueid pour le groupe de sécurité de vos composants master. Le groupe de sécurité sélectionné est modifié par AWS CloudFormation afin d’autoriser un nouveau groupe de sécurité à chaque utilisation de la pile.
Suite à des étapes inattendues liées à un VPC de lien privé – Des données CA incorrectes (--b64-cluster-ca) ou le mauvais point de terminaison de l'API (--apiserver-endpoint) sont transmis.

Lorsqu’un Outpost est déconnecté de la région AWS à laquelle il est associé, le cluster Kubernetes continuera probablement à fonctionner normalement. Toutefois, si le cluster ne fonctionne pas correctement, suivez les étapes de dépannage décrites dans la section Préparer les clusters Amazon EKS locaux sur AWS Outposts en cas de déconnexion réseau. Si vous rencontrez d’autres problèmes, contactez le service d’assistance AWS. AWS Support peut vous guider pour télécharger et exécuter un outil de collecte de journaux. De cette façon, vous pouvez collecter les journaux des instances du plan de contrôle de votre cluster Kubernetes et les envoyer au service d’assistance AWS pour une analyse plus approfondie.

Lorsque les instances du plan de contrôle Amazon EKS ne sont pas accessibles via AWS Systems Manager (Systems Manager), Amazon EKS affiche l’erreur suivante pour votre cluster.


Amazon EKS control plane instances are not reachable through SSM. Please verify your SSM and network configuration, and reference the EKS on Outposts troubleshooting documentation.

Pour résoudre ce problème, assurez-vous que votre VPC et vos sous-réseaux répondent aux exigences décrites dans Créer un VPC et des sous-réseaux pour les clusters Amazon EKS sur AWS Outposts et que vous avez suivi les étapes décrites dans Configuration de Session Manager dans le Guide de l’utilisateur AWS Systems Manager.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Considérations relatives à la capacité

Nœuds