Escalonar pods automaticamente usando métricas personalizadas ou externas

Autopilot Standard

Neste documento, descrevemos como buscar e usar métricas personalizadas e externas para escalonar pods horizontalmente.

Para buscar as métricas, use um adaptador de métricas gerenciadas do GKE. Essa solução gerenciada está disponível para métricas no Cloud Monitoring que podem ser consultadas com PromQL e para algumas métricas personalizadas de pod expostas em um endpoint HTTP no formato do Prometheus.

O escalonador automático de carga de trabalho pode usar esses dados para escalonar as cargas de trabalho de maneira mais eficiente. Por exemplo, é possível usar esse recurso para monitorar a profundidade da fila ou a utilização do cache e, em seguida, permitir que o escalonador automático aumente ou diminua o número de pods. No exemplo do vLLM, uma métrica útil para rastrear a utilização do cache é vllm:gpu_cache_usage_perc.

Como alternativa ao adaptador de métricas gerenciadas, para fazer o escalonamento automático usando qualquer métrica, busque a métrica configurando manualmente um adaptador para enviar métricas a um escalonador automático. Esse fluxo de trabalho envolve a instalação de um adaptador de terceiros, como o Adaptador do Stackdriver, e a configuração de permissões. Por exemplo, consulte o tutorial Otimizar o escalonamento automático de pods com base em métricas.

O restante deste documento se concentra no adaptador de métricas gerenciadas.

Buscar métricas

É possível buscar métricas usando o adaptador de métricas gerenciadas das seguintes maneiras:

• As métricas personalizadas emitidas pelos pods podem ser buscadas no cluster. Essas métricas podem ser usadas para escalonamento automático sem precisar transitar por um sistema de monitoramento como o Cloud Monitoring.
• As métricas personalizadas de pods armazenadas no Cloud Monitoring podem ser buscadas usando uma consulta PromQL. Essas métricas são emitidas por pods e exportadas para o Cloud Monitoring, geralmente usando o Serviço Gerenciado do Google Cloud para Prometheus. Em comparação com o método anterior, essa abordagem permite usar recursos do PromQL, como calcular percentis ou ler valores históricos.
• As métricas externas podem ser buscadas do Cloud Monitoring usando uma consulta do PromQL.

Depois de buscar a métrica, faça referência a ela em um objeto HorizontalPodAutoscaler. Para mais informações, consulte a seção Usar as métricas no Autoescalonador Horizontal de Pods.

Para uma visão geral sobre o escalonamento automático com base em métricas, consulte Sobre o escalonamento automático de cargas de trabalho com base em métricas.

Buscar métricas personalizadas no cluster

As métricas personalizadas 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.

Requisitos

Os requisitos para os pods são os seguintes:

• GKE 1.37.0-gke.3100000 e mais recentes. Esse recurso também está disponível em pré-lançamento para as versões 1.36.4-gke.1247000 e posteriores do GKE.
• Use o escalonamento automático horizontal de pods com o perfil de desempenho.

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

• As métricas precisam ser emitidas por pods na carga de trabalho que está sendo escalonada automaticamente.
• 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.
• Por padrão, é possível expor no máximo 50 métricas exclusivas por nó. Se você precisar expor mais métricas, solicite mais memória adicional.
• Se você estiver usando a versão de pré-lançamento desse recurso, da versão 1.36.4-gke.1247000 à versão 1.37.0-gke.3100000 do GKE, os seguintes requisitos adicionais se aplicam:
  • Os nomes de rótulos nos seletores de rótulos de pods não podem conter caracteres especiais. São aceitas apenas letras de a a z (minúsculas ou maiúsculas), números, hifens e sublinhados.
  • 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.

Definir a métrica

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 expor 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_NAME
               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. Esse caminho geralmente é /metrics.
   • METRIC_NAME: 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. No entanto, o último caractere não pode ser um hífen.

   • Opcional: METRIC_PROMETHEUS_NAME: o nome da métrica do Prometheus, conforme exposto pelo pod. É possível usar 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 escalonador automático.

     Para mais informações sobre restrições de nomes, consulte as limitações do escalonamento automático horizontal de pods. Também é possível filtrar métricas usando rótulos de métricas.

