Por que não consigo usar o kubectl para me conectar ao meu cluster EKS?

Resolução

Se não for possível se conectar ao seu cluster do Amazon EKS ao usar o kubectl, talvez tenha configurado incorretamente um serviço, uma permissão ou uma configuração. Também pode ocorrer um erro quando o ambiente local não consegue se comunicar com o servidor de API do cluster EKS. Solucione o problema com base na mensagem de erro recebida.

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.

Pré-requisitos:

• Execute o comando a seguir para verificar se o sistema pode estabelecer uma conexão com o cluster correto:

  kubectl config current-context

• Execute o seguinte comando get-caller-identity da AWS CLI para verificar se o usuário ou o perfil do AWS Identity and Access Management (AWS IAM) atualmente autenticado está correto:

  aws sts get-caller-identity

  Observação: permita que a entidade principal do IAM acesse objetos do Kubernetes em seu cluster com base no modo de autenticação do cluster.

Mensagem de erro "exec plugin invalid"

Quando a versão da API de autenticação no arquivo kubeconfig não é compatível com a versão do ambiente de gerenciamento da API Kubernetes, você recebe a seguinte mensagem de erro:

"exec plugin: invalid apiVersion "client.authentication.k8s.io/v1alpha""

Execute o seguinte comando update-kubeconfig para atualizar o arquivo kubeconfig do seu cluster:

aws eks update-kubeconfig --region region-code --name my-cluster

Observação: substitua region-code pela região da AWS em que seu cluster está e my-cluster pelo nome do seu cluster.

Sua versão do kubectl deve estar dentro de uma pequena diferença de versão anterior ou posterior do seu ambiente de gerenciamento de cluster do Amazon EKS. Por exemplo, um cliente kubectl versão 1.29 funciona com clusters Kubernetes 1.28, 1.29 e 1.30.

Mensagem de erro "couldn't get current server API group list"

Quando o arquivo kubeconfig não existe ou não contém a autoridade de certificação (CA), você recebe a seguinte mensagem de erro:

"couldn't get current server API group list: Get "https://xxxxxxxxxxxxxxxxxxxx..eks.amazonaws.com/api?timeout=32s": tls: failed to verify certificate: x509: certificate signed by unknown authority"

1. Execute o comando a seguir para verificar se o arquivo kubeconfig existe no local padrão (.kube) em seu diretório inicial:

   cat ~/.kube/config

2. Se o arquivo existir, verifique se a CA do cluster codificada em base64 está no arquivo kubeconfig. Além disso, verifique se o arquivo certificate-authority-data existe e se você o configurou corretamente.

3. Se o arquivo kubeconfig não existir, execute o seguinte comando para recriá-lo:

   kubectl get svc --insecure-skip-tls-verify

4. Verifique se você usa um proxy ou VPN que possa bloquear o TLS.

Mensagem de erro de tempo limite "could not get current server API group list"

Se o host de origem não conseguir se comunicar com o servidor da API na porta 443, a solicitação expirará e você receberá a seguinte mensagem de erro:

"could not get current server API group list: Get "https://xxxxxxxxxxxxxxxxxxxx.gr7.<region-code>.eks.amazonaws.com/api?timeout=32s": dial tcp xx.yy.zz.vvv:443: i/o timeout"

Execute o comando a seguir para usar o telnet na porta 443 para verificar a conectividade do endpoint do servidor de API em seu dispositivo:

$ echo exit | telnet

Exemplo de saída:

xxxxxxxxxxxxxxxxxxxx.gr7.us-east-2.eks.amazonaws.com 443Trying 18.224.160.210...
Connected to xxxxxxxxxxxxxxxxxxxx.gr7.us-east-2.eks.amazonaws.com.
Escape character is '^]'.
Connection closed by foreign host.

Se o comando telnet não resolver o problema, execute as seguintes ações:

