Prometheus를 사용하여 구성 동기화 모니터링

이 페이지에서는 구성 동기화에서 Prometheus로 측정항목을 전송하는 방법을 설명합니다.

이 페이지에서는 Prometheus를 사용하여 구성 동기화 측정항목을 확인하는 방법을 설명합니다. 측정항목을 내보내는 다른 방법은 Cloud Monitoring으로 구성 동기화 모니터링 또는 커스텀 모니터링으로 구성 동기화 모니터링을 참조하세요.

구성 동기화는 측정항목을 자동으로 수집하고 Prometheus로 내보냅니다. Prometheus에서 커스텀 측정항목을 가져오도록 Cloud Monitoring을 구성할 수 있습니다. 그러면 Prometheus와 Monitoring 모두에서 커스텀 측정항목을 확인할 수 있습니다. 자세한 내용은 GKE 문서에서 Prometheus 사용을 참조하세요.

측정항목 스크래핑

모든 Prometheus 측정항목을 포트 8675에서 스크랩할 수 있습니다. 측정항목을 스크랩하기 전에 다음 두 가지 방법 중 하나로 Prometheus용 클러스터를 구성해야 다음 중 하나를 수행합니다.

  • Prometheus 문서를 따라 스크랩용 클러스터를 구성합니다. 또는

  • Prometheus Operator를 다음 매니페스트와 함께 사용합니다. 그러면 모든 구성 동기화 측정항목이 10초마다 스크랩됩니다.

    1. 매니페스트 파일을 저장할 임시 디렉터리를 만듭니다.

      mkdir config-sync-monitor
      cd config-sync-monitor
      
    2. curl 명령어를 사용하여 CoreOS 저장소에서 Prometheus Operator 매니페스트를 다운로드합니다.

      curl -o bundle.yaml https://raw.githubusercontent.com/coreos/prometheus-operator/master/bundle.yaml
      

      이 매니페스트는 권장되지 않는 default 네임스페이스를 사용하도록 구성됩니다. 다음 단계에서는 대신 monitoring 네임스페이스를 사용하도록 구성을 수정합니다. 다른 네임스페이스를 사용하려면 네임스페이스를 나머지 단계에서 표시되는 monitoring으로 대체합니다.

    3. 파일을 만들어 위 번들에 있는 ClusterRoleBinding의 네임스페이스를 업데이트합니다.

      # patch-crb.yaml
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRoleBinding
      metadata:
        name: prometheus-operator
      subjects:
      - kind: ServiceAccount
        name: prometheus-operator
        namespace: monitoring # we are patching from default namespace
      
    4. 패치를 적용하고 매니페스트에서 다른 리소스의 네임스페이스를 수정하는 kustomization.yaml 파일을 만듭니다.

      # kustomization.yaml
      resources:
      - bundle.yaml
      
      namespace: monitoring
      
      patchesStrategicMerge:
      - patch-crb.yaml
      
    5. monitoring 네임스페이스가 없으면 만듭니다. 네임스페이스에 다른 이름을 사용할 수 있지만 이 경우 이전 단계의 YAML 매니페스트에서 namespace 값도 변경합니다.

      kubectl create namespace monitoring
      
    6. 다음 명령어를 사용하여 Kustomize 매니페스트를 적용합니다.

      kubectl apply -k .
      
      until kubectl get customresourcedefinitions servicemonitors.monitoring.coreos.com ; \
      do date; sleep 1; echo ""; done

      두 번째 명령어는 클러스터에서 CRD를 사용할 수 있을 때까지 차단됩니다.

    7. 구성 동기화에서 측정항목을 스크랩하는 Prometheus 서버를 구성하는 데 필요한 리소스의 매니페스트를 만듭니다.

      # config-sync-monitoring.yaml
      apiVersion: v1
      kind: ServiceAccount
      metadata:
        name: prometheus-config-sync
        namespace: monitoring
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRole
      metadata:
        name: prometheus-config-sync
      rules:
      - apiGroups: [""]
        resources:
        - nodes
        - services
        - endpoints
        - pods
        verbs: ["get", "list", "watch"]
      - apiGroups: [""]
        resources:
        - configmaps
        verbs: ["get"]
      - nonResourceURLs: ["/metrics"]
        verbs: ["get"]
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRoleBinding
      metadata:
        name: prometheus-config-sync
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: ClusterRole
        name: prometheus-config-sync
      subjects:
      - kind: ServiceAccount
        name: prometheus-config-sync
        namespace: monitoring
      ---
      apiVersion: monitoring.coreos.com/v1
      kind: Prometheus
      metadata:
        name: config-sync
        namespace: monitoring
        labels:
          prometheus: config-sync
      spec:
        replicas: 2
        serviceAccountName: prometheus-config-sync
        serviceMonitorSelector:
          matchLabels:
            prometheus: config-management
        alerting:
          alertmanagers:
          - namespace: default
            name: alertmanager
            port: web
        resources:
          requests:
            memory: 400Mi
      ---
      apiVersion: v1
      kind: Service
      metadata:
        name: prometheus-config-sync
        namespace: monitoring
        labels:
          prometheus: config-sync
      spec:
        type: NodePort
        ports:
        - name: web
          nodePort: 31900
          port: 9190
          protocol: TCP
          targetPort: web
        selector:
          prometheus: config-sync
      --- 
      --- 
      
    8. 다음 명령어를 사용하여 매니페스트를 적용합니다.

      kubectl apply -f config-sync.yaml
      
      until kubectl rollout status statefulset/prometheus-config-sync -n monitoring; \
      do sleep 1; done
      

      두 번째 명령어는 포드가 실행될 때까지 차단됩니다.

    9. Prometheus 서버의 웹 포트를 로컬 머신에 전달하여 설치를 확인할 수 있습니다.

      kubectl -n monitoring port-forward svc/prometheus-config-sync 9190
      

      이제 http://localhost:9190에서 Prometheus 웹 UI에 액세스할 수 있습니다.

    10. 임시 디렉터리를 삭제합니다.

      cd ..
      rm -rf config-sync-monitor
      