3. Use o comando a seguir para aplicar o manifesto:

   kubectl apply -f FILE_NAME_AUTOSCALING_METRIC.yaml
   

   Substitua FILE_NAME_AUTOSCALING_METRIC pelo nome do arquivo YAML.

4. Verifique a definição da métrica e recupere o nome dela para usar no objeto HorizontalPodAutoscaler:

   1. Execute o comando kubectl describe para o recurso personalizado AutoscalingMetric:

      kubectl describe autoscalingmetric NAME -n NAMESPACE
      

      Substitua:

      • NAME: o nome do objeto AutoscalingMetric.
      • NAMESPACE: o namespace do objeto AutoscalingMetric.

   2. Confira o campo Status. Se nenhum erro for listado, o objeto será válido.

   3. Copie o nome no campo HPA Name. Esse é o nome que você adiciona ao objeto HorizontalPodAutoscaler. Esse nome tem o seguinte formato: autoscaling.gke.io|NAME|METRIC_NAME.

A métrica agora está definida no objeto AutoscalingMetric. Para fazer o escalonamento automático com essa métrica, é preciso referenciá-la em um objeto HorizontalPodAutoscaler. Para mais informações, consulte a seção Usar as métricas no objeto HorizontalPodAutoscaler.

Quando você adiciona o recurso personalizado, a métrica é enviada por push para a API de escalonamento automático. A métrica é lida a cada poucos segundos e enviada ao escalonador automático de carga de trabalho.

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 emitidas pelas cargas de trabalho geralmente incluem rótulos. 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.

Extrair métricas personalizadas ou externas do Cloud Monitoring

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

É possível buscar métricas do Cloud Monitoring para escalonar suas cargas de trabalho. O GKE aceita a busca de dois tipos de métricas do Cloud Monitoring:

• Métricas personalizadas: use esse tipo para aplicar recursos do PromQL, como calcular percentis ou ler valores históricos, às métricas emitidas pelas cargas de trabalho do cluster.
• Métricas externas: use esse tipo para escalonar com base em uma entidade fora do cluster, como o número de mensagens pendentes em uma assinatura do Pub/Sub.

Caso contrário, busque métricas personalizadas do cluster.

Requisitos

• GKE versão 1.36.2-gke.2771000 ou mais recente.
• As métricas precisam ser armazenadas no Cloud Monitoring. Por exemplo, é possível usar o Serviço Gerenciado do Google Cloud para Prometheus.
• No máximo 100 métricas são aceitas por cluster. Esse limite é o total combinado das métricas personalizadas e externas.
• As métricas no Cloud Monitoring precisam estar no mesmo projeto do Google Cloud que o cluster que está sendo escalonado automaticamente.

Definir a métrica

Você usa um arquivo YAML para definir as métricas, incluindo a consulta PromQL específica.

Observação: para conservar os recursos do cluster, o adaptador de métricas de escalonamento automático é executado com zero réplicas por padrão. Quando você aplica um objeto AutoscalingMetric que inclui uma consulta PromQL, o adaptador é escalonado para uma réplica.

Escolha uma das seguintes configurações, dependendo se você está buscando uma métrica personalizada ou uma métrica externa:

1. Crie um objeto AutoscalingMetric e defina a métrica a ser buscada.

   Métrica personalizada (pods)

   apiVersion: autoscaling.gke.io/v1beta1
   kind: AutoscalingMetric
   metadata:
     name: NAME
     namespace: NAMESPACE
   spec:
     metrics:
       - promql:
           name: METRIC_NAME
           query: PROMQL_QUERY
           type: Pods # Specifies that the metric is associated with Pods.
           # metricLabels are optional, default to the labels used by Google
           # Cloud Managed Service for Prometheus. The defaults are used
           # below.
           metricLabels:
             podName: "pod"
             namespace: "namespace"
             clusterName: "cluster"
             location: "location"
             projectId: "project_id"
   

   Substitua:

   • NAME: o nome do objeto AutoscalingMetric.
   • NAMESPACE: o namespace do objeto AutoscalingMetric, que precisa corresponder ao namespace da carga de trabalho que você quer escalonar.
   • METRIC_NAME: o nome da métrica usada pelo objeto HorizontalPodAutoscaler.
   • PROMQL_QUERY: a consulta PromQL que consulta a métrica. A consulta PromQL precisa retornar um vetor com uma entrada por pod no recurso escalonado automaticamente, por exemplo, uma entrada por pod em uma implantação.

   É possível definir mais de uma métrica em um único manifesto AutoscalingMetric adicionando outras entradas promql à matriz metrics.

   Nesse manifesto, o seguinte se aplica:

   • O campo type: Pods indica que as métricas são emitidas por pods.

   • Opcional: os campos metricLabels são os nomes dos rótulos no resultado da consulta PromQL que lista os detalhes do recurso, como o nome do pod, o namespace ou as informações do cluster. A métrica personalizada emitida por um pod precisa incluir um rótulo correspondente ao campo podName, especificando a qual pod a métrica está associada. Esse rótulo é configurado automaticamente quando você envia métricas para o Cloud Monitoring usando o Google Cloud Managed Service para Prometheus.

     Se esses campos não forem especificados no objeto AutoscalingMetric, os seguintes valores padrão serão usados para encontrar as informações no rótulo. Esses valores padrão são os mesmos nomes de rótulo configurados pelo Google Cloud Managed Service para Prometheus:

     • podName: "pod"
     • namespace: "namespace"
     • clusterName: "cluster"
     • location: "location"
     • projectId: "project_id"

   Métrica externa

   apiVersion: autoscaling.gke.io/v1beta1
   kind: AutoscalingMetric
   metadata:
     name: NAME
     namespace: NAMESPACE
   spec:
     metrics:
       - promql:
           name: METRIC_NAME
           query: PROMQL_QUERY
           type: External  # Optional, default is 'External'
   

   Substitua:

   • NAME: o nome do objeto AutoscalingMetric.
   • NAMESPACE: o namespace do objeto AutoscalingMetric, que precisa corresponder ao namespace da carga de trabalho que você quer escalonar.
   • METRIC_NAME: o nome da métrica usada pelo HPA.
   • PROMQL_QUERY: a consulta PromQL que consulta a métrica. A consulta do PromQL precisa retornar um valor escalar ou um vetor com uma entrada única.

   Observação: é possível definir mais de uma métrica em um único manifesto AutoscalingMetric adicionando mais entradas promql à matriz metrics.

2. Verifique as consultas do PromQL no Cloud Monitoring para garantir que elas retornem as métricas esperadas. É mais fácil verificar as consultas durante a configuração do que resolver problemas de comportamentos inesperados mais tarde.

   Para verificar as consultas, consulte a seção a seguir: Verificar consultas do PromQL.

3. Aplique o manifesto AutoscalingMetric ao cluster:

   kubectl apply -f MANIFEST_FILE.yaml
   

   Substitua MANIFEST_FILE pelo nome do arquivo YAML.

4. Verifique a definição da métrica e recupere o nome dela para usar no objeto HorizontalPodAutoscaler:

   1. Execute o comando kubectl describe para o recurso personalizado AutoscalingMetric:

      kubectl describe autoscalingmetric NAME -n NAMESPACE
      

      Substitua:

      • NAME: o nome do objeto AutoscalingMetric.
      • NAMESPACE: o namespace do objeto AutoscalingMetric.

   2. Confira o campo Status. Se nenhum erro for listado, o objeto será válido.

   3. Copie o nome no campo HPA Name. Esse é o nome que você adiciona ao objeto HorizontalPodAutoscaler. Esse nome tem o seguinte formato: autoscaling.gke.io|NAME|METRIC_NAME.

A métrica agora está definida no objeto AutoscalingMetric. Para fazer o escalonamento automático com essa métrica, é preciso referenciá-la em um objeto HorizontalPodAutoscaler. Para mais informações, consulte a seção Usar as métricas no objeto HorizontalPodAutoscaler.

