Escalonar pods automaticamente usando métricas personalizadas ou externas

Este documento descreve como buscar e usar métricas personalizadas e externas para escalonar pods horizontalmente.

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

Como alternativa, para escalonar automaticamente usando qualquer métrica, é possível buscá-la configurando manualmente um adaptador de métricas 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 de métricas personalizadas, e a configuração de permissões. Por exemplo, consulte o tutorial Otimizar o escalonamento automático de pods com base em métricas.

Buscar métricas

É possível buscar métricas das seguintes maneiras:

• As métricas personalizadas emitidas por 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 de pod 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, normalmente 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 no Cloud Monitoring usando uma consulta PromQL.
• As métricas podem ser buscadas configurando manualmente um adaptador de métricas para enviar métricas a um escalonador automático. Esse fluxo de trabalho envolve a instalação de ferramentas de terceiros e a configuração de permissões. Por exemplo, consulte o tutorial Otimizar o escalonamento automático de pods com base em métricas.

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 escalonador automático 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 mecanismo vLLM.

Requisitos

Os requisitos para os pods são os seguintes:

• GKE 1.35.1-gke.1396000 ou mais recente com clusters no canal rápido.
• 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 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 medidor são aceitas.
• Os nomes de rótulos nos seletores de rótulos de pod não podem conter caracteres especiais. Somente letras de a a z (minúsculas ou maiúsculas), números, hifens 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.

Definir a métrica

1. Escolha uma métrica para expor. É possível escolher qualquer métrica que sua carga de trabalho exponha e que também 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 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 que correspondem 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 um comprimento de no máximo 63 caracteres. Essa expressão 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 exposto pelo pod. É possível usar esse campo para renomear a métrica, por exemplo, porque o nome da métrica exposto pelo pod não está em conformidade com as restrições de nome definidas pelo escalonador automático.

     Para mais informações sobre restrições de nome, consulte as 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.

4. Verifique a definição da métrica e recupere o nome da métrica a ser usada para o 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. Consulte 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 escalonar automaticamente com essa métrica, é necessário fazer referência a ela em um objeto HorizontalPodAutoscaler. Para mais informações, consulte a seção Usar as métricas no objeto HorizontalPodAutoscaler.

Ao 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 da carga de trabalho.

Buscar métricas personalizadas ou externas no Cloud Monitoring

É possível buscar métricas do Cloud Monitoring para escalonar as cargas de trabalho. O GKE oferece suporte à 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 subscription.

Caso contrário, busque métricas personalizadas no 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.
• Um máximo de 100 métricas é aceito por cluster. Esse limite é o total combinado de métricas personalizadas e externas.
• As métricas no Cloud Monitoring precisam estar no mesmo Cloud de Confiance by S3NS projeto que o cluster que está sendo escalonado automaticamente.

Definir a métrica

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

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.

   Neste 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 de rótulos no resultado da consulta PromQL que listam 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 que corresponda 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ótulos 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 PromQL precisa retornar um valor escalar ou um vetor com uma entrada exclusiva.

2. Verifique as consultas PromQL no Cloud Monitoring para garantir que elas retornem as métricas esperadas. É mais fácil verificar as consultas à medida que você as configura do que solucionar problemas de comportamentos inesperados mais tarde.

   Para verificar as consultas, consulte a seção a seguir: Verificar consultas 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 da métrica a ser usada para o 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. Consulte 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 escalonar automaticamente com essa métrica, é necessário fazer referência a ela 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 da 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 de valor de campo type: AverageValue. O type: Value também é aceito para métricas externas.
   • O exemplo anterior usa um objeto de implantação apenas como exemplo. Também é possível escalonar automaticamente qualquer objeto aceito por 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, analise 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 autoscaling-metrics-adapter em kube-system, você pode notar que ela tem zero réplicas.

Por padrão, o adaptador é executado com zero réplicas para conservar os recursos do cluster. Este é o comportamento esperado. A implantação só é escalonada para uma réplica quando um recurso personalizado AutoscalingMetric que exige o processamento do 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, analise os registros.

É possível conferir os registros no Cloud de Confiance console:

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 do AutoscalingMetric

É possível analisar 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 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>
   

   Confira 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 PromQL no Cloud Monitoring para verificar se elas retornam as métricas esperadas.

Para verificar as consultas, faça o seguinte:

1. No Cloud de Confiance console, acesse a página 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 conferir 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 escalonar automaticamente usando métricas que não podem ser definidas com uma consulta PromQL, consulte Otimizar o escalonamento automático de pods com base em métricas.