¿Por qué los nodos de trabajo no se unieron a mi clúster de Amazon EKS?

Descripción corta

Al intentar unir nodos de trabajo a su clúster de Amazon EKS, es posible que experimentes uno de los siguientes problemas:

• Al crear un grupo de nodos administrados en el clúster de EKS, el grupo de nodos administrados pasa al estado Error al crear. Los nodos de trabajo no se unen al clúster de EKS y recibirás el mensaje de error «Instances failed to join the kubernetes cluster».
• Los nuevos nodos de trabajo no se unen al clúster de EKS cuando se actualiza el grupo de nodos administrados en el clúster de EKS.

Resolución

Nota: Si se muestran errores al ejecutar comandos de la Interfaz de la línea de comandos de AWS (AWS CLI), consulta Solución de problemas de AWS CLI. Además, asegúrate de utilizar la versión más reciente de la AWS CLI.

Utilización del runbook de Automatización de Systems Manager

Usa el runbook AWSSupport-TroubleshootEKSWorkerNode para determinar por qué los nodos de trabajo no se unen al clúster.

Importante: Para que la automatización funcione, los nodos de trabajo deben tener permiso para acceder a AWS Systems Manager y ejecutarlo. Para conceder el permiso, adjunta la política administrada de AWS AmazonSSMManagedInstanceCore al rol de AWS Identity and Access Management (IAM) de tu perfil de instancia de Amazon Elastic Compute Cloud (Amazon EC2). Utiliza la política AmazonSSMManagedInstanceCore como configuración predeterminada para los grupos de nodos administrados de Amazon EKS que crees a través de eksctl. Usa el formato [-a-zA-Z0-9]{1,100}$ para el nombre de tu clúster.

Para ejecutar la automatización, sigue estos pasos:

1. En la consola de Systems Manager, abre el runbook AWSSupport-TroubleshootEKSWorkerNode.
2. Nota: Consulta la sección Detalles del documento del runbook para obtener más información sobre este.
3. Comprueba que has establecido la región de AWS en la misma región que tu clúster.
4. En la sección Parámetros de entrada, introduce el nombre del clúster en el campo ClusterName y el ID de instancia de Amazon EC2 en el campo WorkerID.
5. (Opcional) En el campo AutomationAssumeRole, introduce el nombre del recurso de Amazon (ARN) del rol de IAM que permite a la automatización realizar acciones por ti. Si no especificas un rol de IAM, la automatización usa los permisos del usuario que inicia el runbook.
6. Selecciona Ejecutar.
7. Revisa la sección Salidas para determinar la causa del problema y los pasos que puedes tomar para resolverlo.

Comprobación de la compatibilidad de DNS para tu Amazon VPC

Confirma que has activado los nombres de host DNS y la resolución de DNS en Amazon Virtual Private Cloud (Amazon VPC) para tu clúster de EKS.

Comprobación de que los nodos de trabajo del perfil de instancia tengan los permisos correctos

Adjunta las siguientes políticas administradas de AWS al rol asociado a los nodos de trabajo de tu perfil de instancia: 

• AmazonEKSWorkerNodePolicy
• AmazonEKS_CNI_Policy
• AmazonEC2ContainerRegistryReadOnly

Asegúrate de que el límite de permisos o la política de control de servicio (SCP) a nivel de organización o cuenta no restrinjan el nodo de trabajo para realizar llamadas a la API. 

Configuración de los datos de usuario para tus nodos de trabajo

Nota: Si usas AWS CloudFormation para iniciar tus nodos de trabajo, no tienes que configurar los datos de usuario de tus nodos de trabajo. En su lugar, utiliza la consola de CloudFormation para iniciar nodos de Amazon Linux autoadministrados.

Si utilizas grupos de nodos administrados para iniciar tus nodos de trabajo, no tendrás que configurar ningún dato de usuario con las imágenes de máquina de Amazon (AMI) de Amazon Linux optimizadas para Amazon EKS. Configura los datos de usuario si utilizas AMI personalizadas para iniciar tus nodos de trabajo mediante grupos de nodos administrados.

Si utilizas grupos de nodos administrados por Amazon EKS con una plantilla de inicio personalizada, especifica los datos de usuario correctos en la plantilla de inicio. Si el clúster de Amazon EKS es un clúster totalmente privado que usa puntos de enlace de VPC para conectarse, debes actualizar los datos de usuario. Especifica la autoridad de certificación (CA), el punto de enlace del servidor de API y la dirección IP del clúster de DNS en los datos de usuario.

Ejemplo de configuración de datos de usuario:

#!/bin/bash
set -ex
B64_CLUSTER_CA=CA-CERT
API_SERVER_URL=ENDPOINT
K8S_CLUSTER_DNS_IP=IP-ADDRESS
/etc/eks/bootstrap.sh ${ClusterName} ${BootstrapArguments} —b64-cluster-ca $B64_CLUSTER_CA —apiserver-endpoint $API_SERVER_URL —dns-cluster-ip $K8S_CLUSTER_DNS_I

