View a markdown version of this page

Configuração avançada para OTel Container Insights no Amazon EKS - Amazon CloudWatch
Pré-requisitosPadrão de configuração geralFiltro de logColeta de várias contasDimensões de métrica personalizadaAjuste de recursos para clusters grandesVerificar as alterações de configuraçãoSolução de problemas

Configuração avançada para OTel Container Insights no Amazon EKS

Este tópico aborda cenários avançados de configuração do OTel Container Insights no Amazon EKS. Use essas configurações para personalizar a coleta de métricas, filtrar logs, coletar telemetria entre contas, adicionar dimensões personalizadas e ajustar a alocação de recursos para grandes clusters.

Pré-requisitos

Antes de definir as configurações avançadas, verifique se os requisitos a seguir estão sendo atendidos.

  • OTel Container Insights instalado e em status ACTIVE no cluster do Amazon EKS

  • Cluster do Amazon EKS executando a versão 1.28 ou versões posteriores do Kubernetes

  • AWS CLI versão 2.15.0 ou posterior

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

  • Permissões do IAM: eks:UpdateAddon, eks:DescribeAddon e iam:AttachRolePolicy (necessárias para configuração entre contas)

Padrão de configuração geral

Todas as configurações avançadas seguem o mesmo padrão. Você passa uma configuração JSON para o complemento amazon-cloudwatch-observability usando o comando aws eks update-addon.

aws eks update-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --configuration-values 'JSON-configuration' \
  --resolve-conflicts OVERWRITE
Importante

O sinalizador --resolve-conflicts OVERWRITE substitui qualquer configuração de complemento existente. Para preservar as configurações existentes, mescle-as com sua nova configuração antes de executar o comando.

Filtro de log

Você pode reduzir os custos do CloudWatch Logs excluindo logs que correspondam a critérios específicos. Use a filtragem de logs para eliminar logs detalhados ou de nível de depuração antes que o atendente os envie para o CloudWatch.

Para configurar a filtragem de logs

  1. Execute o comando a seguir para atualizar o complemento com uma configuração de filtro de log. Substitua cluster-name pelo nome do cluster do Amazon EKS.

    aws eks update-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --configuration-values '{
    "otelContainerInsights": {
      "enabled": true
    },
    "agent": {
      "config": {
        "logs": {
          "metrics_collected": {
            "kubernetes": {
              "enhanced_container_insights": true
            }
          },
          "exclude_filters": [
            {
              "type": "log_level_filter",
              "log_level": "DEBUG"
            }
          ]
        }
      }
    }
  }' \
  --resolve-conflicts OVERWRITE

  2. Verifique se o status do complemento é ACTIVE após a atualização.

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

A configuração exclude_filters remove as entradas de log que correspondem ao nível de log especificado antes que o atendente as envie para o CloudWatch Logs. Isso reduz o volume de ingestão de logs e os custos associados.

Coleta de várias contas

Você pode enviar a telemetria das contas de workload para uma conta de monitoramento central configurando a suposição do perfil do IAM entre contas. Essa abordagem oferece uma visão única das métricas e dos logs de vários clusters do Amazon EKS em diferentes contas da AWS.

Para configurar a coleta de várias contas

Para criar a função entre contas na conta de monitoramento

  1. Na conta de monitoramento central, crie um perfil do IAM com uma política de confiança que permita que a conta de workload a assuma. Substitua workload-account-id pelo ID da conta da AWS de workload.

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::workload-account-id:root"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

  2. Vincule a política gerenciada CloudWatchAgentServerPolicy ao perfil entre contas.

Para configurar o complemento para entrega entre contas

  1. Na conta de workload, atualize o complemento para assumir o perfil entre contas. Substitua cluster-name pelo nome do seu cluster do Amazon EKS e monitoring-account-id pelo ID da conta da AWS da conta central de monitoramento.

    aws eks update-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --configuration-values '{
    "otelContainerInsights": {
      "enabled": true
    },
    "agent": {
      "config": {
        "credentials": {
          "role_arn": "arn:aws:iam::monitoring-account-id:role/CrossAccountCWObservabilityRole"
        }
      }
    }
  }' \
  --resolve-conflicts OVERWRITE

  2. Verifique se o status do complemento é ACTIVE após a atualização.

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

Dimensões de métrica personalizada

Você pode adicionar dimensões personalizadas derivadas dos rótulos do Kubernetes às suas métricas do Container Insights. As dimensões personalizadas permitem filtrar e agrupar métricas em uma granularidade mais precisa, como por equipe, ambiente ou nível de aplicação.

