AWS Distro for OpenTelemetry(ADOT)은 AWS 환경에 최적화 되어있는 업스트림 OpenTelemtry 프로젝트의 AWS 지원 배포판입니다. OpenTelemetry는 CNCF(Cloud Native Computing Foundation)에서 관리하는 오픈소스 관찰가능성(Observability) 프레임워크로 Metric, Log, Trace 데이터를 생성하고 관리하도록 디자인되어 있습니다. Amazon EKS에서는 ADOT을 EKS 관리형 애드온으로 제공하여 EKS 클러스터에서 발생하는 메트릭과 Trace 데이터 등을 여러 모니터링 솔루션에 전송하여 상호 연관된 데이터를 확인할 수 있도록 합니다.

그러면 지금부터 EKS 클러스터에 AWS Distro for OpenTelemetry 애드온을 설치해 보도록 하겠습니다.

사전 준비 사항

ADOT 애드온 설치 전 필요한 사전 준비 사항은 ADOT Operator에서 사용되는 admission webhook에서 사용할 인증서를 관리하기 위해 클러스터에 cert-manager를 설치해야 합니다. 명령어를 실행할 지점에 kubectl, AWS CLI v2가 사전에 설치되어 있어야 하며, kubeconfig에 애드온을 설치할 클러스터 정보가 저장되어 있어야 합니다. 자세한 내용은 문서를 참고하시면 됩니다.

# kubeconfig 업데이트
$ aws eks update-kubeconfig --name <cluster_name> --region <YOUR_AWS_REGION>

# eks addon-manager에 RBAC 권한 적용
$ kubectl apply -f https://amazon-eks.s3.amazonaws.com/docs/addons-otel-permissions.yaml

# cert-manager 설치
$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.8.2/cert-manager.yaml

# cert-manager 설치 확인
$ kubectl get pod -w -n cert-manager

애드온 설치

cert-manager 가 정상적으로 설치된 것이 확인되면, AWS 콘솔 또는 AWS CLI를 통해 문서의 가이드에 따라 ADOT 애드온을 설치합니다. 해당 문서의 경우 '추가 기능 액세스' 부분을 설정하는 방법에 대한 가이드가 누락되어 있습니다. 우선은 해당 부분을 설정하지 않고 설치하고 난 이후에 본 문서에서 설명하도록 하겠습니다.

애드온 설치 상태가 '활성'으로 전환되고 나면, 클러스터 내부에 opentelemetry-operator 파드가 새롭게 생성된 것을 확인하실 수 있습니다.

$ kubectl get pods -n opentelemetry-operator-system
NAME                                      READY   STATUS    RESTARTS   AGE
opentelemetry-operator-5987b6f684-qmmqd   2/2     Running   0          45s

이는 문서에 나온 것처럼 ADOT Operator가 설치된 것을 의미합니다. Kubernetes Operator는 Kubernetes 네이티브 어플리케이션을 자동으로 배포하고 관리할 수 있도록 제공하며, ADOT Operator는 Kubernetes Operator의 구현체입니다. 여기서 Kubernetes 네이티브 어플리케이션은 ADOT Collector를 지칭하며, ADOT Collector는 telemtry 데이터를 수집, 처리, 전송하는 역할을 담당하는 agent입니다. Kubernetes Operator는 사용자 정의 리소스(CR)의 배포와 구성을 단순화하기 위해 사용자 정의 리소스 정의(CRD)를 사용하는 커스텀 컨트롤러(Controller)로, 컨트롤러의 역할대로 CRD로 생성된 리소스를 감시(watch)하여 원하는 상태(Desired State)와 현재 상태(Current State)가 동일하도록 유지합니다. ADOT Operator는 OpenTelemetryCollector라는 사용자 정의 리소스에 대한 생성/변경/삭제 요청을 감지하면 원하는 상태(Desired State)와 일치하도록 실제 해당 리소스를 생성/변경/삭제하는 역할을 수행합니다.

