Implantar o Fluent Bit em contêineres do Windows no Amazon ECS

O Fluent Bit é um processador e roteador de logs rápido e flexível compatível com vários sistemas operacionais. Ele pode ser usado para encaminhar logs a vários destinos da AWS, como o Amazon CloudWatch Logs, Firehose, Amazon S3 e Amazon OpenSearch Service. O Fluent Bit é compatível com soluções comuns de parceiros, como Datadog, Splunk e servidores HTTP personalizados. Para obter mais informações sobre o Fluent Bit, consulte o site do Fluent Bit .

O AWS para Fluent Bit está disponível no Amazon ECR na Galeria Pública do Amazon ECR e em um repositório do Amazon ECR na maioria das regiões para alta disponibilidade. Para obter mais informações, consulte aws-for-fluent-bit no site do GitHub.

Este tutorial explica como implantar contêineres do Fluent Bit em instâncias do Windows em execução no Amazon ECS para transmitir logs gerados pelas tarefas do Windows para o Amazon CloudWatch para logs centralizados.

Este tutorial usa a seguinte abordagem:

• O Fluent Bit é executado como um serviço com a estratégia de programação do Daemon. Essa estratégia garante que uma única instância do Fluent Bit sempre seja executada nas instâncias de contêiner no cluster.

  • Recebe na porta 24224 usando o plug-in de entrada de encaminhamento.

  • Exponha a porta 24224 ao host para que o runtime do docker possa enviar logs para o Fluent Bit usando essa porta exposta.

  • Tem uma configuração que permite que o Fluent Bit envie os registros de logs para destinos especificados.

• Inicie todos os outros contêineres de tarefas do Amazon ECS usando o driver de log fluentd. Para obter mais informações, consulte Fluentd logging driver (Driver de log do Fluentd) no site de documentação do Docker.

  • O Docker se conecta ao soquete TCP 24224 no localhost dentro do namespace do host.

  • O agente do Amazon ECS adiciona rótulos aos contêineres, incluindo o nome do cluster, o nome da família da definição de tarefa, o número da revisão da definição de tarefa, o ARN da tarefa e o nome do contêiner. As mesmas informações são adicionadas ao registro de logs usando a opção labels (rótulos) do driver de logs do docker fluentd. Para obter mais informações, consulte labels, labels-regex, env e env-regex no site de documentação do Docker.

  • Como a opção async do driver de logs fluentd está definida como true, quando o contêiner do Fluent Bit é reiniciado, o docker armazena os logs em buffer até que o contêiner do Fluent Bit seja reiniciado. É possível aumentar o limite de armazenamento em buffer definindo a opção fluentd-buffer-limit. Para obter mais informações, consulte fluentd-buffer-limit no site da documentação do Docker.

O fluxo de trabalho é o seguinte:

• O contêiner do Fluent Bit inicia e recebe na porta 24224, que está exposta ao host.

• O Fluent Bit usa as credenciais do perfil do IAM da tarefa especificadas na definição da tarefa.

• Outras tarefas iniciadas na mesma instância usam o driver de logs do docker do fluentd para se conectar ao contêiner do Fluent Bit na porta 24224.

• Quando os contêineres da aplicação geram logs, o runtime do docker marca esses registros, adiciona metadados especificados nos rótulos e os encaminha pela porta 24224 no namespace do host.

• O Fluent Bit recebe o registro de log na porta 24224 porque ela está exposta ao namespace do host.

• O Fluent Bit executa seu processamento interno e roteia os logs, conforme especificado.

Este tutorial usa a configuração padrão do Fluent Bit do CloudWatch, que faz o seguinte:

• Cria um novo grupo de logs para cada cluster e família de definição de tarefa.

• Cria um novo fluxo de logs para cada contêiner de tarefas no grupo de logs gerado acima sempre que uma nova tarefa é iniciada. Cada fluxo será marcado com o ID da tarefa à qual o contêiner pertence.

• Adiciona metadados, incluindo o nome do cluster, o ARN da tarefa, o nome do contêiner da tarefa, a família de definição de tarefa e o número da revisão da definição de tarefa em cada entrada de log.

  Por exemplo, se você tiver task_1 com container_1 e container_2 e task_2 com container_3, os fluxos de logs do CloudWatch serão os seguintes:

  • /aws/ecs/windows.ecs_task_1

    task-out.TASK_ID.container_1

    task-out.TASK_ID.container_2

  • /aws/ecs/windows.ecs_task_2

    task-out.TASK_ID.container_3

Pré-requisitos

