클러스터에 대한 AWS Fargate 로깅 시작

Amazon EKS on Fargate의 내장 로그 라우터를 사용하여 Fargate 로그를 구성하고 목적지로 전송하는 방법을 설명합니다.

출처: 문서

본문

Amazon EKS on Fargate는 Fluent Bit 기반의 내장 로그 라우터를 제공합니다. 즉 Fluent Bit 컨테이너를 사이드카로 명시적으로 실행하지 않고 Amazon이 대신 실행해 줍니다. 여러분이 해야 할 일은 로그 라우터를 구성하는 것뿐입니다. 구성은 전용 ConfigMap을 통해 이루어지며, 이 ConfigMap은 다음 기준을 충족해야 합니다.

이름이 aws-logging이어야 합니다.
aws-observability라는 전용 네임스페이스에 생성되어야 합니다.
5300자를 초과할 수 없습니다.

ConfigMap을 생성하면 Amazon EKS on Fargate가 자동으로 이를 감지하고 로그 라우터를 그로 구성합니다. Fargate는 AWS 관리형 Fluent Bit의 업스트림 호환 배포판인 AWS for Fluent Bit 버전을 사용합니다. 자세한 내용은 GitHub의 AWS for Fluent Bit를 참조하세요.

로그 라우터를 사용하면 AWS의 다양한 로그 분석 및 스토리지 서비스를 활용할 수 있습니다. Fargate에서 Amazon CloudWatch 및 Amazon OpenSearch Service로 로그를 직접 스트리밍할 수 있습니다. 또한 Amazon Data Firehose를 통해 Amazon S3, Amazon Kinesis Data Streams, 파트너 도구 등의 목적지로 로그를 스트리밍할 수도 있습니다.

Fargate Pod를 배포할 기존 Kubernetes 네임스페이스를 지정하는 기존 Fargate 프로필이 필요합니다. 자세한 내용은 Step 3: 클러스터용 Fargate 프로필 생성을 참조하세요. 또한 기존 Fargate Pod 실행 역할(pod execution role)이 필요합니다. 자세한 내용은 Step 2: Fargate Pod 실행 역할 생성을 참조하세요.

로그 라우터 구성

중요

로그가 성공적으로 게시되려면 클러스터가 있는 VPC에서 로그 목적지까지 네트워크 액세스가 있어야 합니다. 이는 주로 VPC의 송신(egress) 규칙을 사용자 지정하는 사용자와 관련됩니다. CloudWatch 사용 예시는 Amazon CloudWatch Logs 사용자 가이드의 인터페이스 VPC 엔드포인트와 CloudWatch Logs 사용을 참조하세요.

다음 단계에서는 모든 example value를 자신의 값으로 바꾸세요.

aws-observability라는 전용 Kubernetes 네임스페이스를 생성합니다.
다음 내용을 컴퓨터의 aws-observability-namespace.yaml이라는 파일에 저장합니다. name 값은 aws-observability여야 하며 aws-observability: enabled 라벨이 필요합니다.

kind: Namespace
apiVersion: v1
metadata:
  name: aws-observability
  labels:
    aws-observability: enabled

네임스페이스를 생성합니다.

kubectl apply -f aws-observability-namespace.yaml

컨테이너 로그를 목적지로 전송하기 위해 Fluent Conf 데이터 값을 가진 ConfigMap을 생성합니다. Fluent Conf는 컨테이너 로그를 원하는 로그 목적지로 라우팅하는 데 사용되는 빠르고 가벼운 로그 프로세서 구성 언어인 Fluent Bit입니다. 자세한 내용은 Fluent Bit 문서의 Configuration File을 참조하세요.

중요

일반적인 Fluent Conf에 포함되는 주요 섹션은 Service, Input, Filter, Output입니다. 그러나 Fargate 로그 라우터는 다음만 허용합니다.

Filter 및 Output 섹션

Parser 섹션

다른 섹션을 제공하면 거부됩니다.

Fargate 로그 라우터는 Service 및 Input 섹션을 관리합니다. 다음과 같은 Input 섹션이 있으며 이는 수정할 수 없고 ConfigMap에 필요하지도 않습니다. 그러나 메모리 버퍼 제한과 로그에 적용되는 태그 같은 정보를 얻을 수 있습니다.

