CRD를 사용하여 Kubernetes 클러스터에서 사용자 지정 Prometheus 스크랩 작업 만들기

Kubernetes 클러스터에서 Prometheus 메트릭 컬렉션 사용자 지정 은 ConfigMap을 사용하여 Kubernetes 클러스터의 기본 대상에서 Prometheus 메트릭의 스크래핑을 사용자 지정하는 방법을 설명합니다. 이 문서에서는 CRD(사용자 지정 리소스 정의)를 사용하여 추가 사용자 지정 및 추가 대상을 위한 사용자 지정 스크래핑 작업을 만드는 방법을 설명합니다.

CRD(사용자 지정 리소스 정의)

Prometheus에 Azure Monitor 관리 서비스를 사용하도록 설정하면 Pod 모니터 및 서비스 모니터에 대한 CRD(사용자 지정 리소스 정의)가 자동으로 배포됩니다. 그룹 이름 변경을 제외하고, 이러한 CRD는 Prometheus의 OSS Pod 모니터 및 OSS 서비스 모니터와 동일합니다. 클러스터에 기존 Prometheus CRD와 사용자 지정 리소스가 있는 경우 이러한 CRD는 추가 기능에서 만들어진 CRD와 충돌하지 않습니다. 동시에, 관리되는 Prometheus 추가 기능은 OSS Prometheus를 위해 만들어진 CRD를 선택하지 않습니다. 스크래핑 작업을 격리하기 위해 의도적으로 분리한 것입니다.

Pod 또는 서비스 모니터 만들기

Pod 및 Service Monitor 템플릿을 사용하고 API 사양에 따라 사용자 지정 리소스(PodMonitor 및 Service Monitor)를 만듭니다. Managed Prometheus에서 선택되기 위해 기존 OSS CR(사용자 지정 리소스)에서 필요한 유일한 변경 사항은 API 그룹으로, azmonitoring.coreos.com/v1입니다.

사용자의 Pod와 서비스 모니터는 다음 예와 같아야 합니다.

Pod 모니터 예

# Note the API version is azmonitoring.coreos.com/v1 instead of monitoring.coreos.com/v1
apiVersion: azmonitoring.coreos.com/v1
kind: PodMonitor

# Can be deployed in any namespace
metadata:
  name: reference-app
  namespace: app-namespace
spec:
  labelLimit: 63
  labelNameLengthLimit: 511
  labelValueLengthLimit: 1023

  # The selector specifies which pods to filter for
  selector:

    # Filter by pod labels
    matchLabels:
      environment: test
    matchExpressions:
      - key: app
        operator: In
        values: [app-frontend, app-backend]

    # [Optional] Filter by pod namespace. Required if service is in another namespace.
    namespaceSelector:
      matchNames: [app-frontend, app-backend]

  # [Optional] Labels on the pod with these keys will be added as labels to each metric scraped
  podTargetLabels: [app, region, environment]

  # Multiple pod endpoints can be specified. Port requires a named port.
  podMetricsEndpoints:
    - port: metricscs from the exa

서비스 모니터 예

# Note the API version is azmonitoring.coreos.com/v1 instead of monitoring.coreos.com/v1
apiVersion: azmonitoring.coreos.com/v1
kind: ServiceMonitor

# Can be deployed in any namespace
metadata:
  name: reference-app
  namespace: app-namespace
spec:
  labelLimit: 63
  labelNameLengthLimit: 511
  labelValueLengthLimit: 1023

  # The selector filters endpoints by service labels.
  selector:
    matchLabels:
      app: reference-app

  # Multiple endpoints can be specified. Port requires a named port.
  endpoints:
  - port: metrics

Pod 또는 서비스 모니터 배포

다음 예제와 같이 kubectl apply를 사용하여 Pod 또는 서비스 모니터를 배포합니다.

샘플 애플리케이션 만들기

Pod/서비스 모니터로 구성할 수 있는 Prometheus 메트릭을 노출하는 샘플 애플리케이션을 배포합니다.

kubectl apply -f https://raw.githubusercontent.com/Azure/prometheus-collector/refs/heads/main/internal/referenceapp/prometheus-reference-app.yaml

메트릭을 스크래핑하기 위한 Pod 모니터 및/또는 서비스 모니터 만들기

이전 단계에서 애플리케이션을 스크래핑하도록 구성된 Pod 모니터를 배포합니다.

Pod 모니터

