자동 확장을 위한 맞춤 측정항목 노출

이 문서에서는 포드 또는 워크로드에서 자동 확장 처리로 하나 이상의 측정항목을 전송하는 방법을 설명합니다.

이러한 측정항목은 실행 중인 서비스 또는 애플리케이션에서 가져옵니다. 노출된 측정항목의 한 가지 예는 vLLM 엔진에서 노출하는 측정항목을 참조하세요.

그러면 워크로드 자동 확장 처리에서 이 데이터를 사용하여 워크로드를 더 효율적으로 확장할 수 있습니다. 예를 들어 이 기능을 사용하여 대기열 깊이 또는 활성 요청을 모니터링한 후 자동 확장 처리에서 포드 수를 늘리거나 줄일 수 있습니다. vLLM 예시에서 사용률을 추적하는 데 유용한 측정항목은 vllm:gpu_cache_usage_perc입니다.

요구사항

포드의 요구사항은 다음과 같습니다.

측정항목의 요구사항은 다음과 같습니다.

  • 측정항목은 HTTP 엔드포인트에서 액세스할 수 있어야 합니다. 엔드포인트 경로는 기본적으로 /metrics입니다.
  • 측정항목은 Prometheus 표준에 따라 형식이 지정되어야 합니다.
  • 게이지 측정항목만 지원됩니다.
  • 포드 라벨 선택기의 라벨 이름에는 특수문자가 포함되어서는 안 됩니다. a~z 문자 (소문자 또는 대문자), 숫자, 하이픈, 밑줄만 지원됩니다.
  • 측정항목 라벨을 기반으로 필터링을 사용하는 경우 라벨 키는 정규 표현식 ^[a-zA-Z_][a-zA-Z0-9_]*과 일치해야 합니다 (문자 또는 밑줄로 시작하고 문자, 숫자 또는 밑줄만 포함).
  • 클러스터당 최대 20개의 고유한 측정항목을 노출할 수 있습니다.

자동 확장을 위한 측정항목 노출

  1. 노출할 측정항목을 선택합니다. 워크로드에서 노출하고 이전 섹션에 나열된 요구사항을 충족하는 측정항목을 선택할 수 있습니다.

    워크로드에서 이름은 같지만 라벨이 다른 여러 측정항목을 노출하는 경우 라벨 필터를 추가하여 측정항목이 하나만 선택되도록 합니다.

  2. 측정항목 및 포드와 관련된 세부정보를 바꿔 다음 커스텀 리소스를 추가합니다.

    apiVersion: autoscaling.gke.io/v1beta1
kind: AutoscalingMetric
metadata:
  name: NAME
  namespace: NAMESPACE