Para adicionar dimensões personalizadas a partir de rótulos do Kubernetes

  1. Execute o comando a seguir para configurar as dimensões personalizadas. Substitua cluster-name pelo nome do seu cluster do Amazon EKS e label-key pelo rótulo Kubernetes para usar como dimensão.

    aws eks update-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --configuration-values '{
    "otelContainerInsights": {
      "enabled": true
    },
    "agent": {
      "config": {
        "logs": {
          "metrics_collected": {
            "kubernetes": {
              "enhanced_container_insights": true,
              "metric_dimensions": {
                "custom_dimensions": ["label-key"]
              }
            }
          }
        }
      }
    }
  }' \
  --resolve-conflicts OVERWRITE

  2. Verifique se o status do complemento é ACTIVE após a atualização.

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

Depois que a configuração entrar em vigor, os rótulos especificados do Kubernetes aparecerão como dimensões nas métricas do Container Insights no CloudWatch.

Ajuste de recursos para clusters grandes

Para clusters grandes, talvez seja necessário aumentar os limites de CPU e memória para o DaemonSet do atendente do CloudWatch. A alocação padrão de recursos funciona bem para clusters pequenos, mas clusters maiores geram mais dados de telemetria e exigem recursos adicionais do atendente.

A tabela a seguir fornece diretrizes de dimensionamento com base no tamanho do cluster.

Tamanho do cluster Solicitação de CPU Limite da CPU Solicitação de memória Limite de memória
Pequeno (20 nós ou menos) 100 m 200 m 128 milhões 256 milhões
Médio (21 a 100 nós) 200 m 400 m 256 milhões 512 milhões
Grande (mais de 100 nós) 300 m 500 m 384 milhões 768 milhões
Extra grande (mais de 500 nós) 500 m 1000 m 512 milhões 1 Gi
Para configurar limites de recursos para o atendente do DaemonSet

  1. Execute o comando a seguir para definir os limites e as solicitações de recursos. Substitua cluster-name pelo nome do seu cluster do Amazon EKS e os valores dos recursos pelos valores da tabela anterior.

    aws eks update-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --configuration-values '{
    "otelContainerInsights": {
      "enabled": true
    },
    "agent": {
      "resources": {
        "requests": {
          "cpu": "cpu-request",
          "memory": "memory-request"
        },
        "limits": {
          "cpu": "cpu-limit",
          "memory": "memory-limit"
        }
      }
    }
  }' \
  --resolve-conflicts OVERWRITE

  2. Verifique se o status do complemento é ACTIVE e se os pods do atendente são reiniciados com a nova alocação de recursos.

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

  3. Confirme se os pods do atendente estão em execução com os novos limites de recursos.

    kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent -o jsonpath='{.items[0].spec.containers[0].resources}'

Verificar as alterações de configuração

Depois de aplicar qualquer configuração avançada, verifique se o complemento está íntegro e se os pods do atendente foram reiniciados com êxito.

Para verificar as alterações de configuração

  1. Verifique se o status do complemento é ACTIVE. 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:status,ConfigValues:configurationValues}" \
  --output table

  2. Verifique se os pods do atendente foram reiniciados e se estão no status Running.

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

    Todos os pods de atendentes devem mostrar o status Running com um horário de reinicialização recente.

Solução de problemas

Use as orientações a seguir para resolver problemas comuns com configurações avançadas.

A atualização do complemento falha com ConfigurationConflict

Sintoma: o comando aws eks update-addon retorna um erro ConfigurationConflict.

Causa: a configuração JSON fornecida por você está malformada ou contém chaves inválidas.

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

  1. Valide sua configuração JSON usando um linter JSON ou executando o comando a seguir.

    echo 'your-json-configuration' | python3 -m json.tool

  2. Verifique se todas as chaves de configuração são válidas para o complemento amazon-cloudwatch-observability.

  3. Tente atualizar novamente com o JSON corrigido.

As métricas entre contas não aparecem na conta de monitoramento

Sintoma: depois que você configurou a coleta de várias contas, as métricas não aparecem na conta de monitoramento central.

Causa: a política de confiança ou as permissões do perfil do IAM entre contas estão incorretas.

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

  1. Verifique se a política de confiança na conta de monitoramento permite que a conta de workload assuma o perfil.

  2. Verifique se o perfil entre contas tem a política CloudWatchAgentServerPolicy gerenciada anexada.

  3. Verifique se há erros AssumeRole nos logs do atendente.

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

  4. Verifique se o perfil do IAM do atendente na conta de workload tem permissão sts:AssumeRole para o ARN do perfil entre contas.