Nota: Sustituye CA-CERT, ENDPOINT y IP-ADDRESS por los valores de tu instancia. Además, sustituye ${ClusterName} por el nombre de tu clúster de EKS y ${BootstrapArguments} por los valores de arranque adicionales, si es necesario.

Si debes proporcionar datos de usuario para pasar argumentos al archivo bootstrap.sh para la AMI de Linux/Bottlerocket optimizada para Amazon EKS, especifica un ID de AMI en el campo ImageField de la plantilla de inicio.

Para configurar los datos de usuario de tus nodos de trabajo, especifica los datos de usuario al iniciar las instancias de EC2.

Por ejemplo, si utilizas una herramienta de terceros, como Terraform, actualiza el campo de datos de usuario para iniciar tus nodos de trabajo de EKS.

Ejemplo de configuración de datos de usuario:

#!/bin/bash
set -o xtrace
/etc/eks/bootstrap.sh ${ClusterName} ${BootstrapArguments}

Nota: Sustituye ${ClusterName} por el nombre de tu clúster de EKS y ${BootstrapArguments} por los valores de arranque adicionales, si es necesario.

Si utilizas una AMI de Amazon Linux 2023, agrega los parámetros mínimos requeridos a los datos de usuario en el siguiente formato:

MIME-Version: 1.0Content-Type: multipart/mixed; boundary="//"

--//
Content-Type: application/node.eks.aws

---
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  cluster:
    apiServerEndpoint: https://example.com
    certificateAuthority: Y2VydGlmaWNhdGVBdXRob3JpdHk=
    cidr: 10.100.0.0/16
    name: my-cluster

--//--

Comprueba que has configurado correctamente la red para las subredes de Amazon VPC y que tus nodos de trabajo se encuentran en la misma Amazon VPC que tu clúster de EKS

Si utilizas una puerta de enlace de Internet, confirma que la has adjuntado correctamente a la tabla de enrutamiento.

Si utilizas una puerta de enlace de NAT, asegúrate de que esté configurada correctamente en una subred pública. Comprueba también que has configurado correctamente la tabla de enrutamiento.

Si utilizas puntos de enlace privados de VPC para un clúster totalmente privado, confirma que tienes los siguientes puntos de enlace de interfaz:

• com.amazonaws.region.ec2
• com.amazonaws.region.ecr.api
• com.amazonaws.region.ecr.dkr
• com.amazonaws.region.sts

Además, asegúrate de tener el punto de enlace de puerta de enlace, com.amazonaws.region.s3.

Puedes restringir la política de puntos de enlace de VPC de la puerta de enlace de enlace de Amazon Simple Storage Service (Amazon S3) para Amazon ECR. Para obtener más información, consulta Permisos mínimos de los buckets de Amazon S3 para Amazon ECR.

Los pods que se configuran con los roles de IAM para las cuentas de servicio obtienen las credenciales de una llamada a la API de AWS Security Token Service (AWS STS). Si no hay acceso saliente a Internet, debes crear y usar un punto de enlace de AWS STS VPC en tu VPC.

El grupo de seguridad del punto de enlace de VPC debe tener una regla de entrada que permita el tráfico desde el puerto 443. Para obtener más información, consulta Controlar el tráfico hacia los recursos de AWS mediante grupos de seguridad.

Asegúrate de que la política adjunta al punto de enlace de VPC tenga los permisos requeridos para realizar llamadas a la API al servicio específico.

En la sección Redes del clúster de EKS, identifica las subredes asociadas a tu clúster. Confirma que pertenecen a la misma VPC.

Debes crear puntos de enlace independientes para cada servicio de AWS que utilices. Para obtener una lista de los puntos de enlace de los servicios comunes de AWS, consulta la tabla en Requisitos del pod. También puedes crear un servicio de punto de enlace en función de tu caso de uso.

Además, puedes configurar diferentes subredes para iniciar tus nodos de trabajo. Las subredes deben existir en la misma Amazon VPC y debes etiquetarlas adecuadamente. Amazon EKS solo administra automáticamente las etiquetas para las subredes que se configuran durante la creación del clúster. Para obtener más información, consulta Requisitos y consideraciones de la subred.

Actualización del archivo ConfigMap aws-auth con el rol NodeInstanceRole de los nodos de trabajo

Comprueba que has configurado correctamente el archivo ConfigMap aws-auth con el rol de IAM del nodo de trabajo y no con el perfil de instancia.

Ejecuta el siguiente comando:

kubectl describe configmap -n kube-system aws-auth

Si no has configurado correctamente el archivo ConfigMap aws-auth, recibirás el siguiente mensaje de error:

«571 reflector.go:153] k8s.io/kubernetes/pkg/kubelet/kubelet.go:458: Failed to list *v1.Node: Unauthorized»

