사용자 지정 로그 라우팅 - Amazon Elastic Container Service

사용자 지정 로그 라우팅

Amazon ECS용 FireLens를 사용하면 작업 정의 파라미터를 사용하여 로그를 AWS 서비스 또는 AWS 파트너 네트워크(APN) 대상으로 라우팅하여 로그를 저장 및 분석할 수 있습니다. FireLens는 FluentdFluent Bit와 함께 작동합니다. AWS는 Fluent Bit 이미지에 AWS를 제공합니다. 또는 자체 Fluentd 또는 Fluent Bit 이미지를 사용할 수 있습니다.

FireLens 구성을 사용한 Amazon ECS 작업 정의 생성은 AWS SDK, AWS CLI 및 AWS Management 콘솔을 통해 지원됩니다.

고려 사항

Amazon ECS용 FireLens를 사용할 때는 다음 사항을 고려해야 합니다.

  • Amazon ECS용 FireLens는 Fargate 및 EC2 시작 유형을 모두 사용하는 작업에서 지원됩니다.

  • Amazon ECS용 FireLens는 AWS CloudFormation 템플릿에서 지원됩니다. 자세한 내용은 AWS CloudFormation 사용 설명서AWS::ECS::TaskDefinition FirelensConfiguration을 참조하십시오.

  • bridge 네트워크 모드를 사용하는 작업의 경우 FireLens 구성이 포함된 컨테이너는 해당 컨테이너를 사용하는 모든 애플리케이션 컨테이너가 시작되기 전에 시작해야 합니다. 컨테이너의 시작 순서를 제어하려면 작업 정의에서 종속성 조건을 사용하십시오. 자세한 내용은 컨테이너 종속성 단원을 참조하십시오.

    참고

    FireLens 구성과 함께 컨테이너 정의에서 종속성 조건 파라미터를 사용하는 경우 각 컨테이너에 START 또는 HEALTHY 조건 요구 사항이 있는지 확인하십시오.

필요한 IAM 권한

이 기능을 사용하려면 작업에 필요한 AWS 서비스 사용에 필수적인 권한을 제공하는 작업에 IAM 역할을 생성해야 합니다. 예를 들어 컨테이너가 로그를 Kinesis Data Firehose로 라우팅하는 경우 작업에 firehose:PutRecordBatch API를 호출 할 수 있는 권한이 필요합니다. 자세한 내용은 IAM 사용 설명서IAM 자격 증명 권한 추가 및 제거를 참조하십시오.

다음 IAM 정책 예시에서는 로그를 Kinesis Data Firehose로 라우팅하는 데 필요한 권한을 추가합니다.

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

다음 조건에서는 작업 수행 시 Amazon ECS 작업 실행 역할이 필요할 수도 있습니다. 자세한 내용은 Amazon ECS 작업 실행 IAM 역할 단원을 참조하십시오.

  • 작업에서 Fargate 시작 유형을 사용하고 Amazon ECR에서 컨테이너 이미지를 가져오거나 로그 구성의 AWS Secrets Manager에서 중요 데이터를 참조하는 경우, 작업 실행 IAM 역할을 포함하고 있어야 합니다.

  • Amazon S3에서 호스팅되는 사용자 지정 구성 파일을 지정하는 경우 작업 실행 IAM 역할에 구성 파일에 대한 s3:GetObject 권한과 파일이 있는 Amazon S3 버킷에 대한 s3:GetBucketLocation 권한이 포함되어야 합니다. 자세한 내용은 Amazon Simple Storage Service 콘솔 사용 설명서정책에서 권한 지정을 참조하십시오.

    다음 IAM 정책 예시에서는 Amazon S3에서 파일을 검색하는 데 필요한 권한을 추가합니다. Amazon S3 버킷의 이름과 구성 파일 이름을 지정합니다.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::examplebucket/folder_name/config_file_name" ] }, { "Effect": "Allow", "Action": [ "s3:GetBucketLocation" ], "Resource": [ "arn:aws:s3:::examplebucket" ] } ] }

Fluent Bit 이미지에 AWS 사용

AWS는 CloudWatch Logs 및 Kinesis Data Firehose 모두에 대한 플러그인과 함께 Fluent Bit 이미지를 제공합니다. Fluent Bit가 Fluentd보다 리소스 사용률이 낮으므로 Fluent Bit를 로그 라우터로 사용하는 것이 좋습니다. 자세한 내용은 Fluent Bit용 CloudWatch LogsFluent Bit용 Amazon Kinesis Firehose를 참조하십시오.

AWS for Fluent Bit(Fluent Bit용 AWS) 이미지는 Docker Hub에서 얻을 수 있습니다. 그러나 다음 이미지는 더 높은 가용성을 제공하므로 Amazon ECR에서 사용하는 것이 좋습니다.

