Instalar o agente do CloudWatch usando o complemento de observabilidade do EKS do Amazon CloudWatch

O complemento Amazon CloudWatch Observability do EKS instala o agente do CloudWatch e o agente do Fluent Bit em um cluster do Amazon EKS, com uma observabilidade aprimorada do Container Insights para o Amazon EKS e com o CloudWatch Application Signals habilitado por padrão. Ao usar o complemento, é possível coletar as métricas de infraestrutura, a telemetria de performance para as aplicações e os logs de contêiner do cluster do Amazon EKS.

Com o Container Insights com capacidade de observabilidade aprimorada para o Amazon EKS, as métricas do Container Insights são cobradas por observação, em vez de serem cobradas por métrica armazenada ou log ingerido. Para o Application Signals, o faturamento é baseado nas solicitações de entrada para as aplicações, nas solicitações de saída das aplicações e em cada objetivo de nível de serviço (SLO) configurado. Cada solicitação de entrada recebida gera um sinal de aplicação e cada solicitação de saída realizada gera um sinal de aplicação. Cada SLO cria dois sinais de aplicações por período de medição. Para obter mais informações sobre os preços do CloudWatch, consulte Preço do Amazon CloudWatch.

O complemento do Amazon EKS possibilita o uso do Container Insights em nós de processamento do Linux e do Windows no cluster do Amazon EKS. Para habilitar o Container Insights no Windows, é necessário usar a versão 1.5.0 ou versões posteriores do complemento do Amazon EKS. No momento, o Application Signals não é compatível com sistema Windows em clusters do Amazon EKS.

O complemento Amazon CloudWatch Observability do EKS é compatível com os clusters do Amazon EKS executados com a versão 1.23 ou com versões posteriores do Kubernetes.

Ao instalar o complemento, também é necessário conceder permissões do IAM para habilitar que o agente do CloudWatch envie métricas, logs e rastreamentos para o CloudWatch. Há duas maneiras de fazer isso:

• Anexe uma política à função do IAM dos nós de processamento. Essa opção concede permissões aos nós de processamento para enviar telemetria ao CloudWatch.

• Use um perfil do IAM para contas de serviço dos pods de agentes e anexe a política a esse perfil. Funciona somente para clusters do Amazon EKS. Essa opção dá ao CloudWatch acesso apenas aos pods de agente adequados.

Opção 1: instalar com permissões do IAM nos nós de processamento

Para usar esse método, primeiro anexe a política do IAM CloudWatchAgentServerPolicy aos nós de processamento, digitando o comando a seguir. Nesse comando, substitua my-worker-node-role pelo perfil do IAM usado por seus nós de processamento do Kubernetes.

aws iam attach-role-policy \
--role-name my-worker-node-role \
--policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy

Em seguida, instale o complemento de observabilidade do EKS do Amazon CloudWatch. Para instalar o complemento, você pode usar a AWS CLI, o console, o AWS CloudFormation ou o Terraform.

AWS CLI

Como usar a AWS CLI para instalar o complemento Amazon CloudWatch Observability do EKS

Insira o comando da a seguir. Substitua o my-cluster-name pelo nome do cluster.

aws eks create-addon --addon-name amazon-cloudwatch-observability --cluster-name my-cluster-name

Amazon EKS console

Como usar o console do Amazon EKS para adicionar o complemento Amazon CloudWatch Observability do EKS

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

2. No painel de navegação à esquerda, escolha Clusters.

3. Escolha o nome do cluster para o qual você deseja configurar o complemento Amazon CloudWatch Observability do EKS.

4. Escolha a guia Add-ons (Complementos).

5. Escolha Obter mais complementos.

6. Na página Selecionar complementos, faça o seguinte:

   1. Na seção Amazon EKS-addons, marque a caixa de seleção Observabilidade do Amazon CloudWatch.

   2. Escolha Próximo.

7. Na página Definir as configurações dos complementos selecionados:

   1. Selecione a Versão que deseja usar.

   2. Em Selecionar perfil do IAM, selecione Herdar do nó

   3. (Opcional) Você pode expandir Definições de configuração opcionais. Se você selecionar Substituir como Método de resolução de conflitos, uma ou mais configurações do complemento existente poderão ser substituídas pelas configurações do complemento do Amazon EKS. Se você não habilitar esta opção e houver um conflito com suas configurações existentes, a operação falhará. É possível usar a mensagem de erro resultante para solucionar o conflito. Antes de selecionar essa opção, certifique-se de que o complemento do Amazon EKS não gerencie as configurações que você precisa autogerenciar.

   4. Escolha Próximo.