[INPUT]
    Name tail
    Buffer_Max_Size 66KB
    DB /var/log/flb_kube.db
    Mem_Buf_Limit 45MB
    Path /var/log/containers/*.log
    Read_From_Head On
    Refresh_Interval 10
    Rotate_Wait 30
    Skip_Long_Lines On
    Tag kube.*

ConfigMap을 만들 때 Fargate가 필드를 검증하는 데 사용하는 다음 규칙을 고려하세요.

[FILTER], [OUTPUT], [PARSER]는 각각의 해당 키 아래에 지정해야 합니다. 예를 들어 [FILTER]는 filters.conf 아래에 있어야 합니다. filters.conf 아래에 하나 이상의 [FILTER]를 둘 수 있습니다. [OUTPUT] 및 [PARSER] 섹션도 해당 키 아래에 있어야 합니다. 여러 [OUTPUT] 섹션을 지정하면 동시에 다른 목적지로 로그를 라우팅할 수 있습니다.
Fargate는 각 섹션의 필수 키를 검증합니다. Name과 match는 각 [FILTER] 및 [OUTPUT]에 필요합니다. Name과 format은 각 [PARSER]에 필요합니다. 키는 대소문자를 구분하지 않습니다.
${ENV_VAR} 같은 환경 변수는 ConfigMap에서 허용되지 않습니다.
각 filters.conf, output.conf, parsers.conf 내에서 지시문(directive) 또는 키-값 쌍의 들여쓰기는 동일해야 합니다. 키-값 쌍은 지시문보다 더 들여쓰기 되어야 합니다.
Fargate는 grep, parser, record_modifier, rewrite_tag, throttle, nest, modify, kubernetes 같은 지원 필터에 대해 검증합니다.
Fargate는 es, firehose, kinesis_firehose, cloudwatch, cloudwatch_logs, kinesis 같은 지원 출력에 대해 검증합니다.
로깅을 활성화하려면 ConfigMap에 지원되는 Output 플러그인이 하나 이상 제공되어야 합니다. 로깅을 활성화하는 데 Filter와 Parser는 필요하지 않습니다.

검증 중에 발생하는 문제를 해결하기 위해 원하는 구성을 사용하여 Amazon EC2에서 Fluent Bit를 실행할 수도 있습니다. 다음 예시 중 하나를 사용하여 ConfigMap을 생성하세요.

중요

Amazon EKS Fargate 로깅은 ConfigMap의 동적 구성을 지원하지 않습니다. ConfigMap의 변경 사항은 새 Pod에만 적용됩니다. 기존 Pod에는 변경 사항이 적용되지 않습니다.

원하는 로그 목적지에 대한 예시를 사용하여 ConfigMap을 생성하세요.

참고

로그 목적지로 Amazon Kinesis Data Streams를 사용할 수도 있습니다. Kinesis Data Streams를 사용하는 경우 Pod 실행 역할에 kinesis:PutRecords 권한이 부여되었는지 확인하세요. 자세한 내용은 Fluent Bit: Official Manual의 Amazon Kinesis Data Streams Permissions를 참조하세요.

예시

로그를 목적지로 보내도록 Fargate Pod 실행 역할의 권한을 설정합니다.
목적지에 대한 IAM 정책을 컴퓨터로 다운로드합니다.
예시 — 다운로드한 정책 파일에서 IAM 정책을 생성합니다.

aws iam create-policy --policy-name eks-fargate-logging-policy --policy-document file://permissions.json

다음 명령으로 IAM 정책을 Fargate 프로필에 지정된 Pod 실행 역할에 연결합니다. 111122223333을 계정 ID로 바꾸세요. AmazonEKSFargatePodExecutionRole을 Pod 실행 역할로 바꾸세요(자세한 내용은 Step 2: Fargate Pod 실행 역할 생성 참조).

aws iam attach-role-policy \
  --policy-arn arn:aws:iam::111122223333:policy/eks-fargate-logging-policy \
  --role-name AmazonEKSFargatePodExecutionRole

Kubernetes 필터 지원

Fluent Bit Kubernetes 필터를 사용하면 로그 파일에 Kubernetes 메타데이터를 추가할 수 있습니다. 필터에 대한 자세한 내용은 Fluent Bit 문서의 Kubernetes를 참조하세요. API 서버 엔드포인트를 사용하여 필터를 적용할 수 있습니다.

filters.conf: |
    [FILTER]
        Name             kubernetes
        Match            kube.*
        Merge_Log           On
        Buffer_Size         0
        Kube_Meta_Cache_TTL 300s

중요

Kube_URL, Kube_CA_File, Kube_Token_Command, Kube_Token_File은 서비스 소유 구성 매개변수이므로 지정하면 안 됩니다. Amazon EKS Fargate가 이 값을 채웁니다.

Kube_Meta_Cache_TTL은 Fluent Bit가 최신 메타데이터를 위해 API 서버와 통신할 때까지 기다리는 시간입니다. Kube_Meta_Cache_TTL을 지정하지 않으면 Amazon EKS Fargate가 API 서버의 부하를 줄이기 위해 기본값인 30분을 추가합니다.

Fluent Bit 프로세스 로그를 계정으로 전송하려면

다음 ConfigMap을 사용하여 Fluent Bit 프로세스 로그를 선택적으로 Amazon CloudWatch로 전송할 수 있습니다. Fluent Bit 프로세스 로그를 CloudWatch로 전송하려면 추가 로그 수집 및 스토리지 비용이 발생합니다. region-code를 클러스터가 있는 AWS 리전으로 바꾸세요.

kind: ConfigMap
apiVersion: v1
metadata:
  name: aws-logging
  namespace: aws-observability
  labels:
data:
  # Configuration files: server, input, filters and output
  # ======================================================
  flb_log_cw: "true"  # Ships Fluent Bit process logs to CloudWatch.

  output.conf: |
    [OUTPUT]
        Name cloudwatch
        Match kube.*
        region region-code
        log_group_name fluent-bit-cloudwatch
        log_stream_prefix from-fluent-bit-
        auto_create_group true

로그는 클러스터와 동일한 AWS 리전의 CloudWatch에 있습니다. 로그 그룹 이름은 my-cluster-fluent-bit-logs이고 Fluent Bit 로그스트림 이름은 fluent-bit-podname-pod-namespace입니다.

참고

프로세스 로그는 Fluent Bit 프로세스가 성공적으로 시작될 때만 전송됩니다. Fluent Bit 시작 중 실패가 있으면 프로세스 로그가 유실됩니다. 프로세스 로그는 CloudWatch로만 전송할 수 있습니다.

계정으로 프로세스 로그 전송을 디버깅하려면 이전 ConfigMap을 적용하여 프로세스 로그를 얻을 수 있습니다. Fluent Bit 시작 실패는 일반적으로 시작 중에 ConfigMap이 Fluent Bit에 의해 구문 분석되거나 수용되지 않기 때문입니다.

Fluent Bit 프로세스 로그 전송 중지

Fluent Bit 프로세스 로그를 CloudWatch로 전송하려면 추가 로그 수집 및 스토리지 비용이 발생합니다. 기존 ConfigMap 구성에서 프로세스 로그를 제외하려면 다음 단계를 따르세요.

Fargate 로깅을 활성화한 후 Amazon EKS 클러스터의 Fluent Bit 프로세스 로그용으로 자동 생성된 CloudWatch 로그 그룹을 찾습니다. my-cluster-fluent-bit-logs 형식을 따릅니다.
CloudWatch 로그 그룹에서 각 Pod의 프로세스 로그용으로 생성된 기존 CloudWatch 로그 스트림을 삭제합니다.
ConfigMap을 편집하고 flb_log_cw: "false"로 설정합니다.
클러스터의 기존 Pod를 다시 시작합니다.

테스트 애플리케이션

샘플 Pod를 배포합니다.
다음 내용을 컴퓨터의 sample-app.yaml이라는 파일에 저장합니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: sample-app
  namespace: same-namespace-as-your-fargate-profile
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:latest
          ports:
            - name: http
              containerPort: 80

매니페스트를 클러스터에 적용합니다.

kubectl apply -f sample-app.yaml

ConfigMap에서 구성한 목적지에서 NGINX 로그를 확인합니다.

크기 고려 사항

로그 라우터에 최대 50 MB의 메모리를 계획할 것을 권장합니다. 애플리케이션이 매우 높은 처리량으로 로그를 생성할 것으로 예상된다면 최대 100 MB를 계획하세요.

문제 해결

유효하지 않은 ConfigMap 같은 이유로 로깅 기능이 활성화 또는 비활성화되었는지, 그리고 왜 유효하지 않은지 확인하려면 kubectl describe pod pod-name으로 Pod 이벤트를 확인하세요. 출력에는 로깅이 활성화되었는지 여부를 명확히 하는 Pod 이벤트가 포함될 수 있으며, 예를 들면 다음과 같습니다.

[...]
Annotations:          CapacityProvisioned: 0.25vCPU 0.5GB
                      Logging: LoggingDisabled: LOGGING_CONFIGMAP_NOT_FOUND
[...]
Events:
  Type     Reason           Age        From                                                           Message
  ----     ------           ----       ----                                                           -------
  Warning  LoggingDisabled    fargate-scheduler                                              Disabled logging because aws-logging configmap was not found. configmap "aws-logging" not found

Pod 이벤트는 설정에 따라 시간이 지나면 사라지는 임시(ephemeral) 항목입니다. kubectl describe pod pod-name을 사용하여 Pod의 어노테이션도 볼 수 있습니다. Pod 어노테이션에는 로깅 기능이 활성화되었는지 비활성화되었는지와 그 이유에 대한 정보가 있습니다.

더 알아보기 (Learn more)

공식 문서