예시 Amazon ECS 태스크 정의: 로그를 FireLens로 라우팅

FireLens를 사용한 사용자 지정 로그 라우팅을 사용하려면 태스크 정의에 몇 가지를 지정해야 합니다. 이 글에서는 FireLens 로그 라우터 컨테이너를 구성하는 예시를 알아봅니다.

출처: 문서

본문

FireLens를 사용한 사용자 지정 로그 라우팅을 사용하려면 태스크 정의에 다음을 지정해야 합니다:

FireLens 구성이 포함된 로그 라우터(log router) 컨테이너. 컨테이너를 essential로 표시할 것을 권장합니다.
awsfirelens 로그 드라이버를 지정하는 로그 구성을 포함한 하나 이상의 애플리케이션 컨테이너.
태스크가 로그를 라우팅하는 데 필요한 권한이 포함된 태스크 IAM 역할 Amazon 리소스 이름(ARN).

AWS Management Console을 사용해 새 태스크 정의를 만들 때 FireLens 통합 섹션이 있어 로그 라우터 컨테이너를 쉽게 추가할 수 있어요. 자세한 내용은 콘솔을 사용한 Amazon ECS 태스크 정의 생성 문서를 참고하세요.

Amazon ECS는 로그 구성을 변환하고 Fluentd 또는 Fluent Bit 출력 구성을 생성합니다. 출력 구성은 Fluent Bit의 경우 /fluent-bit/etc/fluent-bit.conf, Fluentd의 경우 /fluentd/etc/fluent.conf 경로에 로그 라우팅 컨테이너에 마운트됩니다.

중요: FireLens는 포트 24224에서 수신합니다. 따라서 FireLens 로그 라우터가 태스크 외부에서 접근 가능하지 않도록 태스크가 사용하는 보안 그룹에서 포트 24224의 인그레스(ingress) 트래픽을 허용하지 말아야 합니다. awsvpc 네트워크 모드를 사용하는 태스크의 경우 이는 태스크와 연결된 보안 그룹입니다. host 네트워크 모드를 사용하는 태스크의 경우 이는 태스크를 호스팅하는 Amazon EC2 인스턴스와 연결된 보안 그룹입니다. bridge 네트워크 모드를 사용하는 태스크의 경우 포트 24224를 사용하는 포트 매핑을 만들지 마세요.

기본적으로 Amazon ECS는 로그 항목에 로그의 출처를 식별하는 데 도움이 되는 추가 필드를 추가합니다:

ecs_cluster — 태스크가 속한 클러스터의 이름
ecs_task_arn — 컨테이너가 속한 태스크의 전체 Amazon 리소스 이름(ARN)
ecs_task_definition — 태스크가 사용하는 태스크 정의 이름과 개정
ec2_instance_id — 컨테이너가 호스팅되는 Amazon EC2 인스턴스 ID. 이 필드는 EC2 시작 유형을 사용하는 태스크에만 유효합니다.

메타데이터가 필요 없다면 enable-ecs-log-metadata를 false로 설정할 수 있어요.

다음 태스크 정의 예시는 Fluent Bit를 사용해 로그를 CloudWatch Logs로 라우팅하는 로그 라우터 컨테이너를 정의합니다. 또한 로그 구성을 사용해 로그를 Amazon Data Firehose로 라우팅하고, 이벤트를 버퍼링하는 데 사용되는 메모리를 2 MiB로 설정하는 애플리케이션 컨테이너를 정의합니다.

참고: 더 많은 예시 태스크 정의는 GitHub의 Amazon ECS FireLens 예시를 참고하세요.

{
  "family": "firelens-example-firehose",
  "taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role",
  "containerDefinitions": [
    {
            "name": "log_router",
            "image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:3",
            "cpu": 0,
            "memoryReservation": 51,
            "portMappings": [],
            "essential": true,
            "environment": [],
            "mountPoints": [],
            "volumesFrom": [],
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": {
                    "awslogs-group": "/ecs/ecs-aws-firelens-sidecar-container",
                    "mode": "non-blocking",
                    "awslogs-create-group": "true",
                    "max-buffer-size": "25m",
                    "awslogs-region": "us-east-1",
                    "awslogs-stream-prefix": "firelens"
                },
                "secretOptions": []
            },
            "systemControls": [],
            "firelensConfiguration": {
                "type": "fluentbit"
            }
        },
    {
      "essential": true,
      "image": "public.ecr.aws/docker/library/httpd:latest",
      "name": "app",
      "logConfiguration": {
        "logDriver": "awsfirelens",
        "options": {
          "Name": "firehose",
          "region": "us-west-2",
          "delivery_stream": "my-stream",
          "log-driver-buffer-limit": "1048576"
        }
      },
      "memoryReservation": 100
    }
  ]
}

