View a markdown version of this page

Início rápido: OTel Container Insights no Amazon EKS - Amazon CloudWatch
Pré-requisitosAtive o OTel Container Insights (console)Ative o OTel Container Insights (AWS CLI)Verificar os dados no CloudWatchSolução de problemas

Início rápido: OTel Container Insights no Amazon EKS

Este guia explica como ativar o OTel Container Insights em um cluster existente do Amazon EKS. Ao final desse procedimento, seu cluster envia métricas de infraestrutura e logs de contêineres para o Amazon CloudWatch com o Enhanced Observability ativado.

Você pode ativar o OTel Container Insights de duas maneiras: usando o AWS Management Console (mais rápido) ou usando a AWS CLI. Ambas as abordagens instalam o mesmo complemento amazon-cloudwatch-observability EKS com a configuração do OTel Container Insights. Você não precisa da implantação manual de atendentes, charts do Helm ou pipelines de coletores personalizados. Todo o processo leva menos de 5 minutos.

Pré-requisitos

Antes de ativar o OTel Container Insights, verifique se você atende aos seguintes requisitos.

  • Um cluster existente do Amazon EKS executando o Kubernetes versão 1.28 ou posterior

  • Versão da plataforma eks.1 ou posterior

  • Versão 6.2.0 ou mais recente do complemento amazon-cloudwatch-observability

  • AWS CLI versão 2.15.0 ou posterior (para configuração baseada em CLI)

  • kubectl configurado para comunicar-se com o cluster de destino

  • Permissões do IAM: eks:CreateAddon, eks:DescribeAddon e iam:CreateServiceLinkedRole

  • O complemento do atendente de Identidade de Pods EKS instalado no cluster ou perfis do IAM para contas de serviço (IRSA) configurados

  • Acesso à Internet de saída do cluster para os endpoints do CloudWatch

Ative o OTel Container Insights (console)

O AWS Management Console fornece o caminho mais rápido para ativar o OTel Container Insights.

Para ativar o OTel Container Insights usando o console

  1. Abra o console do Amazon EKS em https://console.aws.amazon.com/eks/.

  2. Escolha Clusters e, em seguida, escolha o nome do cluster.

  3. Escolha a guia Observabilidade.

  4. Escolha Ativar Container Insights e siga as instruções na tela.

Para obter um passo a passo detalhado do console, consulte Ative o OTel Container Insights a partir do console.

Ative o OTel Container Insights (AWS CLI)

Use as etapas a seguir para ativar o oTel Container Insights usando a AWS CLI.

Etapa 1: Criar o perfil do IAM

Crie um perfil do IAM que permita que o complemento de observabilidade CloudWatch Observability envie dados para o CloudWatch.

Para criar o perfil do IAM do complemento de observabilidade CloudWatch Observability

  1. Execute o seguinte comando para criar a função com uma política de confiança para a Identidade de Pods EKS.

    aws iam create-role \
  --role-name EKS-CloudWatch-Observability-Role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": { "Service": "pods.eks.amazonaws.com" },
      "Action": ["sts:AssumeRole", "sts:TagSession"]
    }]
  }'

  2. Anexe a política gerenciada CloudWatchAgentServerPolicy à função.

    aws iam attach-role-policy \
  --role-name EKS-CloudWatch-Observability-Role \
  --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy

Etapa 2: crie a associação de Identidade de Pods

Associe o perfil do IAM à conta de serviço do atendente do CloudWatch no cluster.

Para criar a associação da Identidade de Pods

  • Execute o comando a seguir. Substitua cluster-name pelo nome do seu cluster do Amazon EKS e account-id pelo ID da sua conta da AWS.

    aws eks create-pod-identity-association \
  --cluster-name cluster-name \
  --namespace amazon-cloudwatch \
  --service-account cloudwatch-agent \
  --role-arn arn:aws:iam::account-id:role/EKS-CloudWatch-Observability-Role

Etapa 3: instale o complemento de observabilidade Amazon CloudWatch Observability

Instale o complemento amazon-cloudwatch-observability com o OTel Container Insights ativado.

Para instalar o complemento

  • Execute o comando a seguir. Substitua cluster-name pelo nome do cluster do Amazon EKS.

    aws eks create-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --configuration-values '{"otelContainerInsights":{"enabled":true}}'
    Importante

    A configuração otelContainerInsights.enabled é obrigatória. O OTel Container Insights não está ativado por padrão.

Etapa 4: verifique o status do complemento

Confirme se o complemento foi instalado com sucesso.

Para verificar o status do complemento

  • Execute o comando a seguir. Substitua cluster-name pelo nome do cluster do Amazon EKS.

    aws eks describe-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --query "addon.status" \
  --output text

    A saída esperada é ACTIVE.