사용 가능한 Prometheus 측정항목

구성 동기화는 다음과 같은 측정항목을 수집하여 Prometheus에 제공합니다. 라벨 열에는 각 측정항목에 적용 가능한 모든 라벨이 표시됩니다. 라벨이 없는 측정항목은 시간이 지남에 따라 단일 측정을 나타내는 반면 라벨이 있는 측정항목은 라벨 값의 각 조합에 대해 하나씩 여러 측정을 나타냅니다.

이 테이블이 동기화되지 않으면 Prometheus 사용자 인터페이스의 프리픽스로 측정항목을 필터링할 수 있으며 모든 해당 측정항목은 config_sync_ 프리픽스로 시작합니다.

이름 유형 라벨 설명
config_sync_api_duration_seconds_bucket 히스토그램 status, operation API 서버 호출의 지연 시간 분포(각 주기 동안 버킷으로 분배)
config_sync_api_duration_seconds_count 히스토그램 status, operation API 서버 호출의 지연 시간 분포(지속 시간 무시)
config_sync_api_duration_seconds_sum 히스토그램 status, operation 모든 API 서버 호출 지속 시간의 합계
config_sync_apply_duration_seconds_bucket 히스토그램 commit, status 신뢰 소스에서 선언된 리소스를 클러스터에 적용할 때의 지연 시간 분포(각 주기 동안 버킷으로 분배)
config_sync_apply_duration_seconds_count 히스토그램 commit, status 신뢰 소스에서 선언된 리소스를 클러스터에 적용할 때의 지연 시간 분포(지속 시간 무시)
config_sync_apply_duration_seconds_sum 히스토그램 commit, status 신뢰 소스에서 선언된 리소스를 클러스터에 적용할 때의 모든 지연 시간 합계
config_sync_apply_operations_total 카운터 operation, status, controller 신뢰 소스의 리소스를 클러스터에 동기화하기 위해 수행된 작업 수
config_sync_cluster_scoped_resource_count 게이지 resourcegroup ResourceGroup의 클러스터 범위 지정된 리소스 수
config_sync_crd_count 게이지 resourcegroup ResourceGroup의 CRD 수
config_sync_declared_resources 게이지 commit Git에서 파싱된 선언된 리소스 수
config_sync_internal_errors_total 카운터 source 구성 동기화로 트리거된 내부 오류 수 내부 오류가 발생하지 않으면 측정항목이 표시되지 않을 수 있습니다.
config_sync_kcc_resource_count 게이지 resourcegroup ResourceGroup의 Config Connector 리소스 수
config_sync_last_apply_timestamp 게이지 commit, status 최근 적용 작업의 타임스탬프입니다.
config_sync_last_sync_timestamp 게이지 commit, status Git에서의 최근 동기화의 타임스탬프
config_sync_parser_duration_seconds_bucket 히스토그램 status, trigger, source 정보 소스에서 클러스터로 동기화와 관련된 여러 단계의 지연 시간 분포
config_sync_parser_duration_seconds_count 히스토그램 status, trigger, source 정보 소스에서 클러스터로 동기화(지속 시간 무시)와 관련된 여러 단계의 지연 시간 분포
config_sync_parser_duration_seconds_sum 히스토그램 status, trigger, source 정보 소스에서 클러스터로의 동기화와 관련된 여러 단계의 지연 시간 합계
config_sync_pipeline_error_observed 게이지 name, reconciler, component RootSync 및 RepoSync 커스텀 리소스의 상태. 값 1은 실패를 나타냅니다.
config_sync_ready_resource_count 게이지 resourcegroup ResourceGroup의 준비된 총 리소스 수
config_sync_reconcile_duration_seconds_bucket 히스토그램 status 조정자 관리자가 처리한 조정 이벤트의 지연 시간 분포(각 호출 기간에 따라 버킷으로 분배)
config_sync_reconcile_duration_seconds_count 히스토그램 status 조정자 관리자가 처리한 조정 이벤트의 지연 시간 분포(지속 시간 무시)
config_sync_reconcile_duration_seconds_sum 히스토그램 status 조정자 관리자가 처리한 조정 이벤트의 모든 지연 시간 기간의 합계
config_sync_reconciler_errors 게이지 component, errorclass 신뢰 소스의 리소스를 클러스터에 동기화하는 동안 발생한 오류 수
config_sync_remediate_duration_seconds_bucket 히스토그램 status 교정자 조정 이벤트의 지연 시간 분포(기간별로 버킷으로 분배)
config_sync_remediate_duration_seconds_count 히스토그램 status 교정자 조정 이벤트의 지연 시간 분포(지속 시간 무시)
config_sync_remediate_duration_seconds_sum 히스토그램 status 교정자 조정 이벤트의 모든 지연 시간 기간의 합계
config_sync_resource_count 게이지 resourcegroup ResourceGroup으로 추적된 리소스 수
config_sync_resource_conflicts_total 카운터 commit 캐시된 리소스와 클러스터 리소스 사이의 불일치로부터 발생한 리소스 충돌 수. 리소스 충돌이 발생하지 않으면 측정항목이 표시되지 않을 수 있습니다.
config_sync_resource_fights_total 카운터 너무 자주 동기화되는 리소스 수 리소스 싸움이 발생하지 않은 경우 측정항목이 표시되지 않을 수 있음
config_sync_resource_group_total 게이지 ResourceGroup CR 수
config_sync_resource_ns_count 게이지 resourcegroup ResourceGroup의 리소스에 사용된 네임스페이스의 수
config_sync_rg_reconcile_duration_seconds_bucket 히스토그램 stallreason ResourceGroup CR 조정 시간 분포(기간별로 버킷으로 분산)
config_sync_rg_reconcile_duration_seconds_count 히스토그램 stallreason ResourceGroup CR 조정의 시간 분포(지속 시간 무시)
config_sync_rg_reconcile_duration_seconds_sum 히스토그램 stallreason ResourceGroup CR을 조정하는 모든 시간의 합계
config_sync_kustomize_build_latency_bucket 히스토그램 kustomize build 실행 시간의 지연 시간 분포(각 작업 기간에 따라 버킷으로 분배)
config_sync_kustomize_build_latency_count 히스토그램 kustomize build 실행 시간의 지연 시간 분포(지속 시간 무시)
config_sync_kustomize_build_latency_sum 히스토그램 모든 kustomize build 실행 시간의 합계
config_sync_kustomize_ordered_top_tier_metrics 게이지 top_tier_field 리소스, 생성기, SecretGenerator, ConfigMapGenerator, Transformer, 검사기 사용
config_sync_kustomize_builtin_transformers 게이지 k8s_builtin_transformer Kubernetes 객체 메타데이터와 관련된 기본 제공 변환기 사용
config_sync_kustomize_resource_count 게이지 kustomize build에 의해 출력되는 리소스 수
config_sync_kustomize_field_count 게이지 field_name Kustomization 파일에서 특정 필드가 사용된 횟수
config_sync_kustomize_patch_count 게이지 patch_field patches, patchesStrategicMerge, patchesJson6902 필드의 패치 수
config_sync_kustomize_base_count 게이지 base_source 원격 및 로컬 베이스 수
kustomize_deprecating_field_count 게이지 deprecating_field 지원 중단될 수 있는 필드 사용
kustomize_simplification_adoption_count 게이지 simplification_field 단순화 변환기 이미지, 복제본, 대체 사용
kustomize_helm_inflator_count 게이지 helm_inflator 기본 제공 필드 또는 커스텀 함수에 의한 kustomize에서 helm 사용