• Se você ativou o acesso público no endpoint do servidor de API, verifique se restringiu o acesso ao endpoint do servidor de API a um determinado intervalo CIDR. Certifique-se de que o endereço IP do dispositivo pertença ao bloco CIDR. Além disso, verifique o comportamento de acesso ao endpoint do servidor de API.
• Se você ativou somente o acesso privado no endpoint do servidor de API, todo o tráfego do servidor de API do cluster deverá vir da nuvem privada virtual (VPC) ou de uma rede conectada. Além disso, os comandos kubectl devem vir de dentro da VPC ou de uma rede conectada. Para mais informações, consulte Acessar um servidor de API somente privado.
• Verifique se os grupos de segurança ou as listas de controle de acesso à rede (ACLs da rede) bloqueiam solicitações para o servidor da API Kubernetes. Certifique-se de que o grupo de segurança do cluster permita o tráfego na porta 443 a partir do CIDR de origem.

Mensagem de erro "couldn't get current API server group list"

Quando você tenta realizar uma ação sem permissão para acessar a API Kubernetes no cluster do Amazon EKS, você recebe a seguinte mensagem de erro:

"couldn't get current server API group list: the server has asked for the client to provide credentials"

Para solucionar esse problema, conclua as etapas a seguir:

1. Execute o comando get-caller-identity para verificar quem fez a solicitação para acessar o cluster EKS:

   aws sts get-caller-identity

   Exemplo de saída:

   {
    "UserId": "user-ID",
    "Account": "account-ID",
    "Arn": "arn:aws:iam::account-ID:user/kube-user"
   }

   Observação: o exemplo de saída anterior contém o ID do usuário, a conta da AWS e o ARN da entidade do IAM que fez a solicitação.

2. Altere o modo de autenticação para API_AND_CONFIG_MAP ou API e, em seguida, use as entradas de acesso do EKS para conceder aos usuários do IAM acesso ao Kubernetes.

3. Para conceder as permissões apropriadas, use o modo de autenticação API ou API_AND_CONFIG_MAP para adicionar a entrada da entidade do IAM.
   Modo de autenticação de API
   Execute o seguinte create-access-entry para criar uma entrada de acesso que permita que a entidade principal do IAM se autentique em seu cluster do Amazon EKS:

   aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:user/my-user --type STANDARD --username my-user

   Observação: no comando anterior, substitua o ARN da entidade principal pelo ARN da entidade do IAM.
   Execute o seguinte comando associate-access-policy para associar a entrada de acesso a uma política de acesso:

   aws eks associate-access-policy --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/my-role \
       --access-scope type=cluster --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy

   Modo de autenticação API_AND_CONFIG_MAP
   Para o modo de autenticação API_AND_CONFIG_MAP, é possível usar o modo de autenticação API anterior ou editar o configmap.
   Para editar o aws-auth configmap, execute o seguinte comando:

   kubectl edit configmap aws-auth -n kube-system

   Adicione seu perfil ou usuário do IAM à seção mapRoles ou mapUsers.
   Veja a seguir um exemplo de seção mapRoles com uma entrada para um perfil do IAM:

   mapRoles: |
       - groups:
         - system:masters
         rolearn: arn:aws:iam::111122223333:role/MyEKSrole
         username: eks-user

   Observação: substitua o ARN de exemplo pelo ARN do perfil do IAM. Se você estiver usando um usuário do IAM, substitua MapRoles por MapUsers e o ARN pelo ARN do usuário do IAM.

O exemplo anterior mapeia a entidade principal do IAM para o grupo system:masters que concede acesso administrativo total ao cluster. Para um acesso mais restrito, mapeie a entidade principal do IAM para um usuário ou grupo personalizado do Kubernetes e use os objetos de controle de acesso baseado em perfis (RBAC) do Kubernetes para definir as permissões necessárias. Para obter mais informações, consulte Using RBAC authorization (Uso da autorização RBAC) no site do Kubernetes.

Mensagem de erro "Did you specify the right host or port?"

Se você não configurou corretamente o arquivo kubeconfig, o kubectl não conseguirá se conectar ao cluster EKS e você receberá a seguinte mensagem de erro:

"The connection to the server localhost:8080 was refused - did you specify the right host or port?"

Para resolver esse problema, execute as seguintes ações:

• Execute o comando a seguir para atualizar o arquivo kubeconfig:

  aws eks update-kubeconfig --region region-code --name my-cluster

• Execute o comando a seguir para verificar o contexto atual em seu arquivo kubeconfig:

  kubectl config current-context

• Se a saída do comando current-context não apontar para o cluster EKS esperado, execute o seguinte comando:

  kubectl config use-context ;

Informações relacionadas

Conecte o kubectl a um cluster EKS criando um arquivo kubeconfig