*출처: https://aws.amazon.com/blogs/containers/metrics-and-traces-collection-using-amazon-eks-add-ons-for-aws-distro-for-opentelemetry/

지금까지의 과정을 통해 ADOT Operator가 정상적으로 설치되었다면, 이제 ADOT Collector를 설치해 보겠습니다. OpenTelemetryCollector는 애드온의 '선택적 구성 설정(Optional configuration settings)' 에서 지정하거나 직접 클러스터에 매니페스트를 배포하는 2가지 방법 중 하나로 배포가 가능합니다. EKS 서비스에서 제공하는 사전 정의(Preconfigured)된 OpenTelemetry Collector를 그대로 사용하려는 경우 애드온 설정을 통해 간단히 배포하실 수 있고, OpenTelemetryCollector 설정을 커스텀하게 변경하거나 Deployment 모드를 변경하려는 경우 직접 OpenTelemetryCollector 매니페스트를 배포하시면 됩니다.

애드온 선택적 구성 설정을 통해 ADOT Collector 설치

Amazon EKS 콘솔의 EKS 클러스터 > 추가 기능 > AWS Distro for OpenTelemetry > 편집 > 선택적 구성 설정 > 구성 값에서 Collector를 설정하실 수 있습니다. 원하는 수집 데이터 형태에 따라 아래 각 문서를 통해 Collector 구성 방법을 참고하실 수 있습니다.

• 프로메테우스 메트릭 Collector: https://aws-otel.github.io/docs/getting-started/adot-eks-add-on/config-prometheus-metrics
• 컨테이너 로그 Collector: https://aws-otel.github.io/docs/getting-started/adot-eks-add-on/config-container-logs
• X-Ray Trace Collector: https://aws-otel.github.io/docs/getting-started/adot-eks-add-on/config-otlp-ingest

예를 들어 프로메테우스 메트릭 Collector를 생성하기 위해서는 문서에 나온 것처럼 콘솔 내 구성 값에 아래와 같이 지정하시면 됩니다.

collector:
  prometheusMetrics:
    serviceAccount:
      annotations:
        eks.amazonaws.com/role-arn: <iam_role_arn>
    pipelines:
      metrics:
        amp:
          enabled: true
        emf:
          enabled: true
    exporters:
      prometheusremotewrite:
        endpoint: <remote_write_endpoint>

콘솔 내 선택적 구성 설정 위의 추가 기능 액세스를 확인해 보시면 EKS Pod Identity 또는 IRSA 2가지 방법 중 하나로 서비스 어카운트에 권한을 부여할 수 있습니다. EKS Pod Identity를 사용하려면 클러스터 내부에 Amazon EKS Pod Identity 에이전트 애드온이 설치되어 있어야 합니다. 만일 설치되어 있지 않다면 문서를 참고하여 EKS Pod Identity를 설치하시면 됩니다. 설치 후 EKS 클러스터 > 추가 기능 > AWS Distro for OpenTelemetry > 편집 > 추가 기능 액세스에서 프로메테우스 메트릭 수집 및 전송에 필요한 권한을 부여할 수 있도록 권장 역할 생성 버튼을 누른 후 계속적으로 다음 버튼을 누르면 AmazonPrometheusRemoteWriteAccess와 CloudWatchAgentServerPolicy 정책이 부여된 IAM Role이 자동으로 생성됩니다. IAM Role을 생성한 후 서비스 계정의 Pod Identity IAM 역할: adot-col-prom-metrics에 아래와 같이 해당 IAM Role을 지정하여 애드온을 업데이트 하면, 위의 collector 설정대로 OpenTelemetryCollector 리소스와 필요한 IAM 정책이 부여된 서비스 어카운트 adot-col-prom-metrics가 클러스터에 자동으로 생성됩니다.

EKS Pod Identity 대신 IRSA 방식을 사용하려면 문서에 나온대로 아래 eksctl 명령어를 통해 서비스 어카운트를 생성하신 후 생성된 IAM Role을 콘솔 상에 지정하여 애드온을 변경하시면 됩니다. 이 때 반드시 서비스 어카운트 이름은 adot-col-prom-metrics 이어야 합니다.