Este tutorial pressupõe que os seguintes pré-requisitos foram concluídos:

• A versão mais recente da AWS CLI está instalada e configurada. Para obter mais informações, consulte Instalar a AWS Command Line Interface.

• A imagem do contêiner aws-for-fluent-bit está disponível para os seguintes sistemas operacionais Windows:

  • Windows Server 2019 Core

  • Windows Server 2019 Full

  • Windows Server 2022 Core

  • Windows Server 2022 Full

• As etapas em Configuração para usar o Amazon ECS foram concluídas.

• Você tem um cluster. Neste tutorial, o nome do cluster é FluentBit-cluster.

• Você tem uma VPC com uma sub-rede pública em que a instância do EC2 será iniciada. É possível usar a VPC padrão. Você também pode usar uma sub-rede privada que permita que os endpoints do Amazon CloudWatch alcancem a sub-rede. Para obter mais informações sobre endpoints do Amazon CloudWatch, consulte Endpoints e cotas do Amazon CloudWatch na Referência geral da AWS. Para obter mais informações sobre como usar o assistente da Amazon VPC para criar uma VPC, consulte Criar uma nuvem privada virtual.

Etapa 1: criar os perfis de acesso do IAM

Crie os perfis do IAM do Amazon ECS.

1. Crie o perfil da instância de contêiner do Amazon ECS de nome "ecsInstanceRole". Para obter mais informações, consulte Perfil do IAM de instância de contêiner do Amazon ECS.

2. Crie um perfil do IAM para a tarefa do Fluent Bit denominada fluentTaskRole. Para ter mais informações, consulte Perfil do IAM para tarefas do Amazon ECS.

   As permissões do IAM concedidas no perfil do IAM são assumidas pelos contêineres das tarefas. Para permitir que o Fluent Bit envie logs para o CloudWatch, é preciso anexar as seguintes permissões ao perfil do IAM da tarefa.

   {
       "Version": "2012-10-17",
       "Statement": [
       {
           "Effect": "Allow",
           "Action": [
               "logs:CreateLogStream",
               "logs:CreateLogGroup",
               "logs:DescribeLogStreams",
               "logs:PutLogEvents"
           ],
           "Resource": "*"
       }
       ]
   }

3. Anexe a política ao perfil.

   1. Salve o conteúdo acima em um arquivo denominado fluent-bit-policy.json.

   2. Execute o comando a seguir para anexar a política em linha ao perfil fluentTaskRole do IAM.

      aws iam put-role-policy --role-name fluentTaskRole --policy-name fluentTaskPolicy --policy-document file://fluent-bit-policy.json

Etapa 2: criar uma instância de contêiner do Windows do Amazon ECS

Crie uma instância de contêiner do Windows do Amazon ECS.

Para criar uma instância do Amazon ECS

1. Use o comando aws ssm get-parameters para recuperar o ID da AMI para a região que hospeda sua VPC. Para obter mais informações, consulte Recuperar os metadados da AMI otimizada para Amazon ECS.

2. Use o console do Amazon EC2 para iniciar a instância.

   1. Abra o console do Amazon EC2 em https://console.aws.amazon.com/ec2/.

   2. Na barra de navegação, selecione a Região a ser usada.

   3. No Painel do EC2, escolha Launch Instance (Iniciar instância).

   4. Em Name (Nome), insira um nome exclusivo.

   5. Em Application and OS Images (Amazon Machine Image) (Imagens de aplicações e SO [Amazon Machine Image]), escolha a AMI que você recuperou na primeira etapa.

   6. Em tipo de instância, escolha t3.xlarge.

   7. Em Key pair (login) (Par de chaves [login]), escolha um par de chaves.

   8. Em Network settings (Configurações de rede), em Security group (Grupo de segurança), selecione um grupo de segurança existente ou crie outro.

   9. Em Network settings (Configurações de rede), em Auto-assign Public IPC (Atribuir IP público automaticamente), selecione Enable (Habilitar).

   10. Em Advanced details (Detalhes avançados), em IAM instance profile (Perfil de instância do IAM), escolha ecsInstanceRole.

   11. Configure a instância de contêiner do Amazon ECS com os dados de usuário a seguir. Em Advanced Details (Detalhes avançados), cole o seguinte script no campo User data (Dados do usuário), substituindo cluster_name pelo nome do cluster.

       <powershell>
       Import-Module ECSTools
       Initialize-ECSAgent -Cluster cluster-name -EnableTaskENI -EnableTaskIAMRole -LoggingDrivers '["awslogs","fluentd"]'
       </powershell>

   12. Quando estiver pronto, selecione o campo de confirmação e, então, escolha Launch Instances.

   13. Uma página de confirmação informa que sua instância está sendo executada. Selecione Visualizar instâncias para fechar a página de confirmação e voltar ao console.