Etapa 5: confirme se os pods do atendente estão em execução

Verifique se os pods do atendente do CloudWatch estão em execução no namespace amazon-cloudwatch.

Para confirmar se os pods do atendente estão em execução

  • Execute o comando a seguir.

    kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent

    Todos os pods de atendentes devem mostrar o status Running.

Verificar os dados no CloudWatch

Depois de concluir a configuração, os dados do Container Insights aparecem no CloudWatch em 3 a 5 minutos.

Verificar as métricas

Para verificar as métricas no CloudWatch

  1. Abra o console do CloudWatch, em https://console.aws.amazon.com/cloudwatch/.

  2. No painel de navegação, escolha Query Studio.

  3. Pesquise métricas com container_cpu_usage_seconds_total usando o PromQL.

Verificar os logs do

Para verificar se há grupos de logs em seu cluster, execute o seguinte comando. Substitua cluster-name pelo nome do cluster do Amazon EKS.

aws logs describe-log-groups \
  --log-group-name-prefix "/aws/containerinsights/cluster-name" \
  --query "logGroups[].logGroupName" \
  --output table

Tempo esperado até a obtenção de dados

A tabela a seguir mostra a latência esperada para cada tipo de sinal após a ativação do OTel Container Insights.

Signal Latência esperada
Métricas de infraestrutura De 2 a 3 minutos
Logs de contêineres De 2 a 3 minutos
Eventos de logs de desempenho 3 a 5 minutos

Solução de problemas

Use as orientações a seguir para resolver problemas comuns ao ativar o OTel Container Insights no Amazon EKS.

O status do complemento mostra CREATE_FAILED ou DEGRADED

Sintoma: quando você executa aws eks describe-addon, o status mostra CREATE_FAILED ou DEGRADED.

Causa: a instalação do complemento falhou, geralmente devido a permissões insuficientes do IAM ou à falta de uma associação da Identidade de Pods.

Solução: para resolver esse problema, siga as seguintes etapas:

  1. Use o comando a seguir para verificar as informações detalhadas do erro. Substitua cluster-name pelo nome do seu cluster.

    aws eks describe-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --query "addon.health"

  2. Verifique se o perfil do IAM existe e tem a CloudWatchAgentServerPolicy anexada.

  3. Verifique se a associação da Identidade de Pods tem como alvo o namespace (amazon-cloudwatch) e a conta de serviço (cloudwatch-agent) corretos.

  4. Exclua o complemento com falha e reinstale-o depois de resolver o problema.

    aws eks delete-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability

Os pods do atendente estão no estado CrashLoopBackOff ou Pending

Sintoma: quando você executa kubectl get pods -n amazon-cloudwatch, um ou mais pods mostram o status CrashLoopBackOff ou Pending.

Causa: os pods do atendente não podem ser iniciados devido à insuficiência de recursos do nó, à falta de permissões ou a problemas de conectividade de rede.

Solução: para resolver esse problema, siga as seguintes etapas:

  1. Verifique os eventos do pod para obter mensagens de erro detalhadas.

    kubectl describe pod -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent

  2. Verifique se há erros de inicialização nos logs do contêiner do atendente.

    kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=50

  3. Verifique se seus nós têm CPU e memória suficientes disponíveis para os pods de atendentes.

  4. Verifique se o complemento do atendente de Identidade de Pods EKS está instalado e em execução.

    kubectl get pods -n kube-system -l app.kubernetes.io/name=eks-pod-identity-agent

As métricas não aparecem no CloudWatch após 5 minutos

Sintoma: os pods do atendente mostram o status Running, mas nenhuma métrica aparece no CloudWatch após 5 minutos.

Causa: o atendentenão consegue enviar dados para o CloudWatch, normalmente devido a restrições de rede ou permissões incorretas do IAM.

Solução: para resolver esse problema, siga as seguintes etapas:

  1. Verifique se os pods do atendente conseguem alcançar os endpoints do CloudWatch. Verifique se os grupos de segurança do VPC e as ACLs de rede permitem o tráfego de saída de HTTPS (porta 443) para endpoints do CloudWatch.

  2. Verifique os logs do atendente em busca de erros de permissão ou tempos limite de conexão.

    kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=100 | grep -i "error\|timeout\|denied"

  3. Verifique se o perfil do IAM tem a política CloudWatchAgentServerPolicy anexada e se a política de confiança permite pods.eks.amazonaws.com.

  4. Se você usa um endpoint da VPC para o CloudWatch, confirme se a política do endpoint permite as ações necessárias.