리전 이름 리전 이미지 URI

미국 동부(버지니아 북부)

us-east-1

906394416424.dkr.ecr.us-east-1.amazonaws.com/aws-for-fluent-bit:latest

미국 동부(오하이오)

us-east-2

906394416424.dkr.ecr.us-east-2.amazonaws.com/aws-for-fluent-bit:latest

미국 서부(캘리포니아 북부 지역)

us-west-1

906394416424.dkr.ecr.us-west-1.amazonaws.com/aws-for-fluent-bit:latest

미국 서부(오레곤)

us-west-2

906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest

아시아 태평양(홍콩)

ap-east-1

449074385750.dkr.ecr.ap-east-1.amazonaws.com/aws-for-fluent-bit:latest

아시아 태평양(뭄바이)

ap-south-1

906394416424.dkr.ecr.ap-south-1.amazonaws.com/aws-for-fluent-bit:latest

아시아 태평양(서울)

ap-northeast-2

906394416424.dkr.ecr.ap-northeast-2.amazonaws.com/aws-for-fluent-bit:latest

아시아 태평양(싱가포르)

ap-southeast-1

906394416424.dkr.ecr.ap-southeast-1.amazonaws.com/aws-for-fluent-bit:latest

아시아 태평양(시드니)

ap-southeast-2

906394416424.dkr.ecr.ap-southeast-2.amazonaws.com/aws-for-fluent-bit:latest

아시아 태평양(도쿄)

ap-northeast-1

906394416424.dkr.ecr.ap-northeast-1.amazonaws.com/aws-for-fluent-bit:latest

캐나다(중부)

ca-central-1

906394416424.dkr.ecr.ca-central-1.amazonaws.com/aws-for-fluent-bit:latest

유럽(프랑크푸르트)

eu-central-1

906394416424.dkr.ecr.eu-central-1.amazonaws.com/aws-for-fluent-bit:latest

유럽(아일랜드)

eu-west-1

906394416424.dkr.ecr.eu-west-1.amazonaws.com/aws-for-fluent-bit:latest

유럽(런던)

eu-west-2

906394416424.dkr.ecr.eu-west-2.amazonaws.com/aws-for-fluent-bit:latest

유럽(파리)

eu-west-3

906394416424.dkr.ecr.eu-west-3.amazonaws.com/aws-for-fluent-bit:latest

유럽(스톡홀름)

eu-north-1

906394416424.dkr.ecr.eu-north-1.amazonaws.com/aws-for-fluent-bit:latest

중동(바레인)

me-south-1

741863432321.dkr.ecr.me-south-1.amazonaws.com/aws-for-fluent-bit:latest

남아메리카(상파울루)

sa-east-1

906394416424.dkr.ecr.sa-east-1.amazonaws.com/aws-for-fluent-bit:latest

AWS GovCloud(US-East)

us-gov-east-1

161423150738.dkr.ecr.us-gov-east-1.amazonaws.com/aws-for-fluent-bit:latest

AWS GovCloud (US-West)

us-gov-west-1

161423150738.dkr.ecr.us-gov-west-1.amazonaws.com/aws-for-fluent-bit:latest

중국(베이징)

cn-north-1

128054284489.dkr.ecr.cn-north-1.amazonaws.com.cn/aws-for-fluent-bit:latest

중국(닝샤)

cn-northwest-1

128054284489.dkr.ecr.cn-northwest-1.amazonaws.com.cn/aws-for-fluent-bit:latest

FireLens 구성을 사용하는 작업 정의 생성

FireLens에서 사용자 지정 로그 라우팅을 사용하려면 작업 정의에 다음 사항을 지정해야 합니다.

  • FireLens 구성을 포함하는 로그 라우터 컨테이너. 이 컨테이너는 필수로 표시해야 합니다.

  • awsfirelens 로그 드라이버를 지정하는 로그 구성이 포함된 하나 이상의 애플리케이션 컨테이너.

  • 작업이 로그를 라우팅하는 데 필요한 권한이 포함된 작업 IAM 역할 ARN.

AWS Management 콘솔을 사용하여 새로운 작업 정의를 생성할 때 로그 라우터 컨테이너를 쉽게 추가할 수 있는 FireLens 통합 섹션이 있습니다. 자세한 내용은 작업 정의 생성하기 단원을 참조하십시오.

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

다음 작업 정의 예에서는 Fluent Bit를 사용하여 로그를 CloudWatch Logs로 라우팅하는 로그 라우터 컨테이너를 정의합니다. 또한 로그 구성을 사용하여 로그를 Amazon Kinesis Data Firehose로 라우팅하는 애플리케이션 컨테이너도 정의합니다.

