Por que os nós de processamento não conseguiram se juntar ao meu cluster do Amazon EKS?

Breve descrição

Ao tentar juntar nós de processamento ao seu cluster do Amazon EKS, é possível enfrentar um dos seguintes problemas:

• Quando você cria um grupo de nós gerenciados no cluster do EKS, o grupo de nós gerenciados entra no estado de Falha na criação. Os nós de processamento não se juntam ao cluster do EKS e você recebe a mensagem de erro “Instances failed to join the kubernetes cluster”.
• Os novos nós de processamento não conseguem se juntar ao cluster do EKS quando você faz upgrade do grupo de nós gerenciados no cluster do EKS.

Resolução

Observação: se você receber erros ao executar comandos da AWS Command Line Interface (AWS CLI), consulte Solução de problemas da AWS CLI. Além disso, verifique se você está usando a versão mais recente da AWS CLI.

Use o runbook de automação do Systems Manager

Use o runbook AWSSupport-TroubleshootEKSWorkerNode para descobrir por que seus nós de processamento não estão se juntando ao seu cluster.

Importante: para que a automação funcione, seus nós de processamento devem ter permissão para acessar e executar o AWS Systems Manager. Para conceder permissão, anexe a política gerenciada pela AWS AmazonSSMManagedInstanceCore ao perfil do AWS Identity and Access Management (AWS IAM) que corresponde ao seu perfil de instância do Amazon Elastic Compute Cloud (Amazon EC2). Use a política AmazonSSMManagedInstanceCore como a configuração padrão para os grupos de nós gerenciados do Amazon EKS que você cria por meio do eksctl. Use o formato [-a-zA-Z0-9]{1,100}$ para o nome do seu cluster.

Para executar a automação, conclua as seguintes etapas:

1. No console do Systems Manager, abra o runbook AWSSupport-TroubleshootEKSWorkerNode.
2. Observação: consulte a seção Document details (Detalhes do documento) do runbook para obter mais informações sobre o runbook.
3. Verifique se você definiu a região da AWS como a mesma região do seu cluster.
4. Na seção Parâmetros de entrada, especifique o nome do seu cluster no campo ClusterName e o ID da instância do Amazon EC2 no campo WorkerID.
5. (Opcional) No campo AutomationAssumeRole, insira o nome do recurso da Amazon (ARN) do perfil do IAM que permite que a automação execute ações por você. Se você não especificar um perfil do IAM, a automação usará as permissões do usuário que inicia o runbook.
6. Selecione Executar.
7. Consulte a seção Saídas para identificar a causa do problema e as etapas que é possível tomar para resolvê-lo.

Verifique o suporte a DNS para sua Amazon VPC

Confirme se você ativou os nomes do host DNS e a resolução de DNS na Amazon Virtual Private Cloud (Amazon VPC) para seu cluster do EKS.

Verifique se os nós de processamento do seu perfil de instância têm as permissões corretas

Anexe as seguintes políticas gerenciadas pela AWS ao perfil associado aos nós de processamento do seu perfil de instância:

• AmazonEKSWorkerNodePolicy
• AmazonEKS_CNI_Policy
• AmazonEC2ContainerRegistryReadOnly

Certifique-se de que o limite de permissões ou a política de controle de serviços (SCP) no nível da organização ou da conta não restrinja o nó de processamento a fazer chamadas de API.

Configure os dados de usuário para seus nós de processamento

Observação: se você usar o AWS CloudFormation para iniciar seus nós de processamento, não precisará configurar os dados do usuário para esses nós. Em vez disso, use o console do CloudFormation para iniciar nós autogerenciados do Amazon Linux.

Se você iniciar seus nós de processamento usando grupos de nós gerenciados, não precisará configurar dados de usuário com as imagens de máquina da Amazon (AMI) do Amazon Linux otimizadas para o Amazon EKS. Configure os dados do usuário somente quando usar AMIs personalizadas para iniciar seus nós de processamento por meio de grupos de nós gerenciados.

Se estiver usando grupos de nós gerenciados pela Amazon EKS com um modelo de lançamento personalizado, especifique os dados do usuário corretos nesse modelo de lançamento. Se o cluster do Amazon EKS for um cluster totalmente privado que usa endpoints da VPC para se conectar, você deverá atualizar os dados do usuário. Especifique a autoridade de certificação (CA), o endpoint do servidor de API e o endereço IP do cluster DNS nos dados do usuário.