kubectl apply -f https://raw.githubusercontent.com/Azure/prometheus-collector/refs/heads/main/otelcollector/deploy/example-custom-resources/pod-monitor/pod-monitor-reference-app.yaml

서비스 모니터

kubectl apply -f https://raw.githubusercontent.com/Azure/prometheus-collector/refs/heads/main/otelcollector/deploy/example-custom-resources/service-monitor/service-monitor-reference-app.yaml

문제 해결

Pod 또는 서비스 모니터가 성공적으로 적용되면 추가 기능이 자동으로 대상에서 메트릭 수집을 시작합니다. 사용자 지정 리소스의 일반적인 문제 해결 및 대상이 127.0.0.1/대상에 표시되는지 확인하려면 Azure Monitor의 Prometheus 메트릭 컬렉션 문제 해결 을 참조하세요.

스크랩 구성 설정

다음 섹션에서는 CRD에 사용되는 Prometheus 구성 파일에서 지원되는 설정에 대해 설명합니다. 이러한 설정에 대한 자세한 내용은 Prometheus 구성 참조 를 참조하세요.

글로벌 설정

전역 설정에 대한 구성 형식은 OSS prometheus 구성에서 지원하는 것과 동일합니다.

global:
  scrape_interval: <duration>
  scrape_timeout: <duration>
  external_labels:
    <labelname1>: <labelvalue>
    <labelname2>: <labelvalue>
scrape_configs:
  - <job-x>
  - <job-y>

글로벌 섹션에 제공된 설정은 CRD의 모든 스크래핑 작업에 적용되지만 개별 작업에 지정된 경우 재정의됩니다.

스크랩 구성

사용자 지정 리소스에 대해 지원되는 대상 검색 방법은 현재 Pod 및 서비스 모니터입니다.

Pod 및 서비스 모니터

Pod 및 서비스 모니터를 사용하여 발견된 대상에는 사용되는 모니터에 따라 다른 __meta_* 레이블이 있습니다. relabelings 섹션의 레이블을 사용하여 대상을 필터링하거나 대상의 레이블을 바꿀 수 있습니다. Pod 및 서비스 모니터의 예를 보려면 Pod 및 서비스 모니터 예시를 참조하세요.

레이블 재지정

relabelings 섹션은 대상 검색 시 적용되며 작업의 각 대상에 적용됩니다. 다음 예에서는 relabelings를 사용하는 방법을 보여 줍니다.

레이블 추가 작업의 모든 메트릭에 example_label이라는 새 레이블을 값 example_value과 함께 추가합니다. 해당 레이블이 항상 존재하고 작업의 모든 대상에 대한 레이블을 추가하기 때문에 __address__를 원본 레이블로만 사용합니다.

relabelings:
- sourceLabels: [__address__]
  targetLabel: example_label
  replacement: 'example_value'

Pod 또는 ServiceMonitor 레이블 사용

Pod 및 서비스 모니터를 사용하여 발견된 대상에는 사용되는 모니터에 따라 다른 __meta_* 레이블이 있습니다. 대상을 검색한 후 __* 레이블이 삭제됩니다. 메트릭 수준에서 사용하여 필터링하려면 먼저 레이블 이름을 할당하여 relabelings를 사용하여 유지합니다. 그런 다음 metricRelabelings를 사용하여 필터링합니다.

# Use the kubernetes namespace as a label called 'kubernetes_namespace'
relabelings:
- sourceLabels: [__meta_kubernetes_namespace]
  action: replace
  targetLabel: kubernetes_namespace

# Keep only metrics with the kubernetes namespace 'default'
metricRelabelings:
- sourceLabels: [kubernetes_namespace]
  action: keep
  regex: 'default'

작업 및 인스턴스 레이블 재지정

다른 레이블과 마찬가지로 원본 레이블을 기반으로 job 및 instance 레이블 값을 변경할 수 있습니다.

# Replace the job name with the pod label 'k8s app'
relabelings:
- sourceLabels: [__meta_kubernetes_pod_label_k8s_app]
  targetLabel: job

# Replace the instance name with the node name. This is helpful to replace a node IP
# and port with a value that is more readable
relabelings:
- sourceLabels: [__meta_kubernetes_node_name]
  targetLabel: instance

메트릭 레이블 재지정

메트릭 레이블 재지정은 스크래핑 후 및 수집 전에 적용됩니다. metricRelabelings 섹션을 사용하여 스크래핑 후 메트릭을 필터링합니다. 다음 예제를 참조하세요.

이름별 메트릭 삭제