Usar as métricas no objeto HorizontalPodAutoscaler

1. Crie um objeto HorizontalPodAutoscaler. O tipo de métrica HorizontalPodAutoscaler precisa corresponder ao valor do campo type definido no recurso personalizado AutoscalingMetric. Escolha uma das seguintes configurações, dependendo do tipo de métrica:

   Opção 1: métrica externa

   apiVersion: autoscaling/v2
   kind: HorizontalPodAutoscaler
   metadata:
     name: HPA_NAME
     namespace: NAMESPACE
   spec:
     scaleTargetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: DEPLOYMENT_NAME
     minReplicas: MIN_REPLICAS
     maxReplicas: MAX_REPLICAS
     metrics:
       - type: External
         external:
           metric:
             name: autoscaling.gke.io|NAME|METRIC_NAME
           target:
             type: AverageValue
             averageValue: AVERAGE_VALUE
   

   Opção 2: métrica de pods

   apiVersion: autoscaling/v2
   kind: HorizontalPodAutoscaler
   metadata:
     name: HPA_NAME
     namespace: NAMESPACE
   spec:
     scaleTargetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: DEPLOYMENT_NAME
     minReplicas: MIN_REPLICAS
     maxReplicas: MAX_REPLICAS
     metrics:
       - type: Pods
         pods:
           metric:
             name: autoscaling.gke.io|NAME|METRIC_NAME
           target:
             type: AverageValue  # This is the only supported target type
             averageValue: AVERAGE_VALUE
   

   Substitua:

   • HPA_NAME: o nome do objeto HorizontalPodAutoscaler.
   • NAMESPACE: o namespace do objeto HorizontalPodAutoscaler, que precisa corresponder ao namespace da carga de trabalho e do recurso AutoscalingMetric.
   • DEPLOYMENT_NAME: o nome da implantação de carga de trabalho que você quer escalonar.
   • MIN_REPLICAS: o número mínimo de pods em execução.
   • MAX_REPLICAS: o número máximo de pods em execução.
   • NAME: o nome do recurso personalizado AutoscalingMetric que você criou.
   • METRIC_NAME: o nome da métrica definida no recurso AutoscalingMetric.
   • AVERAGE_VALUE: o valor da métrica de destino em que o escalonador automático escalona a carga de trabalho.

   Ao criar seu próprio objeto HorizontalPodAutoscaler, observe o seguinte:

   • Os objetos AutoscalingMetric, Deployment e HorizontalPodAutoscaler precisam estar no mesmo namespace.
   • O exemplo anterior usa o par campo-valor type: AverageValue. O type: Value também é compatível com métricas externas.
   • O exemplo anterior usa um objeto de implantação apenas como exemplo. Também é possível fazer o escalonamento automático de qualquer objeto compatível com objetos HorizontalPodAutoscaler, como um objeto ReplicaSet.

2. Aplique o manifesto HorizontalPodAutoscaler:

   kubectl apply -f HPA_MANIFEST_FILE.yaml
   

   Substitua HPA_MANIFEST_FILE pelo nome do arquivo YAML.

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

Para resolver problemas com a busca de métricas, consulte os registros ou o status do recurso personalizado AutoscalingMetric.

O adaptador de métricas de escalonamento automático tem zero réplicas

Ao inspecionar a implantação do autoscaling-metrics-adapter em kube-system, você vai notar que ela tem zero réplicas.

Por padrão, o adaptador é executado sem réplicas para conservar os recursos do cluster. Esse é o comportamento esperado. A implantação só é escalonada para uma réplica quando um recurso personalizado AutoscalingMetric que exige o processamento de PromQL existe no cluster.

Se você configurou um objeto AutoscalingMetric com uma consulta PromQL, mas o adaptador não foi escalonado, verifique se o objeto foi criado corretamente no cluster.

Analisar os registros

Para encontrar problemas com o controlador responsável por receber métricas do Cloud Monitoring, revise os registros dele.

É possível conferir os registros no console do Google Cloud :