Etapa 3: configurar o Fluent Bit

É possível usar a configuração padrão a seguir fornecida pela AWS para começar rapidamente:

• Amazon CloudWatch, que é baseado no plug-in do Fluent Bit para Amazon CloudWatch no Manual oficial do Fluent Bit.

Como alternativa, é possível usar outras configurações padrão fornecidas pela AWS. Para obter mais informações, consulte Overriding the entrypoint for the Windows image (Substituir o ponto de entrada da imagem do Windows) no site aws-for-fluent-bit do Github.

A configuração padrão do Fluent Bit do Amazon CloudWatch é mostrada abaixo.

Substitua as seguintes variáveis:

• região pela região para a qual você deseja enviar logs do Amazon CloudWatch.

[SERVICE]
    Flush               5
    Log_Level           info
    Daemon              off

[INPUT]
    Name                forward
    Listen              0.0.0.0
    Port                24224
    Buffer_Chunk_Size   1M
    Buffer_Max_Size     6M
    Tag_Prefix          ecs.

# Amazon ECS agent adds the following log keys as labels to the docker container.
# We would use fluentd logging driver to add these to log record while sending it to Fluent Bit.
[FILTER]
    Name                modify
    Match               ecs.*
    Rename              com.amazonaws.ecs.cluster ecs_cluster
    Rename              com.amazonaws.ecs.container-name ecs_container_name
    Rename              com.amazonaws.ecs.task-arn ecs_task_arn
    Rename              com.amazonaws.ecs.task-definition-family ecs_task_definition_family
    Rename              com.amazonaws.ecs.task-definition-version ecs_task_definition_version

[FILTER]
    Name                rewrite_tag
    Match               ecs.*
    Rule                $ecs_task_arn ^([a-z-:0-9]+)/([a-zA-Z0-9-_]+)/([a-z0-9]+)$  out.$3.$ecs_container_name false
    Emitter_Name        re_emitted

[OUTPUT]
    Name                cloudwatch_logs
    Match               out.*
    region              region
    log_group_name      fallback-group
    log_group_template  /aws/ecs/$ecs_cluster.$ecs_task_definition_family
    log_stream_prefix   task-
    auto_create_group   On

Cada log que entra no Fluent Bit tem uma tag que você especifica ou é gerada automaticamente quando você não fornece uma. As tags podem ser usadas para rotear diferentes logs para destinos diferentes. Para obter informações adicionais, consulte Tag no Manual oficial do Fluent Bit.

A configuração do Fluent Bit descrita acima tem as seguintes propriedades:

• O plug-in de entrada de encaminhamento recebe o tráfego de entrada na porta TCP 24224.

• Cada entrada de log recebida nessa porta tem uma tag que o plug-in de entrada de encaminhamento modifica para prefixar o registro com a string ecs..

• O pipeline interno do Fluent Bit roteia a entrada de log para modificar o filtro usando o regex Match (Corresponder). Esse filtro substitui as chaves no registro de log JSON pelo formato que o Fluent Bit pode consumir.

• A entrada de log modificada é consumida pelo filtro rewrite_tag. Esse filtro altera a tag do registro de log para o formato out.TASK_ID.CONTAINER_NAME.

• A nova tag será roteada para o plug-in cloudwatch_logs de saída, que cria os grupos e fluxos de logs, conforme descrito anteriormente, usando as opções log_group_template e log_stream_prefix do plug-in de saída do CloudWatch. Para obter informações adicionais, consulte Configuration parameters (Parâmetros de configuração) no Manual oficial do Fluent Bit.

Etapa 4: registrar uma definição de tarefa do Fluent Bit no Windows que roteia os logs para o CloudWatch

Registre uma definição de tarefa do Fluent Bit no Windows que roteia os logs para o CloudWatch.

nota

Essa definição de tarefa expõe a porta 24224 do contêiner do Fluent Bit para a porta 24224 do host. Verifique se essa porta não está aberta em seu grupo de segurança de instâncias do EC2 para impedir o acesso externo.

Para registrar uma definição de tarefa