Exemplo de configuração de dados do usuário:

#!/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

Observação: substitua CA-CERT, ENDPOINT e IP-ADDRESS pelos valores da sua instância. Além disso, substitua ${ClusterName} pelo nome do seu cluster do EKS e ${BootstrapArguments} por valores adicionais de bootstrap, se necessário.

Se você precisar fornecer dados do usuário para passar argumentos para o arquivo bootstrap.sh incluído com uma AMI do Linux/Bottlerocket otimizada para Amazon EKS, especifique um ID de AMI no ImageField do seu modelo de lançamento.

Para configurar dados de usuários para seus nós de processamento, especifique esses dados ao executar suas instâncias do EC2.

Por exemplo, se você usa uma ferramenta de terceiros como o Terraform, atualize o campo de dados do usuário para iniciar seus nós de processamento do EKS.

Exemplo de configuração de dados do usuário:

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

Observação: substitua ${ClusterName} pelo nome do seu cluster do EKS e ${BootstrapArguments} por valores adicionais de bootstrap, se necessário.

Se você usa uma AMI do Amazon Linux 2023, adicione os parâmetros mínimos necessários aos dados do usuário no seguinte 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

--//--

Verifique se você configurou corretamente a rede para suas sub-redes da Amazon VPC e se seus nós de processamento estão na mesma Amazon VPC do seu cluster do EKS

Se você usa um gateway da internet, confirme se o anexou corretamente à tabela de rotas.

Se você usa um gateway NAT, certifique-se de que ele esteja configurado corretamente em uma sub-rede pública. Além disso, verifique se você configurou corretamente a tabela de rotas.

Se você usa endpoints privados da VPC para um cluster totalmente privado, certifique-se de ter os seguintes endpoints de interface:

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

Além disso, certifique-se de que você tem o endpoint do gateway, com.amazonaws.region.s3.

É possível restringir a política do endpoint da VPC do gateway do Amazon Simple Storage Service (Amazon S3) para o Amazon ECR. Para obter mais informações, consulte Permissões mínimas do bucket do Amazon S3 para o Amazon ECR.

Os pods que você configura com perfis do IAM para contas de serviço adquirem credenciais de uma chamada de API do AWS Security Token Service (AWS STS). Se não houver acesso externo à internet, você deve criar e usar um endpoint da VPC do AWS STS na sua VPC.

O grupo de segurança do endpoint de VPC deve ter uma regra de entrada que permita o tráfego da porta 443. Para obter mais informações, consulte Controle o tráfego para seus recursos da AWS usando grupos de segurança.

Certifique-se de que a política anexada ao endpoint da VPC tenha as permissões necessárias para fazer chamadas de API para o serviço específico.

Na seção Rede do cluster do EKS, identifique as sub-redes associadas ao seu cluster. Confirme se elas pertencem à mesma VPC.

Você deve criar endpoints separados para cada serviço da AWS que você usa. Para obter uma lista de endpoints para serviços comuns da AWS, consulte a tabela em Requisitos do pod. Além disso, também é possível criar um serviço de endpoint com base no seu caso de uso.

Também é possível configurar diferentes sub-redes nas quais iniciar seus nós de processamento. Essas sub-redes devem existir na mesma Amazon VPC e estar devidamente etiquetadas. O Amazon EKS gerencia etiquetas automaticamente somente para sub-redes que você configura durante a criação do cluster. Para obter mais informações, consulte Requisitos e considerações para sub-redes.

Atualize o aws-auth ConfigMap com o NodeInstanceRole dos seus nós de processamento

Verifique se aws-auth ConfigMap está configurado corretamente com o perfil do IAM do seu nó de processamento e não com o perfil de instância.

Execute o seguinte comando:

kubectl describe configmap -n kube-system aws-auth

Se você não configurou corretamente o aws-auth ConfigMap, receberá a seguinte mensagem de erro:

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

Se você usar o método de autenticação da API do EKS, crie uma entrada de acesso para o NodeInstanceRole. Em Tipo, selecione EC2_linux.