Si usas el método de autenticación de la API de EKS, crea una entrada de acceso para el NodeInstanceRole. En Tipo, selecciona EC2_linux.

Cumplimiento de los requisitos del grupo de seguridad de los nodos de trabajo

Confirma que has configurado el grupo de seguridad del plano de control y el del nodo de trabajo con los ajustes requeridos para tráfico de entrada y salida. Además, confirma que has configurado las reglas de la lista de control de acceso de la red (ACL de la red) para permitir el tráfico hacia y desde 0.0.0.0/0 para los puertos 80, 443 y 1025-65535.

Definición de las etiquetas para tus nodos de trabajo

Para la propiedad Tag de tus nodos de trabajo, configura Key como kubernetes.io/cluster/clusterName y configura Value como owned.

Para obtener más información, consulta Requisitos y consideraciones de la VPC.

Comprobación de que los nodos de trabajo lleguen al punto de enlace del servidor de API del clúster de EKS

Inicia nodos de trabajo en una subred que esté asociada a una tabla de enrutamiento que dirija al punto de enlace de la API a través de una puerta de enlace de Internet o NAT. Si inicias tus nodos de trabajo en una red privada restringida, confirma que tus nodos de trabajo lleguen al punto de enlace del servidor de API de EKS. Si inicias los nodos de trabajo con una Amazon VPC que usa un DNS personalizado en lugar de AmazonProvidedDNS, es posible que los nodos de trabajo no resuelvan el punto de enlace.

Nota: El punto de enlace no se resuelve cuando se desactiva el acceso público al punto de enlace y se activa solo el acceso privado. Para obtener más información, consulta Enabling DNS resolution for Amazon EKS cluster endpoints (Activación de la resolución de DNS para los puntos de enlace del clúster de Amazon EKS).

Confirmar si el kubelet puede llegar a los puntos de enlace requeridos

Ejecuta los siguientes comandos para comprobar si el kubelet puede llegar a los puntos de enlace:

$ nc -vz ec2.region.amazonaws.com 443

$ nc -vz dkr.ecr.region.amazonaws.com 443

$ nc -vz api.ecr.region.amazonaws.com 443

$ nc -vz s3.region.amazonaws.com 443

Nota: Sustituye region por tu región.

Confirmar que se ha configurado correctamente el rol del clúster

Debes adjuntar AmazonEKSClusterPolicy a tu rol de IAM del clúster de Amazon EKS. Además, la relación de confianza de tu clúster debe permitir el servicio eks.amazonaws.com para sts:AssumeRole.

Ejemplo de política de confianza:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "eks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Confirmar que se han activado los puntos de enlace STS regionales

Si el clúster se encuentra en una región que admite puntos de enlace STS, activa el punto de enlace STS regional para autenticar el kubelet. A continuación, el kubelet puede crear el objeto de nodo.

Asegurarse de que se ha configurado la AMI para que funcione con EKS y de que la AMI incluye los componentes necesarios

La AMI de Amazon Linux optimizada para Amazon EKS contiene los componentes necesarios para funcionar con el clúster de EKS. Si la AMI de los nodos de trabajo no es la AMI de Amazon Linux optimizada para Amazon EKS, confirma que los siguientes componentes de Kubernetes estén en estado activo:

• kubelet
• Autenticador de AWS IAM
• Docker (Amazon EKS versión 1.23 y anteriores)
• containerd

Uso de SSH para conectarse a la instancia del nodo de trabajo de EKS y comprobar los registros del agente de kubelet

Comprueba que has configurado el agente de kubelet como un servicio systemd en la instancia del nodo de trabajo de EKS.

Para validar tus registros de kubelet, ejecuta el siguiente comando:

journalctl -f -u kubelet

Para resolver problemas, consulta Solución de problemas con los clústeres y nodos de Amazon EKS.

Uso del script del recopilador de registros de Amazon EKS para solucionar errores

Utiliza los archivos de registro y los registros del sistema operativo (SO) para solucionar los problemas en tu clúster de Amazon EKS. Los nodos de trabajo del clúster de Amazon EKS almacenan los registros de inicialización de cloud-init en /var/log/cloud-init-output.log y /var/log/cloud-init.log.

Para usar el script del recopilador de registros de EKS para recopilar registros, debes usar SSH para conectarte al nodo de trabajo que tiene el problema. A continuación, ejecuta el siguiente script:

curl -O https://raw.githubusercontent.com/awslabs/amazon-eks-ami/master/log-collector-script/linux/eks-log-collector.sh

sudo bash eks-log-collector.sh

Confirmación de la disponibilidad de direcciones IP para las subredes de Amazon VPC del nodo de trabajo

Si tu Amazon VPC no tiene direcciones IP disponibles, puedes asociar un CIDR secundario a tu Amazon VPC existente. Para obtener más información, consulta Requisitos de red de Amazon EKS para VPC y subredes. La AMI optimizada para EKS contiene los componentes necesarios para funcionar con el clúster de EKS.