1. Crie um arquivo denominado fluent-bit.json com o seguinte conteúdo:

   Substitua as seguintes variáveis:

   • task-iam-role pelo nome do recurso da Amazon (ARN) do perfil do IAM da tarefa

   • region (região) pela região em que a tarefa é executada

   {
     "family": "ecs-windows-fluent-bit",
     "taskRoleArn": "task-iam-role",
     "containerDefinitions": [
       {
         "name": "fluent-bit",
         "image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:windowsservercore-latest",
         "cpu": 512,
         "portMappings": [
           {
             "hostPort": 24224,
             "containerPort": 24224,
             "protocol": "tcp"
           }
         ],
         "entryPoint": [
           "Powershell",
           "-Command"
         ],
         "command": [
           "C:\\entrypoint.ps1 -ConfigFile C:\\ecs_windows_forward_daemon\\cloudwatch.conf"
         ],
         "environment": [
           {
             "name": "AWS_REGION",
             "value": "region"
           }
         ],
         "memory": 512,
         "essential": true,
         "logConfiguration": {
           "logDriver": "awslogs",
           "options": {
             "awslogs-group": "/ecs/fluent-bit-logs",
             "awslogs-region": "region",
             "awslogs-stream-prefix": "flb",
             "awslogs-create-group": "true"
           }
         }
       }
     ],
     "memory": "512",
     "cpu": "512"
   }

2. Use o comando a seguir para registrar a definição de tarefa.

   aws ecs register-task-definition --cli-input-json file://fluent-bit.json --region region

   É possível listar as definições de tarefa para a conta executando o comando list-task-definitions. A saída exibe os valores da família e da revisão que você pode usar com run-task ou start-task.

Etapa 5: executar a definição de tarefa ecs-windows-fluent-bit como um serviço do Amazon ECS usando a estratégia de programação do daemon

Depois de registrar uma definição de tarefa para sua conta, será possível executar uma tarefa no cluster. Para este tutorial, você executa uma única instância da definição de tarefa ecs-windows-fluent-bit:1 no cluster FluentBit-cluster. Execute a tarefa em um serviço que use a estratégia de programação do daemon, o que garante que uma única instância do Fluent Bit sempre seja executada em cada instância de contêiner.

Para executar uma tarefa

1. Execute o comando a seguir para iniciar a definição de tarefa ecs-windows-fluent-bit:1(registrada na etapa anterior) como um serviço.

   nota

   Essa definição de tarefa usa o driver de log awslogs. Sua instância de contêiner precisa ter as permissões necessárias.

   Substitua as seguintes variáveis:

   • region (região) pela região em que o serviço é executado

   aws ecs create-service \
       --cluster FluentBit-cluster \
       --service-name FluentBitForwardDaemonService \
       --task-definition ecs-windows-fluent-bit:1 \
       --launch-type EC2 \
       --scheduling-strategy DAEMON \
       --region region

2. Execute o comando a seguir para listar as tarefas.

   Substitua as seguintes variáveis:

   • region (região) pela região em que as tarefas de serviço são executadas

   aws ecs list-tasks --cluster FluentBit-cluster --region region

Etapa 6: registrar uma definição de tarefa do Windows que gere os logs

Registre uma definição de tarefa do Windows que gere os logs. Essa definição de tarefa implanta uma imagem de contêiner do Windows que gravará um número incremental no stdout a cada segundo.

A definição de tarefa usa o driver de log fluentd que se conecta à porta 24224 que o plug-in do Fluent Bit recebe. O agente do Amazon ECS rotula cada contêiner do Amazon ECS com tags, incluindo o nome do cluster, o ARN da tarefa, o nome da família da definição de tarefa, o número da revisão da definição de tarefa e o nome do contêiner da tarefa. Esses rótulos de valores-chave são passados para o Fluent Bit.

nota

Essa tarefa usa o modo de rede default. Entretanto, também é possível usar o modo de rede awsvpc com a tarefa.

Para registrar uma definição de tarefa

1. Crie um arquivo denominado windows-app-task.json com o seguinte conteúdo:

   {
     "family": "windows-app-task",
     "containerDefinitions": [
       {
         "name": "sample-container",
         "image": "mcr.microsoft.com/windows/servercore:ltsc2019",
         "cpu": 512,
         "memory": 512,
         "essential": true,
         "entryPoint": [
           "Powershell",
           "-Command"
         ],
         "command": [
           "$count=1;while(1) { Write-Host $count; sleep 1; $count=$count+1;}"
         ],
         "logConfiguration": {
           "logDriver": "fluentd",
           "options": {
             "fluentd-address": "localhost:24224",
             "tag": "{{ index .ContainerLabels \"com.amazonaws.ecs.task-definition-family\" }}",
             "fluentd-async": "true",
             "labels": "com.amazonaws.ecs.cluster,com.amazonaws.ecs.container-name,com.amazonaws.ecs.task-arn,com.amazonaws.ecs.task-definition-family,com.amazonaws.ecs.task-definition-version"
           }
         }
       }
     ],
     "memory": "512",
     "cpu": "512"
   }