spec:
  metrics:
  - pod:
      selector:
        matchLabels:
          APP_LABEL_NAME: APP_LABEL_VALUE
      containers:
      - endpoint:
          port: METRIC_PORT
          path: METRIC_PATH
        metrics:
        - gauge:
            name: METRIC
            prometheusMetricName: METRIC_PROMETHEUS_NAME

    워크로드와 일치하도록 다음을 바꿉니다.

    • NAME: AutoscalingMetric 객체의 이름입니다.
    • NAMESPACE: 포드가 있는 네임스페이스입니다.
    • APP_LABEL_NAME 및 APP_LABEL_VALUE: 측정항목을 내보내는 포드와 일치하는 라벨 이름 및 값입니다.
    • METRIC_PORT: 포트 번호입니다.
    • METRIC_PATH: 측정항목의 경로입니다. 서비스 또는 애플리케이션에서 사용하는 경로를 확인합니다. 이 경로는 보통 /metrics입니다.
    • METRIC: 노출하는 측정항목의 이름입니다. 이름은 정규 표현식 ^[a-z]([-a-z0-9]*[a-z0-9])?과 일치해야 하며 길이는 63자(영문 기준) 이하여야 합니다. 즉, 첫 번째 문자는 소문자여야 하며 마지막 문자를 제외한 모든 후속 문자는 하이픈, 소문자 또는 숫자여야 합니다. 마지막 문자는 하이픈일 수 없습니다.

    • 선택사항: METRIC_PROMETHEUS_NAME: 포드에서 노출하는 Prometheus 측정항목 이름입니다. 예를 들어 포드에서 노출하는 측정항목 이름이 자동 확장 처리에서 설정한 이름 제한을 준수하지 않는 경우 이 필드를 사용하여 측정항목 이름을 바꿀 수 있습니다.

      이름 제한에 대한 자세한 내용은 수평형 포드 자동 확장 제한을 참조하세요.

  3. 다음 명령어를 사용하여 매니페스트를 적용합니다.

    kubectl apply -f FILE_NAME_AUTOSCALING_METRIC.yaml

    FILE_NAME_AUTOSCALING_METRIC을 YAML 파일 이름으로 바꿉니다.

    커스텀 리소스를 추가하면 측정항목이 자동 확장 API로 푸시됩니다. 측정항목은 몇 초마다 읽고 워크로드 자동 확장 처리로 전송됩니다.

  4. 이제 자동 확장 처리에 측정항목을 노출했으므로 이러한 측정항목을 사용하도록 워크로드 자동 확장 처리를 구성할 수 있습니다. 이렇게 하려면 다음 커스텀 리소스를 추가합니다.

    apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: NAME_HPA
  namespace: NAMESPACE
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: DEPLOYMENT
  minReplicas: MIN_REPLICAS
  maxReplicas: MAX_REPLICAS
  metrics:
    - type: Pods
      pods:
        metric:
          name: autoscaling.gke.io|NAME|METRIC
        target:
          type: AverageValue
          averageValue: AVERAGE_VALUE

    워크로드와 일치하도록 다음을 바꿉니다.

    • NAME_HPA: HorizontalPodAutoscaler 객체의 이름입니다.
    • NAMESPACE: 포드가 있는 네임스페이스입니다.
    • DEPLOYMENT: 타겟팅하는 배포의 이름입니다.
    • MIN_REPLICAS: 배포가 확장할 수 있는 최소 복제본 수입니다.
    • MAX_REPLICAS: 배포가 확장할 수 있는 최대 복제본 수입니다.
    • NAME: AutoscalingMetric 객체의 이름입니다.
    • METRIC: 노출하는 측정항목의 이름입니다.
    • AVERAGE_VALUE: 측정항목의 평균 목표 값입니다. 자동 확장 처리에서는 모든 포드에서 평균 측정항목 값을 유지하도록 복제본 수를 조정합니다.

  5. 다음 명령어를 사용하여 매니페스트를 적용합니다.

    kubectl apply -f FILE_NAME_HPA.yaml

    FILE_NAME_HPA를 YAML 파일 이름으로 바꿉니다.

측정항목 라벨을 사용하여 측정항목 필터링

측정항목 라벨을 사용하여 측정항목을 필터링하는 기능은 GKE 1.36.0-gke.1759000 이상에서 사용할 수 있습니다.

측정항목에는 라벨이 포함되는 경우가 많습니다. 라벨은 값에 측정기준을 추가할 수 있는 키-값 쌍입니다. 예를 들어 메서드 및 환경별로 분할된 HTTP 엔드포인트에 대한 요청 수를 계산하는 측정항목은 라벨을 사용하여 이 컨텍스트를 지정할 수 있습니다. 이 예시는 다음과 같을 수 있습니다.

http_requests_total{method="GET", env="prod"} 11111
http_requests_total{method="PUT", env="staging"} 22222

라벨 필터를 사용하면 측정항목 사양이 하나의 측정항목과 정확히 일치하도록 할 수 있습니다. 예를 들어 이전 예시에서 첫 번째 측정항목만 선택하려면 AutoscalingMetric gauge 측정항목에 다음 사양을 사용합니다.

apiVersion: autoscaling.gke.io/v1beta1
kind: AutoscalingMetric
metadata:
  name: filter-sample
spec:
  # Several lines are omitted here.
      metrics:
      - gauge:
          name: http_requests_total
          filter:
            matchLabels:
              method: GET
              env: prod

matchLabels 키-값 쌍의 키는 정규 표현식 ^[a-zA-Z_][a-zA-Z0-9_]*과 일치해야 합니다. 즉, 문자 또는 밑줄로 시작하고 문자, 숫자 또는 밑줄만 포함해야 합니다.

자동 확장을 위해 노출된 측정항목 문제 해결

AutoscalingMetric 커스텀 리소스의 상태를 검토하여 구성 오류를 찾을 수 있습니다. 방법은 다음과 같습니다.

  1. 다음 명령어를 실행하여 AutoscalingMetric 커스텀 리소스를 검사합니다.

    kubectl describe autoscalingmetric NAME -n NAMESPACE

  2. Status 필드에서 구성 오류에 대한 경고, HorizontalPodAutoscaler 객체에 표시되어야 하는 측정항목의 정확한 이름과 같은 구성된 측정항목에 대한 정보를 확인합니다.

다음 단계