Prometheus 디버깅 절차 예시

다음 예시는 Prometheus 측정항목, 객체 상태 필드, 객체 주석을 사용하여 구성 동기화와 관련된 문제를 감지하고 진단하는 몇 가지 패턴을 보여줍니다. 이러한 예시는 문제를 발견한 상위 수준 모니터링에서 시작한 다음 점진적으로 상세 검색을 통해 문제의 근본 원인을 파악하는 방법을 보여줍니다.

상태별 구성 쿼리

reconciler 프로세스는 클러스터에서 구성 동기화가 작동하는 방식에 대한 전반적인 정보를 제공하는 높은 수준의 측정항목을 제공합니다. 오류가 발생했는지 여부를 알 수 있으며 경고를 설정할 수도 있습니다.

config_sync_reconciler_errors

조정자로 측정항목 쿼리

구성 동기화 RootSync 및 RepoSync API를 사용하는 경우 RootSync 및 RepoSync 객체를 모니터링할 수 있습니다. RootSync 및 RepoSync 객체는 구성 동기화가 클러스터에서 작동하는 방식에 대한 유용한 정보를 제공하는 상위 수준 측정항목으로 계측됩니다. 거의 모든 측정항목에 조정자 이름이 태그로 지정되므로 오류가 발생했는지 확인하고 이에 대한 알림을 Prometheus에서 설정할 수 있습니다.