2. Use o comando a seguir para registrar a definição de tarefa.

   Substitua as seguintes variáveis:

   • region (região) pela região em que a tarefa é executada

   aws ecs register-task-definition --cli-input-json file://windows-app-task.json --region region

   É possível listar as definições de tarefa para a conta executando o comando list-task-definitions. A saída exibe os valores da família e da revisão que você pode usar com run-task ou start-task.

Etapa 7: executar a definição de tarefa windows-app-task

Depois de registrar a definição de tarefa windows-app-task, execute-a no cluster FluentBit-cluster.

Para executar uma tarefa

1. Execute a definição de tarefa windows-app-task:1 que você registrou na etapa anterior.

   Substitua as seguintes variáveis:

   • region (região) pela região em que a tarefa é executada

   aws ecs run-task --cluster FluentBit-cluster --task-definition windows-app-task:1 --count 2 --region region

2. Execute o comando a seguir para listar as tarefas.

   aws ecs list-tasks --cluster FluentBit-cluster

Etapa 8: verificar os logs no CloudWatch

Para verificar a configuração do Fluent Bit, verifique os seguintes grupos de log no console do CloudWatch:

• /ecs/fluent-bit-logs: este é o grupo de logs que corresponde ao contêiner do daemon do Fluent Bit que está sendo executado na instância de contêiner.

• /aws/ecs/FluentBit-cluster.windows-app-task: este é o grupo de logs que corresponde a todas as tarefas iniciadas para a família de definição de tarefa windows-app-task dentro do cluster FluentBit-cluster.

  task-out.FIRST_TASK_ID.sample-container: este fluxo de logs contém todos os logs gerados pela primeira instância da tarefa no contêiner de tarefas do contêiner de amostra.

  task-out.SECOND_TASK_ID.sample-container: este fluxo de logs contém todos os logs gerados pela segunda instância da tarefa no contêiner de tarefas do contêiner de amostra.

O fluxo de logs task-out.TASK_ID.sample-container tem campos semelhantes aos seguintes:

{
    "source": "stdout",
    "ecs_task_arn": "arn:aws:ecs:region:0123456789012:task/FluentBit-cluster/13EXAMPLE",
    "container_name": "/ecs-windows-app-task-1-sample-container-cEXAMPLE",
    "ecs_cluster": "FluentBit-cluster",
    "ecs_container_name": "sample-container",
    "ecs_task_definition_version": "1",
    "container_id": "61f5e6EXAMPLE",
    "log": "10",
    "ecs_task_definition_family": "windows-app-task"
}

Para verificar a configuração do Fluent Bit

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

2. No painel de navegação, escolha Grupos de logs. Certifique-se de que você esteja na região em que implantou o Fluent Bit para seus contêineres.

   Na lista de grupos de log na Região da AWS, você deve ver o seguinte:

   • /ecs/fluent-bit-logs

   • /aws/ecs/FluentBit-cluster.windows-app-task

   Caso você veja esses grupos de logs, a configuração do Fluent Bit estará verificada.

Etapa 9: limpar

Ao concluir este tutorial, limpe os recursos associados a ele para evitar cobranças por recursos que você não está usando.

Para limpar os recursos do tutorial

1. Interrompa as tarefas windows-simple-task e ecs-fluent-bit. Para ter mais informações, consulte Interrupção de uma tarefa do Amazon ECS.

2. Execute o comando a seguir para excluir o grupo de logs /ecs/fluent-bit-logs. Para obter mais informações sobre a exclusão de grupos de logs, consulte delete-log-group na Referência do AWS Command Line Interface.

   aws logs delete-log-group --log-group-name /ecs/fluent-bit-logs
   aws logs delete-log-group --log-group-name /aws/ecs/FluentBit-cluster.windows-app-task

3. Execute o comando a seguir para encerrar a instância.

   aws ec2 terminate-instances --instance-ids instance-id

4. Execute o comando a seguir para excluir os perfis do IAM.

   aws iam delete-role --role-name ecsInstanceRole
   aws iam delete-role --role-name fluentTaskRole

5. Execute o comando a seguir para excluir o cluster do Amazon ECS.

   aws ecs delete-cluster --cluster FluentBit-cluster