8. Na página Adicionar tags, escolha Criar. Depois que a instalação do complemento for concluída, você verá o complemento instalado.

AWS CloudFormation

Como usar o AWS CloudFormation para instalar o complemento Amazon CloudWatch Observability do EKS

Substitua o my-cluster-name pelo nome do cluster. Para obter mais informações, consulte AWS::EKS::Addon.

{
    "Resources": {
        "EKSAddOn": {
            "Type": "AWS::EKS::Addon",
            "Properties": {
                "AddonName": "amazon-cloudwatch-observability",
                "ClusterName": "my-cluster-name"
            }
        }
    }
}

Terraform

Como usar o Terraform para instalar o complemento Amazon CloudWatch Observability do EKS

Substitua o my-cluster-name pelo nome do cluster. Para obter mais informações, consulte Recurso: aws_eks_addon.

resource "aws_eks_addon" "example" {
  addon_name   = "amazon-cloudwatch-observability"
  cluster_name = "my-cluster-name"
}

Opção 2: instalar usando a função de conta de serviço do IAM

Antes de usar esse método, verifique os seguintes pré-requisitos:

• Você possui um cluster funcional do Amazon EKS com nós conectados em uma das Regiões da AWS que são compatíveis com o Container Insights. Para obter a lista de regiões compatíveis, consulte Container Insights.

• Você instalou o kubectl e configurou o cluster. Para obter mais informações, consulte Instalar o kubectl no Manual do usuário do Amazon EKS.

• Você tem o eksctl instalado. Para obter mais informações, consulte Instalação ou atualização do eksctl no Guia do usuário do Amazon EKS.

Instalar o complemento de observabilidade do EKS do Amazon CloudWatch usando o perfil de conta de serviço do IAM

1. Insira o comando seguir para criar um provedor do OpenID Connect (OIDC), se o cluster ainda não tiver um. Para obter mais informações, consulte Configuração de uma conta de serviço do Kubernetes para assumir um perfil do IAM no Guia do usuário do Amazon EKS.

   eksctl utils associate-iam-oidc-provider --cluster my-cluster-name --approve

2. Insira o comando a seguir para criar o perfil do IAM com a política CloudWatchAgentServerPolicy anexada e configure a conta do serviço de agente para assumir esse perfil usando o OIDC. Substitua my-cluster-name pelo nome do seu cluster e substitua my-service-account-role pelo nome do perfil ao qual você deseja associar a conta de serviço. Se o perfil ainda não existir, o eksctl o criará para você.

   eksctl create iamserviceaccount \
     --name cloudwatch-agent \
     --namespace amazon-cloudwatch --cluster my-cluster-name \
     --role-name my-service-account-role \
     --attach-policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
     --role-only \
     --approve

3. Instale o complemento inserindo o comando a seguir. Substitua my-cluster-name pelo nome do seu cluster, substitua 111122223333 pela ID da sua conta e substitua my-service-account-role pelo perfil do IAM criado na etapa anterior.

   aws eks create-addon --addon-name amazon-cloudwatch-observability --cluster-name my-cluster-name --service-account-role-arn arn:aws:iam::111122223333:role/my-service-account-role

(Opcional) Configuração adicional

Opte por não coletar logs de contêineres

Por padrão, o complemento usa o Fluent Bit para coletar logs de contêineres de todos os pods e, em seguida, envia os logs para o CloudWatch Logs. Para obter informações sobre quais logs são coletados, consulte Configurar o Fluent Bit.

Para desativar a coleta de logs de contêineres, passe a seguinte opção ao criar ou atualizar o complemento:

--configuration-values '{ "containerLogs": { "enabled": false } }'

Opte por não participar da coleção de métricas de GPU NVIDIA

A partir da versão 1.300034.0 do agente CloudWatch, o Container Insights coleta métricas de GPU NVIDIA das workloads do EKS por padrão. Essas métricas estão listadas na tabela em Métricas da GPU NVIDIA.

Você pode optar por não coletar métricas de GPU NVIDIA definindo a opção accelerated_compute_metrics no arquivo de configuração do agente CloudWatch como false. Essa opção está na seção kubernetes da seção metrics_collected no arquivo de configuração do CloudWatch. Este é um exemplo de uma configuração de exclusão.