필터링에 사용 가능한 측정항목 라벨의 전체 목록을 참조하세요.

Prometheus에서는 RootSyncs 또는 RepoSync에 대해 다음 필터를 사용할 수 있습니다.

# Querying RootSync
config_sync_reconciler_errors{configsync_sync_name=ROOT_SYNC_NAME}

# Querying RepoSync
config_sync_reconciler_errors{configsync_sync_name=REPO_SYNC_NAME}

상태별 가져오기 및 동기화 작업 쿼리

Prometheus에서 다음 쿼리를 사용할 수 있습니다.

# Check for errors that occurred when sourcing configs.
config_sync_reconciler_errors{component="source"}

# Check for errors that occurred when syncing configs to the cluster.
config_sync_reconciler_errors{component="sync"}

소스 및 동기화 프로세스 자체의 측정항목도 확인할 수 있습니다.

config_sync_parser_duration_seconds{status="error"}
config_sync_apply_duration_seconds{status="error"}
config_sync_remediate_duration_seconds{status="error"}

Google Cloud Managed Service for Prometheus로 리소스 모니터링

Google Cloud Managed Service for Prometheus는 Prometheus 측정항목을 위한 Google Cloud의 완전 관리형 멀티 클라우드 솔루션입니다. 관리형 수집(권장 모드) 또는 자체 배포형 데이터 수집의 두 가지 데이터 컬렉션 모드를 지원합니다. 관리형 수집 모드에서 Google Cloud Managed Service for Prometheus로 구성 동기화 모니터링을 설정하려면 다음 단계를 수행합니다.

  1. 관리형 수집 설정의 안내에 따라 클러스터에서 관리형 Prometheus를 사용 설정합니다.

  2. 다음 샘플 매니페스트를 pod-monitoring-config-sync-monitoring.yaml로 저장합니다. 이 매니페스트는 config-management-monitoring 네임스페이스 아래에서 otel-collector-* 포드의 포트 8675에 구성 동기화 측정항목을 스크래핑하도록 PodMonitoring 리소스를 구성합니다. PodMonitoring 리소스는 Kubernetes 라벨 선택기를 사용하여 otel-collector-* 포드를 찾습니다.

    apiVersion: monitoring.googleapis.com/v1
    kind: PodMonitoring
    metadata:
      name: config-sync-monitoring
      namespace: config-management-monitoring
    spec:
      selector:
        matchLabels:
          app: opentelemetry
          component: otel-collector
      endpoints:
      - port: 8675
        interval: 10s
    
  3. 클러스터에 매니페스트를 적용합니다.

    kubectl apply -f pod-monitoring-config-sync-monitoring.yaml
    

  4. Cloud Monitoring의 Managed Service for Prometheus 데이터의 안내에 따라 Google Cloud 콘솔에서 Cloud Monitoring 측정항목 탐색기 페이지를 사용하여 Prometheus 데이터가 노출되는지 확인합니다.