Atenda aos requisitos de grupo de segurança de seus nós de processamento

Confirme se você configurou o grupo de segurança do seu ambiente de gerenciamento e o grupo de segurança do seu nó de processamento com as configurações necessárias para tráfego interno e externo. Além disso, confirme se você configurou as regras da sua lista de controle de acesso à rede (ACL da rede) para permitir o tráfego de e para 0.0.0.0/0 nas portas 80, 443 e 1025-65535.

Defina as etiquetas para seus nós de processamento

Para a propriedade Tag dos seus nós de processamento, defina Key como kubernetes.io/cluster/clusterName e Value como owned.

Para mais informações, consulte Requisitos e considerações para VPCs.

Confirme se os seus nós de processamento podem acessar o endpoint do servidor de APIs do seu cluster do EKS

Inicie nós de processamento em uma sub-rede associada a uma tabela de rotas que roteia para o endpoint de API por meio de um gateway NAT ou da internet. Se você iniciar seus nós de processamento em uma rede privada restrita, confirme se esses nós podem acessar o endpoint do servidor de APIs do EKS. Se você iniciar nós de processamento com uma Amazon VPC que usa um DNS personalizado em vez de AmazonProvidedDNS, talvez eles não resolvam o endpoint.

Observação: o endpoint não é resolvido quando você desativa o acesso público ao endpoint e ativa somente o acesso privado. Para obter mais informações, consulte Turning on DNS resolution for Amazon EKS cluster endpoints (Ativar a resolução de DNS para endpoints de cluster do Amazon EKS).

Confirme se o kubelet pode alcançar os endpoints necessários

Execute os seguintes comandos para testar se o kubelet pode alcançar os endpoints:

$ 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

Observação: substitua region pela sua região.

Confirme se você configurou corretamente o perfil do cluster

Você deve anexar AmazonEKSClusterPolicy ao seu perfil do IAM do cluster do Amazon EKS. Além disso, a relação de confiança do seu cluster deve permitir o serviço eks.amazonaws.com para sts:AssumeRole.

Exemplo de política de confiança:

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

Confirme se você ativou os endpoints regionais do STS

Se o cluster estiver em uma região com suporte para endpoints do STS, ative o endpoint regional do STS para autenticar o kubelet. O kubelet pode então criar o objeto do nó.

Verifique se você configurou sua AMI para funcionar com o EKS e se a AMI inclui os componentes necessários

A AMI do Amazon Linux otimizada para Amazon EKS contém os componentes necessários para trabalhar com o cluster do EKS. Se a AMI dos nós de processamento não for a AMI do Amazon Linux otimizada para o Amazon EKS, confirme se os seguintes componentes do Kubernetes estão em estado Ativo:

• kubelet
• AWS IAM Authenticator
• Docker (Amazon EKS versão 1.23 e anteriores)
• containerd

Use SSH para conectar-se à sua instância de nó de processamento do EKS e verifique os logs de agente kubelet

Verifique se você configurou o agente kubelet como um serviço systemd na instância do nó de processamento do EKS.

Para validar seus logs do kubelet, execute o seguinte comando:

journalctl -f -u kubelet

Para resolver problemas, consulte Solucionar problemas com clusters e nós do Amazon EKS.

Use o script do coletor de logs do Amazon EKS para solucionar erros

Use os arquivos de log e os logs do sistema operacional para solucionar os problemas no seu cluster do Amazon EKS. Os nós de processamento do cluster do Amazon EKS armazenam logs de inicialização cloud-init em /var/log/cloud-init-output.log e /var/log/cloud-init.log.

Para usar o script do coletor de logs do EKS para coletar logs, você deve usar o SSH para se conectar ao nó de processamento que apresenta o problema. Em seguida, execute o seguinte 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

Confirme se as sub-redes da Amazon VPC para o nó de processamento têm endereços IP disponíveis

Se sua Amazon VPC não tiver endereços IP disponíveis, é possível associar um CIDR secundário à sua Amazon VPC existente. Para obter mais informações, consulte Exibir os requisitos de rede do Amazon EKS para VPC e sub-redes. A AMI otimizada para EKS contém os componentes necessários para trabalhar com o cluster do EKS.