Solucionar problemas de clusters locais do Amazon EKS em AWS Outposts

Os clusters locais são criados por meio da API do Amazon EKS, mas são executados de maneira assíncrona. Isso significa que as solicitações à API do Amazon EKS retornam imediatamente para os clusters locais. Porém, essas solicitações podem ser bem-sucedidas, antecipar-se à falha devido a erros de validação de entrada ou falhar e ter erros de validação descritivos. Esse comportamento é semelhante ao da API do Kubernetes.

Os clusters locais não fazem a transição para um status FAILED. O Amazon EKS tenta continuamente reconciliar o estado do cluster com o estado desejado solicitado pelo usuário. Como resultado, um cluster local pode permanecer no estado CREATING por um período prolongado até que o problema subjacente seja resolvido.

Os problemas do cluster local podem ser descobertos usando o comando describe-cluster do Amazon EKS AWS CLI. Problemas de cluster local são revelados pelo campo cluster.health da resposta do comando describe-cluster. A mensagem contida nesse campo inclui um código de erro, uma mensagem descritiva e IDs de recursos relacionados. Essas informações estão disponíveis somente por meio da API do Amazon EKS e da AWS CLI. No exemplo a seguir, substitua my-cluster pelo nome do cluster local.


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

Veja um exemplo de saída abaixo.


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

Se o problema não puder ser reparado, talvez seja necessário excluir o cluster local e criar um novo. Por exemplo, tentar provisionar um cluster com um tipo de instância que não está disponível no Outpost. A tabela a seguir inclui erros comuns relacionados à integridade.

Cenário de erro	Código	Mensagem	ResourceIds
Não foi possível encontrar as sub-redes fornecidas.	`ResourceNotFound`	`The subnet ID subnet-id does not exist`	Todos os IDs de sub-rede fornecidos
As sub-redes fornecidas não pertencem à mesma VPC.	`ConfigurationConflict`	`Subnets specified must belong to the same VPC`	Todos os IDs de sub-rede fornecidos
Algumas sub-redes fornecidas não pertencem ao Outpost especificado.	`ConfigurationConflict`	`Subnet subnet-id expected to be in outpost-arn, but is in other-outpost-arn`	ID de sub-rede problemática
Algumas sub-redes fornecidas não pertencem a nenhum Outpost.	`ConfigurationConflict`	`Subnet subnet-id is not part of any Outpost`	ID de sub-rede problemática
Algumas sub-redes fornecidas não têm endereços livres suficientes para a criação de interfaces de rede elásticas para as instâncias do ambiente de gerenciamento.	`ResourceLimitExceeded`	`The specified subnet does not have enough free addresses to satisfy the request.`	ID de sub-rede problemática
O tipo de instância do ambiente de gerenciamento especificado não é compatível com o Outpost.	`ConfigurationConflict`	`The instance type type is not supported in Outpost outpost-arn`	ARN do cluster
Você encerrou uma instância do Amazon EC2 do ambiente de gerenciamento ou `run-instance` teve êxito, mas o estado sofreu alterações para `Terminated`. Isso pode acontecer por um período após a reconexão do Outpost e os erros internos do Amazon EBS causarem uma falha no fluxo de trabalho interno do Amazon EC2.	`InternalFailure`	`EC2 instance state "Terminated" is unexpected`	ARN do cluster
Você não tem capacidade suficiente no Outpost. Isso também pode acontecer quando um cluster estiver sendo criado se um Outpost for desconectado da região da AWS.	`ResourceLimitExceeded`	`There is not enough capacity on the Outpost to launch or start the instance.`	ARN do cluster
A conta excedeu a cota de grupo de segurança.	`ResourceLimitExceeded`	Mensagem de erro retornada pela API do Amazon EC2	ID da VPC de destino
A conta excedeu a cota de interface de rede elástica.	`ResourceLimitExceeded`	Mensagem de erro retornada pela API do Amazon EC2	ID da sub-rede de destino
As instâncias do ambiente de gerenciamento não eram acessíveis por meio do AWS Systems Manager. Para saber a resolução, consulte As instâncias do ambiente de gerenciamento não podem ser acessadas por meio do AWS Systems Manager.	`ClusterUnreachable`	As instâncias do ambiente de gerenciamento do Amazon EKS não podem ser acessadas por meio do SSM. Verifique a configuração do SSM e da rede e consulte a documentação de solução de problemas do EKS no Outposts.	IDs de instâncias do Amazon EC2
Ocorreu um erro ao obter detalhes de um grupo de segurança gerenciado ou de uma interface de rede elástica.	Com base no código de erro do cliente Amazon EC2.	Mensagem de erro retornada pela API do Amazon EC2	Todos os IDs de grupos de segurança gerenciados
Ocorreu um erro ao autorizar ou revogar as regras de ingresso de grupo de segurança. Isso se aplica aos grupos de segurança do cluster e do ambiente de gerenciamento.	Com base no código de erro do cliente Amazon EC2.	Mensagem de erro retornada pela API do Amazon EC2	ID de grupo de segurança problemático
Ocorreu um erro ao excluir uma interface de rede elástica de uma instância do ambiente de gerenciamento.	Com base no código de erro do cliente Amazon EC2.	Mensagem de erro retornada pela API do Amazon EC2	ID de interface de rede elástica problemática