{
  "agent": {
    "region": "us-east-1"
  },
  "logs": {
    "metrics_collected": {
      "emf": {
      },
      "kubernetes": {
        "enhanced_container_insights": true,
        "accelerated_compute_metrics": false
      }
    },
    "force_flush_interval": 5,
  }
}

Como usar uma configuração personalizada do agente do CloudWatch

Para coletar métricas, logs ou rastreamentos adicionais usando o agente do CloudWatch, é possível especificar uma configuração personalizada e, ao mesmo tempo, manter o Container Insights e o CloudWatch Application Signals habilitados. Para fazê-lo, incorpore o arquivo de configuração do agente do CloudWatch na chave de configuração no âmbito da chave do agente da configuração avançada que você pode usar ao criar ou ao atualizar o complemento para o EKS. Veja a seguir uma representação da configuração padrão do agente quando nenhuma configuração adicional é fornecida.

Importante

Qualquer configuração personalizada fornecida usando as definições de configurações adicionais substitui a configuração padrão usada pelo agente. Tenha cuidado para não desabilitar acidentalmente as funcionalidades que são habilitadas por padrão, como o Container Insights com uma observabilidade aprimorada e o CloudWatch Application Signals. Diante do cenário em que é necessário fornecer uma configuração do agente personalizada, recomendamos usar a configuração padrão apresentada a seguir como linha de base e, em seguida, modificá-la com base nas suas necessidades.

--configuration-values '{
  "agent": {
    "config": {
      "logs": {
        "metrics_collected": {
          "app_signals": {},
          "kubernetes": {
            "enhanced_container_insights": true
          }
        }
      },
      "traces": {
        "traces_collected": {
          "app_signals": {}
        }
      }
    }
  
}'

O exemplo apresentado a seguir mostra a configuração padrão do agente do CloudWatch no Windows. O agente do CloudWatch no Windows não oferece suporte à configuração personalizada.

{
  "logs": {
    "metrics_collected": {
      "kubernetes": {
        "enhanced_container_insights": true
      },
    }
  }
}

Gerenciamento de certificados TLS para o webhook de admissão

O complemento Amazon CloudWatch Observability do EKS utiliza webhooks de admissão do Kubernetes para validar e alterar solicitações de recursos personalizados (CR) do AmazonCloudWatchAgent e de Instrumentation e, opcionalmente, solicitações de pod do Kubernetes no cluster, se o CloudWatch Application Signals estiver habilitado. No Kubernetes, os webhooks requerem um certificado TLS no qual o servidor de API esteja configurado para confiar, a fim de garantir uma comunicação segura.

Por padrão, o complemento Amazon CloudWatch Observability do EKS gera automaticamente uma CA autoassinada e um certificado TLS assinado por essa CA para proteger a comunicação entre o servidor de API e o servidor de webhook. O certificado gerado automaticamente tem uma expiração padrão de dez anos e não é renovado de forma automática após expirar. Além disso, o pacote da CA e o certificado são gerados novamente sempre que o complemento é atualizado ou reinstalado, redefinindo, assim, a expiração. Caso deseje alterar a expiração padrão do certificado gerado automaticamente, você poderá usar as configurações adicionais apresentadas a seguir ao criar ou atualizar o complemento. Substitua expiry-in-days pelo período de expiração desejado em dias.

--configuration-values '{ "admissionWebhooks": { "autoGenerateCert": { "expiryDays": expiry-in-days } } }' 

Para obter uma solução mais segura e repleta de recursos da autoridade de certificação, o complemento tem suporte opcional para o cert-manager, uma solução amplamente adotada para o gerenciamento de certificados TLS no Kubernetes que simplifica o processo de obtenção, renovação, gerenciamento e uso desses certificados. A solução garante que os certificados sejam válidos e estejam atualizados, bem como busca renová-los em um momento configurado antes da expiração. Além disso, o cert-manager facilita a emissão de certificados de diversas fontes com suporte, incluindo o AWS Certificate Manager Private Certificate Authority.