{ "family": "firelens-example-firehose", "taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role", "containerDefinitions": [ { "essential": true, "image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest", "name": "log_router", "firelensConfiguration": { "type": "fluentbit" }, "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "firelens-container", "awslogs-region": "us-west-2", "awslogs-create-group": "true", "awslogs-stream-prefix": "firelens" } }, "memoryReservation": 50 }, { "essential": true, "image": "httpd", "name": "app", "logConfiguration": { "logDriver":"awsfirelens", "options": { "Name": "firehose", "region": "us-west-2", "delivery_stream": "my-stream" } }, "memoryReservation": 100 } ] }

logConfiguration 객체에서 옵션으로 지정된 키 값 페어는 Fluentd 또는 Fluent Bit 출력 구성을 생성하는 데 사용됩니다. 다음은 Fluent Bit 출력 정의의 코드 예시입니다.

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

FireLens는 match 구성을 관리합니다. 이 구성은 작업 정의에는 지정되어 있지 않습니다.

ECS 메타데이터 사용

작업 정의에서 FireLens 구성을 지정할 때 선택적으로 enable-ecs-log-metadata에 대한 값을 전환할 수 있습니다. 기본적으로 Amazon ECS는 로그 원본을 식별하는 데 도움이 되는 추가 필드를 로그 항목에 추가합니다. enable-ecs-log-metadatafalse로 설정하여 이 작업을 비활성화할 수 있습니다.

  • ecs_cluster – 작업이 속한 클러스터의 이름입니다.

  • ecs_task_arn – 컨테이너가 속한 작업의 전체 ARN입니다.

  • ecs_task_definition – 작업에서 사용 중인 작업 정의 이름 및 개정입니다.

  • ec2_instance_id – 컨테이너가 호스팅되는 Amazon EC2 인스턴스 ID입니다. 이 필드는 EC2 시작 유형을 사용하는 작업에서만 유효합니다.

다음은 Amazon ECS 로그 메타데이터 설정 값을 지정할 때 필요한 구문을 보여 줍니다.

{ "containerDefinitions":[ { "essential":true, "image":"906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest", "name":"log_router", "firelensConfiguration":{ "type":"fluentbit", "options":{ "enable-ecs-log-metadata":"true | false" } } } ] }

사용자 정의 구성 파일 지정

FireLens가 사용자를 대신하여 생성하는 자동 생성 구성 파일 외에 사용자 정의 구성 파일도 지정할 수 있습니다. 구성 파일 형식은 사용 중인 로그 라우터의 기본 형식입니다. 자세한 내용은 Fluentd 구성 파일 구문Fluent Bit 구성 스키마를 참조하십시오.

사용자 정의 구성 파일에서 bridge 또는 awsvpc 네트워크 모드를 사용하는 작업의 경우 FireLens가 입력 구성에 Fluentd나 Fluent Bit를 추가하기 때문에 TCP를 통해 Fluentd 또는 Fluent Bit 전달 입력을 설정해서는 안 됩니다.

사용자 정의 구성 파일을 지정하려면 FireLens 구성에 다음 옵션이 포함되어야 합니다.

config-file-type

사용자 정의 구성 파일의 원본 위치입니다. 사용할 수 있는 옵션은 s3 또는 file입니다.

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 역할을 생성했는지 확인하십시오. 자세한 내용은 필요한 IAM 권한 단원을 참조하십시오.

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

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

Fargate 시작 유형을 사용하는 작업의 경우 유일하게 지원되는 config-file-type 값은 file입니다.

Fluent Logger 라이브러리 사용

awsfirelens 로그 드라이버가 작업 정의에 지정되어 있으면 ECS 에이전트는 다음 환경 변수를 컨테이너에 주입합니다.

FLUENT_HOST

FireLens 컨테이너에 할당된 IP 주소입니다.

FLUENT_PORT

Fluent Forward 프로토콜이 수신 대기 중인 포트입니다.

FLUENT_HOSTFLUENT_PORT 환경 변수를 사용하면 stdout을 거치지 않고 코드에서 로그 라우터로 직접 로깅할 수 있습니다. 자세한 내용은 GitHub에서 fluent-logger-golang을 참조하십시오.

정규 표현식을 사용하여 로그 필터링

Fluentd와 Fluent Bit 모두 콘텐츠에 근거하여 로그 필터링을 지원합니다. FireLens는 이 필터링을 활성화하는 간단한 방법을 제공합니다. 컨테이너 정의의 로그 구성 options에서 정규 표현식을 값으로 받아들이는 특수 키 exclude-patterninclude-pattern을 지정할 수 있습니다. exclude-pattern 키로 인해 정규 표현식과 일치하는 모든 로그가 삭제됩니다. include-pattern의 경우 정규 표현식과 일치하는 로그만 전송됩니다. 이 두 가지 키를 함께 사용할 수 있습니다.

다음 예에서는 이 필터의 사용법을 보여줍니다.

{ "containerDefinitions":[ { "logConfiguration":{ "logDriver":"awsfirelens", "options":{ "@type":"cloudwatch_logs", "log_group_name":"firelens-testing", "auto_create_stream":"true", "use_tag_as_stream":"true", "region":"us-west-2", "exclude-pattern":"^[a-z][aeiou].*$", "include-pattern":"^.*[aeiou]$" } } } ] }

예제 작업 정의

다음은 일반적인 로그 라우팅 옵션을 보여주는 몇 가지 작업 정의 예시입니다. 자세한 예는 GitHub의 Amazon ECS FireLens 예시를 참조하십시오.

CloudWatch Logs로 로그 전달

다음 작업 정의 예시에서는 로그를 CloudWatch Logs 로그 그룹에 전달하는 로그 구성을 지정하는 방법을 보여줍니다. 자세한 내용은 Amazon CloudWatch Logs User GuideAmazon CloudWatch Logs란 무엇입니까?를 참조하십시오.

로그 구성 옵션에서 로그 그룹 이름과 이 그룹이 속한 리전을 지정합니다. 사용자를 대신하여 Fluent Bit가 로그 그룹을 생성게 하려면 "auto_create_group":"true"를 지정합니다. 필터링에 도움이 되는 로그 스트림 접두사를 지정할 수도 있습니다. 자세한 내용은 Fluent Bit Plugin for CloudWatch Logs를 참조하십시오.

{ "family": "firelens-example-cloudwatch", "taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role", "containerDefinitions": [ { "essential": true, "image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest", "name": "log_router", "firelensConfiguration": { "type": "fluentbit" }, "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "firelens-container", "awslogs-region": "us-west-2", "awslogs-create-group": "true", "awslogs-stream-prefix": "firelens" } }, "memoryReservation": 50 }, { "essential": true, "image": "nginx", "name": "app", "logConfiguration": { "logDriver":"awsfirelens", "options": { "Name": "cloudwatch", "region": "us-west-2", "log_group_name": "firelens-testing-fluent-bit", "auto_create_group": "true", "log_stream_prefix": "from-fluent-bit" } }, "memoryReservation": 100 } ] }

Amazon Kinesis Data Firehose 전송 스트림에 로그 전달

다음 작업 정의 예시에서는 로그를 Amazon Kinesis Data Firehose 전송 스트림으로 전달하는 로그 구성을 지정하는 방법을 보여줍니다. Kinesis Data Firehose 전송 스트림이 이미 존재해야 합니다. 자세한 내용은 Amazon Kinesis Data Firehose 개발자 안내서Amazon Kinesis Data Firehose 전달 스트림 생성을 참조하십시오.

로그 구성 옵션에서 전송 스트림 이름과 이 스트림이 속한 지역을 지정합니다. 자세한 내용은 Fluent Bit Plugin for Amazon Kinesis Firehose를 참조하십시오.

{ "family": "firelens-example-firehose", "taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role", "containerDefinitions": [ { "essential": true, "image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest", "name": "log_router", "firelensConfiguration": { "type": "fluentbit" }, "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "firelens-container", "awslogs-region": "us-west-2", "awslogs-create-group": "true", "awslogs-stream-prefix": "firelens" } }, "memoryReservation": 50 }, { "essential": true, "image": "httpd", "name": "app", "logConfiguration": { "logDriver":"awsfirelens", "options": { "Name": "firehose", "region": "us-west-2", "delivery_stream": "my-stream" } }, "memoryReservation": 100 } ] }

External Fluentd 도는 Fluent Bit로 전달

다음 작업 정의 예시에서는 외부 Fluentd 또는 Fluent Bit 호스트에 로그를 전달하는 로그 구성을 지정하는 방법을 보여줍니다. 사용자 환경에 porthost를 지정합니다.

{ "family": "firelens-example-forward", "taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role", "containerDefinitions": [ { "essential": true, "image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest", "name": "log_router", "firelensConfiguration": { "type": "fluentbit" }, "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "firelens-container", "awslogs-region": "us-west-2", "awslogs-create-group": "true", "awslogs-stream-prefix": "firelens" } }, "memoryReservation": 50 }, { "essential": true, "image": "httpd", "name": "app", "logConfiguration": { "logDriver":"awsfirelens", "options": { "Name": "forward", "Host": "fluentdhost", "Port": "24224" } }, "memoryReservation": 100 } ] }