logConfiguration 객체의 options로 지정된 키-값 쌍은 Fluentd 또는 Fluent Bit 출력 구성을 생성하는 데 사용됩니다. 다음은 Fluent Bit 출력 정의의 코드 예시입니다:

[OUTPUT]
    Name   firehose
    Match  app-firelens*
    region us-west-2
    delivery_stream my-stream

참고: FireLens가 match 구성을 관리합니다. 태스크 정의에서는 match 구성을 지정하지 마세요.

사용자 지정 구성 파일 사용 (Use a custom configuration file)

사용자 지정 구성 파일을 지정할 수 있습니다. 구성 파일 형식은 사용 중인 로그 라우터의 네이티브 형식입니다. 자세한 내용은 Fluentd Config File Syntax와 YAML Configuration 문서를 참고하세요.

사용자 지정 구성 파일에서 bridge 또는 awsvpc 네트워크 모드를 사용하는 태스크의 경우 FireLens가 입력 구성을 추가하므로 TCP를 통한 Fluentd 또는 Fluent Bit forward 입력을 설정하지 마세요.

FireLens 구성은 사용자 지정 구성 파일을 지정하기 위해 다음 옵션을 포함해야 합니다:

config-file-type — 사용자 지정 구성 파일의 소스 위치입니다. 사용 가능한 옵션은 s3 또는 file입니다.
- 참고: AWS Fargate에서 호스팅되는 태스크는 file 구성 파일 형식만 지원합니다. 그러나 AWS for Fluent Bit init 컨테이너를 사용하여 AWS Fargate에서 Amazon S3에 호스팅된 구성 파일을 사용할 수 있어요. 자세한 내용은 GitHub의 ECS에서 Fluent Bit용 Init 프로세스, 다중 구성 지원 문서를 참고하세요.
config-file-value — 사용자 지정 구성 파일의 소스입니다. s3 구성 파일 형식을 사용한다면 구성 파일 값은 Amazon S3 버킷과 파일의 전체 ARN입니다. file 구성 파일 형식을 사용한다면 구성 파일 값은 컨테이너 이미지에 있거나 컨테이너에 마운트된 볼륨에 존재하는 구성 파일의 전체 경로입니다.
- 중요: 사용자 지정 구성 파일을 사용할 때 FireLens가 사용하는 경로와 다른 경로를 지정해야 합니다. Amazon ECS는 Fluent Bit용으로 /fluent-bit/etc/fluent-bit.conf, Fluentd용으로 /fluentd/etc/fluent.conf 파일 경로를 예약합니다.

다음 예시는 사용자 지정 구성을 지정할 때 필요한 구문을 보여줍니다.

중요: Amazon S3에 호스팅된 사용자 지정 구성 파일을 지정하려면 적절한 권한이 있는 태스크 실행 IAM 역할을 만들었는지 확인하세요.

다음은 사용자 지정 구성을 지정할 때 필요한 구문입니다.

{
  "containerDefinitions": [
    {
      "essential": true,
      "image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:3",
      "name": "log_router",
      "firelensConfiguration": {
        "type": "fluentbit",
        "options": {
          "config-file-type": "s3 | file",
          "config-file-value": "arn:aws:s3:::amzn-s3-demo-bucket/fluent.conf | filepath"
        }
      }
    }
  ]
}

참고: AWS Fargate에서 호스팅되는 태스크는 file 구성 파일 형식만 지원합니다. 그러나 AWS for Fluent Bit init 컨테이너를 사용하여 AWS Fargate에서 Amazon S3에 호스팅된 구성 파일을 사용할 수 있어요. 자세한 내용은 GitHub의 ECS에서 Fluent Bit용 Init 프로세스, 다중 구성 지원 문서를 참고하세요.

더 알아보기 (Learn more)

FireLens 구성에 대한 자세한 내용은 AWS 개발자 가이드의 관련 문서를 참고하세요.