Recomendamos analisar as práticas recomendadas para o gerenciamento de certificados TLS em seus clusters e aconselhamos a opção pelo cert-manager para ambientes de produção. Observe que, se você optar por habilitar o cert-manager para gerenciar os certificados TLS para o webhook de admissão, será necessário instalar previamente o cert-manager no cluster do Amazon EKS antes de instalar o complemento Amazon CloudWatch Observability do EKS. Consulte a documentação do cert-manager para saber mais sobre as opções de instalação disponíveis. Após a instalação, é possível optar por usar o cert-manager para o gerenciamento dos certificados TLS para o webhook de admissão usando a configuração adicional apresentada a seguir ao criar ou atualizar o complemento.

--configuration-values '{ "admissionWebhooks": { "certManager": { "enabled": true } } }' 

A configuração avançada debatida nesta seção usará, por padrão, um emissor SelfSigned.

Como coletar IDs de volume do Amazon EBS

Se quiser coletar IDs de volume do Amazon EBS nos logs de performance, será necessário adicionar outra política ao perfil do IAM que está anexado aos nós de processamento ou à conta de serviço. Adicione o seguinte como uma política em linha. Para obter mais informações, consulte Adicionar e remover permissões de identidade do IAM.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "ec2:DescribeVolumes"
            ],
            "Resource": "*",
            "Effect": "Allow"
        }
    ]
}

Solução de problemas do complemento Amazon CloudWatch Observability do EKS

Use as informações apresentadas a seguir para ajudar a solucionar problemas relacionados ao complemento Amazon CloudWatch Observability do EKS.

Atualização e exclusão do complemento Amazon CloudWatch Observability do EKS

Para obter instruções sobre como atualizar ou excluir o complemento Amazon CloudWatch Observability do EKS, consulte Gerenciar complementos do Amazon EKS. Use amazon-cloudwatch-observability como o nome do complemento.

Verificação da versão do agente do CloudWatch usado pelo complemento Amazon CloudWatch Observability do EKS

O complemento Amazon CloudWatch Observability do EKS instala um recurso personalizado do tipo AmazonCloudWatchAgent que controla o comportamento do daemonset do agente do CloudWatch no cluster, incluindo a versão do agente do CloudWatch que está sendo usada. É possível obter uma lista de todos os recursos personalizados do tipo AmazonCloudWatchAgent, que estão instalados em seu cluster, ao inserir o seguinte comando:

kubectl get amazoncloudwatchagent -A

Na saída desse comando, você poderá verificar a versão do agente do CloudWatch. Como alternativa, também é possível descrever o recurso amazoncloudwatchagent ou um dos pods do cloudwatch-agent-* em execução no cluster para inspecionar a imagem que está sendo usada.

Tratamento de um ConfigurationConflict durante o gerenciamento do complemento

Ao instalar ou atualizar o complemento Amazon CloudWatch Observability do EKS, se você perceber uma falha causada por um Health Issue do tipo ConfigurationConflict com uma descrição que começa com Conflicts found when trying to apply. Will not continue due to resolve conflicts mode, é provável que você já tenha o agente do CloudWatch e os componentes associados, como o ServiceAccount, o ClusterRole e o ClusterRoleBinding instalados no cluster. Quando o complemento tentar instalar o agente do CloudWatch e os componentes associados, se ele detectar quaisquer alterações no conteúdo, por padrão, apresentará falhas na instalação ou na atualização para evitar a substituição do estado dos recursos no cluster.

Se você estiver tentando realizar a integração do complemento Amazon CloudWatch Observability do EKS e obter essa falha, recomendamos excluir uma configuração existente do agente do CloudWatch instalada anteriormente no cluster e, em seguida, instalar o complemento do EKS. Certifique-se de fazer backup de quaisquer personalizações que você possa ter executado na configuração original do agente do CloudWatch, como uma configuração do agente personalizada, e fornecê-las ao complemento Amazon CloudWatch Observability do EKS na próxima instalação ou atualização. Se você realizou a instalação do agente do CloudWatch para a integração com o Container Insights, consulte Exclusão do agente do CloudWatch e do Fluent Bit para o Container Insights para obter mais informações.

Como alternativa, o complemento oferece suporte a uma opção de configuração de resolução de conflitos que tem a funcionalidade de especificar OVERWRITE. É possível usar essa opção para prosseguir com a instalação ou a atualização do complemento ao substituir os conflitos no cluster. Se você estiver usando o console do Amazon EKS, encontrará o Método de resolução de conflitos ao escolher as Definições de configuração opcionais na criação ou na atualização do complemento. Caso esteja usando a AWS CLI, você poderá fornecer o comando --resolve-conflicts OVERWRITE para criar ou atualizar o complemento.