1. Acesse a página Análise de registros:

   Acessar a Análise de registros

2. No painel de consulta, digite a seguinte consulta:

   resource.type="k8s_container"
   resource.labels.namespace_name="kube-system"
   resource.labels.container_name="autoscaling-metrics-adapter"
   

Como alternativa, para conferir os registros usando kubectl, execute o seguinte comando:

kubectl logs deployment.apps/autoscaling-metrics-adapter -n kube-system

Analisar o status de AutoscalingMetric

Revise o status do recurso personalizado AutoscalingMetric para procurar erros de configuração.

1. Inspecione o recurso personalizado AutoscalingMetric:

   kubectl describe autoscalingmetric NAME -n NAMESPACE
   

   Substitua:

   • NAME: o nome do recurso personalizado AutoscalingMetric que você criou.
   • NAMESPACE: o namespace do recurso personalizado.

2. Para mais detalhes sobre as métricas configuradas, consulte o campo Status. Esses detalhes incluem avisos sobre erros de configuração e o nome exato da métrica, conforme ela aparece no objeto HorizontalPodAutoscaler.

   Confira um exemplo de status válido:

   Name:         sample-metric
   Namespace:    default
   Labels:       <none>
   Annotations:  <none>
   API Version:  autoscaling.gke.io/v1beta1
   Kind:         AutoscalingMetric
   Metadata:
     Creation Timestamp:  2026-08-10T14:41:58Z
     Generation:          1
     Resource Version:    1786372918604351020
     UID:                 c3f012a9-8f25-4399-ac91-12ae8f4426d7
   Spec:
     Metrics:
       Promql:
         Name:   pubsub_unacked
         Query:  sum(pubsub_subscription_num_undelivered_messages)
         Type:   External
   Status:
     Metric Statuses:
       Hpa Name:  autoscaling.gke.io|sample-metric|pubsub_unacked
       Name:      pubsub_unacked
   Events:        <none>
   

   Veja a seguir um exemplo de status com um erro de configuração:

   Name:         bad-metric
   Namespace:    default
   Labels:       <none>
   Annotations:  <none>
   API Version:  autoscaling.gke.io/v1beta1
   Kind:         AutoscalingMetric
   Metadata:
     Creation Timestamp:  2026-08-10T14:42:40Z
     Generation:          1
     Resource Version:    1786372960414079010
     UID:                 a47d3ed4-f6f2-4c2c-9341-0de4e9752c3c
   Spec:
     Metrics:
       Promql:
         Name:   duplicate_metric
         Query:  sum(up)
         Type:   External
       Promql:
         Name:   duplicate_metric
         Query:  avg(up)
         Type:   External
   Status:
     Metric Statuses:
       Errors:
         Multiple metrics defined with the same name.
       Name:  duplicate_metric
   Events:    <none>
   

Verificar consultas PromQL

Se você buscar métricas do Cloud Monitoring usando uma consulta PromQL, um problema com a consulta poderá causar erros na recuperação da métrica ou fazer com que um valor inesperado seja recuperado. Por exemplo, se você espera que uma porcentagem seja retornada como um valor de 1 a 100, mas recebe um valor de 0 a 1, o escalonamento automático resultante se comporta de maneira inesperada.

É possível testar as consultas do PromQL no Cloud Monitoring para verificar se elas retornam as métricas esperadas.

Para verificar as consultas, faça o seguinte:

1. No console do Google Cloud , acesse a página do Metrics Explorer.

   Acesse o Metrics explorer

2. Na parte de cima do painel Criador de consultas, selecione a guia PromQL.

3. No editor de consultas, insira a consulta PromQL que você quer testar.

4. Clique em Executar consulta para ver as métricas no gráfico.

A seguir

• Para uma visão geral sobre o escalonamento automático com base em métricas, consulte Sobre o escalonamento automático de cargas de trabalho com base em métricas.
• Para fazer o escalonamento automático usando métricas que não podem ser definidas com uma consulta do PromQL, consulte Otimizar o escalonamento automático de pods com base em métricas.