# 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 Console de gerenciamento da AWS (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 Console de gerenciamento da AWS 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/](https://console.aws.amazon.com/eks/).
1. Escolha **Clusters** e, em seguida, escolha o nome do cluster.
1. Escolha a guia **Observabilidade**.
1. 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](container-insights-eks-otel-console.md).
## 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"]
}]
}'
```
1. 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/](https://console.aws.amazon.com/cloudwatch/).
1. No painel de navegação, escolha **Query Studio**.
1. 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"
```
1. Verifique se o perfil do IAM existe e tem a `CloudWatchAgentServerPolicy` anexada.
1. 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.
1. 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
```
1. 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
```
1. Verifique se seus nós têm CPU e memória suficientes disponíveis para os pods de atendentes.
1. 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.
1. 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"
```
1. 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`.
1. Se você usa um endpoint da VPC para o CloudWatch, confirme se a política do endpoint permite as ações necessárias.