$ eksctl create iamserviceaccount \
    --name adot-col-prom-metrics \
    --namespace opentelemetry-operator-system \
    --cluster <your_cluster_name> \
    --attach-policy-arn arn:aws:iam::aws:policy/AmazonPrometheusRemoteWriteAccess \
    --attach-policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
    --approve \
    --role-only

애드온을 변경하여 '활성' 상태가 되면 아래와 같이 adot-col-prom-metrics라는 이름으로 사전 정의된 Collector가 배포되었고, 그에 따라 adot-col-prom-metrics-collector라는 Prefix를 가진 파드가 생성된 것을 확인하실 수 있을 것입니다.

$ kubectl get OpenTelemetryCollector -A
NAMESPACE                       NAME                      MODE         VERSION   READY   AGE   IMAGE                                                         MANAGEMENT
opentelemetry-operator-system   adot-col-prom-metrics     deployment   0.109.0   1/1     25s   public.ecr.aws/aws-observability/aws-otel-collector:v0.41.1   managed

매니페스트를 통해 ADOT Collector 설치

OpenTelemetryCollector를 EKS에 의해 사전에 지정되어 있는 설정이 아닌 커스텀한 설정 또는 다른 Deployment 모드로 배포되기를 원하는 경우 별도로 매니페스트를 통해 배포하실 수 있습니다. Amazon Managed Prometheus로 메트릭 전송, Amazon CloudWatch로 로그 전송, AWS X-Ray로 Trace 데이터 전송을 위한 Collector 매니페스트를 배포하는 방법은 문서의 Next Topics에 연결된 각 문서들을 참고하실 수 있습니다. Collector 매니페스트는 aws-otel-community github에도 별도로 나와 있으니 참고하시면 됩니다.

Amazon Managed Prometheus로 메트릭 전송하기 위한 Collector를 배포하는 예시로 aws-otel-community github의 매니페스트를 복사하여 <YOUR_AWS_REGION>와 <YOUR_REMOTE_WRITE_ENDPOINT> 값을 변경하고, yaml 파일(예사: collector-config-amp.yaml)을 저장합니다. 필요한 경우 매니페스트에서 프로메테우스 scrape_configs 값을 커스텀하게 변경하실 수 있습니다. 매니페스트의 ClusterRoleBinding 리소스를 확인해 보면 서비스 어카운트 이름이 adot-collector로 지정되어 있으므로 IRSA 생성 시 아래와 같이 adot-collector로 생성하고 필요에 따라 정책을 추가하거나 제거하시면 됩니다.

# IRSA 생성
$ eksctl create iamserviceaccount \
    --name adot-collector \
    --cluster <cluster-name> \
    --attach-policy-arn arn:aws:iam::aws:policy/AmazonPrometheusRemoteWriteAccess \
    --attach-policy-arn arn:aws:iam::aws:policy/AWSXrayWriteOnlyAccess \
    --attach-policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
    --approve 

# ADOT Collector 매니페스트 배포
$ kubectl apply -f collector-config-amp.yaml

배포 후 아래 명령어를 통해 Collector가 매니페스트 설정대로 Deployment 오브젝트 형태(deployment 모드)로 배포된 것을 확인하실 수 있습니다.

$ kubectl get OpenTelemetryCollector -A
NAMESPACE                       NAME                      MODE         VERSION   READY   AGE    IMAGE                                                         MANAGEMENT
default                         my-collector-amp          deployment   0.109.0   1/1     15m    public.ecr.aws/aws-observability/aws-otel-collector:v0.41.1   managed

Collector가 모두 배포되고 나면 my-collector-<collector 이름> 형태의 파드가 클러스터에 생성된 것을 확인하실 수 있으며, 해당 Collector에 의해 프로메테우스로 메트릭이 전송될 것입니다. 동일한 방법으로 CloudWatch로 로그를 전송하거나 X-Ray로 Trace 데이터를 전송하도록 구성하실 수 있습니다.