# Drop the metric named 'example_metric_name'
metricRelabelings:
- sourceLabels: [__name__]
  action: drop
  regex: 'example_metric_name'

이름으로 특정 메트릭만 유지

# Keep only the metric named 'example_metric_name'
metricRelabelings:
- sourceLabels: [__name__]
  action: keep
  regex: 'example_metric_name'

# Keep only metrics that start with 'example_'
metricRelabelings:
- sourceLabels: [__name__]
  action: keep
  regex: '(example_.*)'

레이블별로 메트릭 필터링

# Keep metrics only where example_label = 'example'
metricRelabelings:
- sourceLabels: [example_label]
  action: keep
  regex: 'example'

# Keep metrics only if `example_label` equals `value_1` or `value_2`
metricRelabelings:
- sourceLabels: [example_label]
  action: keep
  regex: '(value_1|value_2)'

# Keep metrics only if `example_label_1 = value_1` and `example_label_2 = value_2`
metricRelabelings:
- sourceLabels: [example_label_1, example_label_2]
  separator: ';'
  action: keep
  regex: 'value_1;value_2'

# Keep metrics only if `example_label` exists as a label
metricRelabelings:
- sourceLabels: [example_label_1]
  action: keep
  regex: '.+'

메트릭 이름 바꾸기 메트릭 이름 바꾸기는 지원되지 않습니다.

기본 인증 및 전달자 토큰

PodMonitors와 ServiceMonitors를 사용하면 기본 인증 토큰이나 전달자 토큰을 사용하여 대상을 스크래핑할 수 있습니다. 사용자 이름/암호/토큰을 포함하는 비밀이 Pod/서비스 모니터와 동일한 네임스페이스에 있는지 확인합니다. 이 동작은 OSS prometheus-operator와 동일합니다.

TLS 기반 스크래핑

https 엔드포인트에서 Prometheus 메트릭을 스크래핑하려면, Prometheus 구성, PodMonitor, 또는 ServiceMonitor에 scheme가 https로 설정되고, 추가적인 TLS 설정이 필요합니다.

1. kube-system 네임스페이스에 ama-metrics-mtls-secret라는 이름의 비밀을 만듭니다. 비밀 개체의 데이터 섹션에 지정된 각 키-값 쌍은 데이터 섹션에 지정된 키와 동일한 파일 이름을 가진 이 /etc/prometheus/certs 위치에 별도의 파일로 탑재됩니다. 비밀 값은 base64로 인코딩되어야 합니다.

   다음은 비밀의 YAML 예제입니다.

   apiVersion: v1
   kind: Secret
   metadata:
     name: ama-metrics-mtls-secret
     namespace: kube-system
   type: Opaque
   data:
     <certfile>: base64_cert_content    
     <keyfile>: base64_key_content 
   

   ama-metrics-mtls-secret 비밀은 경로 ama-metrics에 있는 /etc/prometheus/certs/ Pod에 탑재되어 Prometheus 스크래퍼에서 사용할 수 있습니다. 키는 파일 이름이 됩니다. 값은 base64 디코딩되어 컨테이너 내의 파일 내용으로 추가됩니다.

2. Prometheus 구성, PodMonitor 또는 ServiceMonitor에서 파일 경로를 제공합니다.

   • 다음 예제를 사용하여 PodMonitor 또는 ServiceMonitor에 대한 TLS 구성 설정을 제공합니다.

    tlsConfig:
      ca:
        secret:
          key: "<certfile>"
          name: "ama-metrics-mtls-secret"
      cert:
        secret:
          key: "<certfile>"
          name: "ama-metrics-mtls-secret"
      keySecret:
          key: "<keyfile>"
          name: "ama-metrics-mtls-secret"
      insecureSkipVerify: false
   

기본 인증 및 TLS

CRD에서 기본 인증 또는 전달자 토큰(파일 기반 자격 증명) 및 TLS 인증 설정을 모두 사용하려면 아래와 같이 해당 base64로 인코딩된 값이 있는 데이터 섹션 아래의 모든 키를 비밀에 포함해야 ama-metrics-mtls-secret 합니다.

apiVersion: v1
kind: Secret
metadata:
  name: ama-metrics-mtls-secret
  namespace: kube-system
type: Opaque
data:
  certfile: base64_cert_content    # used for TLS
  keyfile: base64_key_content      # used for TLS
  password1: base64-encoded-string # used for basic auth
  password2: base64-encoded-string # used for basic auth

다음 단계

• Prometheus 메트릭 수집에 대해 자세히 알아보기