A tabela a seguir lista os erros de outros serviços do AWS que são apresentados no campo health da resposta do describe-cluster.

Código de erro do Amazon EC2	Código de problema de integridade do cluster	Descrição
`AuthFailure`	`AccessDenied`	Esse erro pode ocorrer por vários motivos. O motivo mais comum é que você acidentalmente removeu do serviço do ambiente de gerenciamento uma tag que o serviço usa para reduzir o escopo da política de perfil vinculada. Se isso ocorrer, o Amazon EKS não poderá mais gerenciar e monitorar esses recursos da AWS.
`UnauthorizedOperation`	`AccessDenied`	Esse erro pode ocorrer por vários motivos. O motivo mais comum é que você acidentalmente removeu do serviço do ambiente de gerenciamento uma tag que o serviço usa para reduzir o escopo da política de perfil vinculada. Se isso ocorrer, o Amazon EKS não poderá mais gerenciar e monitorar esses recursos da AWS.
`InvalidSubnetID.NotFound`	`ResourceNotFound`	Esse erro ocorre quando o ID da sub-rede para as regras de ingresso de um grupo de segurança não pode ser encontrado.
`InvalidPermission.NotFound`	`ResourceNotFound`	Esse erro ocorre quando as permissões para as regras de ingresso de um grupo de segurança não estão corretas.
`InvalidGroup.NotFound`	`ResourceNotFound`	Esse erro ocorre quando o grupo das regras de ingresso de um grupo de segurança não pode ser encontrado.
`InvalidNetworkInterfaceID.NotFound`	`ResourceNotFound`	Esse erro ocorre quando o ID da interface de rede para as regras de ingresso de um grupo de segurança não pode ser encontrado.
`InsufficientFreeAddressesInSubnet`	`ResourceLimitExceeded`	Esse erro ocorre quando a cota de recursos da sub-rede é excedida.
`InsufficientCapacityOnOutpost`	`ResourceLimitExceeded`	Esse erro ocorre quando a cota de capacidade do outpost é excedida.
`NetworkInterfaceLimitExceeded`	`ResourceLimitExceeded`	Esse erro ocorre quando a cota de interface de rede elástica é excedida.
`SecurityGroupLimitExceeded`	`ResourceLimitExceeded`	Esse erro ocorre quando a cota de capacidade do grupo de segurança é excedida.
`VcpuLimitExceeded`	`ResourceLimitExceeded`	Isso é observado na criação de uma instância do Amazon EC2 em uma nova conta. O procedimento pode ser semelhante ao seguinte: "`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`	O Amazon EC2 retornará esse código de erro se não houver suporte no Outpost para o tipo de instância especificado.
Todas as outras falhas	`InternalFailure`	Nenhum

Os clusters locais exigem permissões e políticas diferentes das exigidas pelos clusters do Amazon EKS hospedados na nuvem. Quando a criação do cluster falhar e gera um erro InvalidPermissions, verifique novamente se o perfil do cluster que você está usando tem a política gerenciada AmazonEKSLocalOutpostClusterPolicy anexada a ele. Todas as outras chamadas de API exigem o mesmo conjunto de permissões que os clusters do Amazon EKS na nuvem.

O tempo necessário para criar um cluster local varia dependendo de vários fatores. Esses fatores incluem a configuração da rede, a configuração do Outpost e a configuração do cluster. Em geral, um cluster local é criado e passa para o status ACTIVE dentro de 15 a 20 minutos. Se um cluster local permanecer no estado CREATING, você poderá chamar describe-cluster para obter informações sobre a causa no campo de saída cluster.health.

Os problemas mais comuns são os seguintes:

Seu cluster não pode se conectar à instância do ambiente de gerenciamento da região AWS em que o Systems Manager está. Você pode verificar isso chamando aws ssm start-session --target instance-id em um bastion host na região. Se esse comando não funcionar, verifique se o Systems Manager está sendo executado na instância do ambiente de gerenciamento. Outra solução de contorno é excluir o cluster e depois recriá-lo.
As instâncias do ambiente de gerenciamento do Systems Manager podem não ter acesso à Internet. Verifique se a sub-rede que você forneceu ao criar o cluster tem um gateway NAT e uma VPC com um gateway da internet. Use o analisador de acessibilidade da VPC para verificar se a instância do ambiente de gerenciamento pode acessar o gateway da Internet. Para obter mais informações, consulte Getting started with VPC Reachability Analyzer (Conceitos básicos do VPC Reachability Analyzer).
O ARN de perfil fornecido não tem políticas. Verifique se a política gerenciada da AWS: AmazonEKSLocalOutpostClusterPolicy foi removida do perfil. Isso também pode ocorrer se uma pilha do AWS CloudFormation estiver mal configurada.
Todas as sub-redes fornecidas devem estar associadas ao mesmo Outpost e devem alcançar umas às outras. Quando várias sub-redes são especificadas durante a criação do cluster, o Amazon EKS tenta distribuir as instâncias do ambiente de gerenciamento entre várias sub-redes.
Os grupos de segurança gerenciados pelo Amazon EKS são aplicados à interface de rede elástica. No entanto, outros elementos da configuração, como regras de firewall NACL, podem entrar em conflito com as regras da interface de rede elástica.

A VPC e o DNS da sub-rede estão mal configurados ou falta a configuração

Revisão Crie um VPC e sub-redes para clusters do Amazon EKS em AWS Outposts.

Problemas de AMI:
- Você está usando uma AMI incompatível. Você deve usar a versão v20220620 ou posterior para Criar nós com AMIs otimizadas do Amazon Linux Amazon EKS otimizado para Amazon Linux.
- Se você usou um modelo do AWS CloudFormation para criar seus nós, verifique se ele não estava usando uma AMI sem suporte.
O ConfigMap do autenticador do AWS IAM está ausente: nesse caso, é necessário criá-lo. Para obter mais informações, consulteComo aplicar o ConfigMapaws-auth ao seu cluster
O grupo de segurança errado é usado: certifique-se de usar eks-cluster-sg-cluster-name-uniqueid para o grupo de segurança dos nós de processamento. O grupo de segurança selecionado é alterado pelo AWS CloudFormation para permitir um novo grupo de segurança sempre que a pilha for usada.
Seguir etapas inesperadas de uma VPC de link privado: são especificados dados de CA (--b64-cluster-ca) ou endpoint de API (--apiserver-endpoint) incorretos.
Política de segurança de Pod mal configurada:
- Os daemonsets CoreDNS e Amazon VPC CNI plugin for Kubernetes devem ser executados nos nós para que eles se integrem e se comuniquem com o cluster.
- O Amazon VPC CNI plugin for Kubernetes requer alguns recursos de rede privilegiada para funcionar corretamente. É possível visualizar os recursos de rede privilegiada com o seguinte comando: kubectl describe psp eks.privileged.
Recomendamos que você não modifique a política padrão de segurança de pods. Para ter mais informações, consulte Compreensão das políticas de segurança de Pod(PSP) criadas pelo Amazon EKS.

Quando um Outpost é desconectado da região da AWS à qual está associado, o cluster Kubernetes provavelmente continuará funcionando normalmente. No entanto, se o cluster não funcionar corretamente, siga as etapas de solução de problemas em Preparar clusters locais do Amazon EKS no AWS Outposts para desconexões de rede. Se encontrar outros problemas, entre em contato com o suporte AWS. AWS O suporte pode orientar você sobre como baixar e executar uma ferramenta de coleta de logs. Dessa forma, você pode coletar logs das instâncias do ambiente de gerenciamento do cluster Kubernetes e enviá-los para o suporte do AWS Support para investigação adicional.

Quando as instâncias do ambiente de gerenciamento do Amazon EKS não podem ser acessadas pelo AWS Systems Manager (Systems Manager), o Amazon EKS exibe o seguinte erro para o seu 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.

Para resolver esse problema, verifique se a VPC e as sub-redes atendem aos requisitos em Criar uma VPC e sub-redes para clusters do Amazon EKS em AWS Outposts e se você concluiu as etapas em Configurar o Session Manager no Guia do usuário do AWS Systems Manager.