Expor métricas personalizadas para escalonamento automático

Este documento descreve como enviar uma ou mais métricas de um pod ou carga de trabalho para o escalonador automático.

Essas métricas vêm do serviço ou aplicativo que você está executando. Para um exemplo de métricas expostas, consulte as métricas expostas pelo vLLM Engine.

O autoescalador de carga de trabalho pode usar esses dados para escalonar as cargas de trabalho com mais eficiência. Por exemplo, é possível usar esse recurso para monitorar a profundidade da fila ou as solicitações ativas e permitir que o escalonador automático aumente ou diminua o número de pods. No exemplo do vLLM, uma métrica útil para acompanhar a utilização é vllm:gpu_cache_usage_perc.

Requisitos

Os requisitos para os pods são os seguintes:

Os requisitos para as métricas são os seguintes:

  • As métricas precisam estar acessíveis em um endpoint HTTP. O caminho do endpoint é /metrics por padrão.
  • As métricas precisam ser formatadas de acordo com o padrão do Prometheus.
  • Somente métricas de indicador são aceitas.
  • Os nomes de rótulos nos seletores de rótulos de pods não podem conter caracteres especiais. Somente letras de a a z (minúsculas ou maiúsculas), números, hífens e sublinhados são aceitos.
  • Ao usar a filtragem com base em rótulos de métricas, a chave do rótulo precisa corresponder à expressão regular ^[a-zA-Z_][a-zA-Z0-9_]* (começar com uma letra ou um sublinhado e conter apenas letras, números ou sublinhados).
  • É possível expor no máximo 20 métricas exclusivas por cluster.

Expor métricas para escalonamento automático

  1. Escolha uma métrica para expor. Você pode escolher qualquer métrica exposta pela sua carga de trabalho e que atenda aos requisitos listados na seção anterior.

    Se a carga de trabalho expuser várias métricas com o mesmo nome, mas rótulos diferentes, adicione um filtro de rótulo para garantir que apenas uma seja selecionada.

  2. Adicione o seguinte recurso personalizado, substituindo os detalhes específicos da sua métrica e do pod:

    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

    Substitua o seguinte para corresponder à sua carga de trabalho:

    • NAME: o nome do objeto "AutoscalingMetric".
    • NAMESPACE: o namespace em que os pods estão.
    • APP_LABEL_NAME e APP_LABEL_VALUE: o nome e o valor do rótulo correspondentes aos pods que emitem a métrica.
    • METRIC_PORT: o número da porta.
    • METRIC_PATH: o caminho para a métrica. Verifique o caminho usado pelo serviço ou aplicativo. Geralmente, esse caminho é /metrics.
    • METRIC: o nome da métrica que você está expondo. O nome precisa corresponder à expressão regular ^[a-z]([-a-z0-9]*[a-z0-9])? e ter no máximo 63 caracteres. Isso significa que o primeiro caractere precisa ser uma letra minúscula, e todos os seguintes precisam ser hifens, letras minúsculas ou dígitos, exceto o último, que não pode ser um hífen.

    • Opcional: METRIC_PROMETHEUS_NAME: o nome da métrica do Prometheus exposto pelo pod. Use esse campo para renomear a métrica, por exemplo, porque o nome exposto pelo pod não está de acordo com as restrições definidas pelo autoescalador.

      Para detalhes sobre restrições de nome, consulte limitações do escalonamento automático horizontal de pods.

  3. Aplique o manifesto usando o seguinte comando:

    kubectl apply -f FILE_NAME_AUTOSCALING_METRIC.yaml

    Substitua FILE_NAME_AUTOSCALING_METRIC pelo nome do arquivo YAML.

    Depois de adicionar o recurso personalizado, a métrica é enviada à API de escalonamento automático. A métrica é lida a cada poucos segundos e enviada ao escalonador automático de carga de trabalho.

  4. Agora que você expôs as métricas ao autoescalador, é possível configurar o autoescalador de carga de trabalho para usar essas métricas. Para fazer isso, adicione o seguinte recurso personalizado:

    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

    Substitua o seguinte para corresponder à sua carga de trabalho:

    • NAME_HPA: o nome do objeto HorizontalPodAutoscaler.
    • NAMESPACE: o namespace em que os pods estão.
    • DEPLOYMENT: o nome da implantação que você está segmentando.
    • MIN_REPLICAS: o número mínimo de réplicas que a implantação pode escalonar.
    • MAX_REPLICAS: o número máximo de réplicas que a implantação pode escalonar.
    • NAME: o nome do objeto "AutoscalingMetric".
    • METRIC: o nome da métrica que você está expondo.
    • AVERAGE_VALUE: o valor médio desejado para a métrica. O autoescalador ajusta o número de réplicas para manter um valor médio da métrica em todos os pods.

  5. Aplique o manifesto usando o seguinte comando:

    kubectl apply -f FILE_NAME_HPA.yaml

    Substitua FILE_NAME_HPA pelo nome do arquivo YAML.

Como filtrar métricas usando rótulos de métricas

A filtragem de métricas usando rótulos de métricas está disponível no GKE 1.36.0-gke.1759000 ou posterior.

As métricas geralmente incluem rótulos. Os rótulos são pares de chave-valor que permitem adicionar dimensões a um valor. Por exemplo, uma métrica que conta o número de solicitações para um endpoint HTTP segmentado por método e ambiente pode usar rótulos para especificar esse contexto. Este exemplo pode ter a seguinte aparência:

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

Use filtros de rótulo para garantir que sua especificação de métrica corresponda exatamente a uma métrica. Por exemplo, para selecionar apenas a primeira métrica no exemplo anterior, use a seguinte especificação para a métrica 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

As chaves dos pares de chave-valor matchLabels precisam corresponder à expressão regular ^[a-zA-Z_][a-zA-Z0-9_]*, ou seja, começar com uma letra ou um sublinhado e conter apenas letras, números ou sublinhados.

Resolver problemas de métricas expostas para escalonamento automático

Revise o status do recurso personalizado AutoscalingMetric para procurar erros de configuração. Para fazer isso, siga estas etapas:

  1. Inspecione o recurso personalizado AutoscalingMetric executando o seguinte comando:

    kubectl describe autoscalingmetric NAME -n NAMESPACE

  2. Consulte o campo Status para informações sobre métricas configuradas, como avisos sobre erros de configuração e o nome exato da métrica, conforme ela aparece no objeto HorizontalPodAutoscaler.

A seguir