Container Service for Kubernetes:Configure horizontal pod autoscaling with Prometheus metrics

Opção A: Usar métricas nativas do ACK

O Prometheus Service vem instalado por padrão no ACK e coleta diversas métricas, incluindo:

• Métricas de contêiner do cAdvisor

• Métricas de infraestrutura do Node Exporter

• Métricas do GPU Exporter

• Quaisquer métricas adicionais conectadas ao Prometheus Service

Para visualizar todas as métricas conectadas:

1. Faça logon no console do ACK. No painel de navegação à esquerda, clique em Clusters.

2. Na página Clusters, clique no nome do seu cluster. No painel de navegação à esquerda, escolha Operations > Prometheus Monitoring.

3. No canto superior direito, clique em Alert Settings . Se o link não aparecer, atualize o Managed Service for Prometheus para a versão mais recente. Consulte Prerequisites.

4. No console do Prometheus Service, clique em Settings no painel de navegação à esquerda para visualizar todas as métricas conectadas.

Opção B: Expor métricas personalizadas de um pod

Se sua aplicação expuser métricas no formato Prometheus, utilize um ServiceMonitor para coletá-las. Este exemplo implanta uma aplicação de amostra que expõe http_requests_total e configura a coleta.

Atualizar a configuração do adapter

1. Faça logon no console do ACK. No painel de navegação à esquerda, clique em Clusters.

2. Clique no nome do seu cluster. No painel de navegação à esquerda, clique em Applications > Helm.

3. Localize ack-alibaba-cloud-metrics-adapter e clique em Update na coluna Actions.

4. No painel Update Release, atualize o YAML com sua configuração e clique em OK.

   Detalhes do YAML

   AlibabaCloudMetricsAdapter:
   ......
     prometheus:
       enabled: true    # Enable the Prometheus adapter.
       # Prometheus Service data request URL. See "Get the Prometheus data request URL" below.
       url: https://cn-beijing.arms.aliyuncs.com:9443/api/v1/prometheus/xxxx/xxxx/xxxx/cn-beijing
       # Prometheus V1 with token authentication enabled:
       prometheusHeader:
       - Authorization: {Token}
       # Prometheus V2 without password-free access (uncomment and replace the V1 block above):
       # prometheusHeader:
       # - Authorization: Basic <base64Encode(<accessKey:secretKey>)>
       metricsRelistInterval: 1m  # Interval for refreshing the metric list. Keep the default.
       logLevel: 5                # Debug log level. Keep the default.
       adapter:
         rules:
           default: false  # Do not expose predefined metrics by default.
           custom:
           # Example: convert container_memory_working_set_bytes to container_memory_working_set_bytes_per_second
           - seriesQuery: 'container_memory_working_set_bytes{namespace!="",pod!=""}'
             resources:
               overrides:
                 namespace: { resource: "namespace" }
                 pod: { resource: "pod" }
             name:
               matches: "^(.*)_bytes"
               as: "${1}_bytes_per_second"
             metricsQuery: 'sum(<<.Series>>{<<.LabelMatchers>>}) by (<<.GroupBy>>)'
           # Example: convert container_cpu_usage_seconds_total to container_cpu_usage_core_per_second
           - seriesQuery: 'container_cpu_usage_seconds_total{namespace!="",pod!=""}'
             resources:
               overrides:
                 namespace: { resource: "namespace" }
                 pod: { resource: "pod" }
             name:
               matches: "^(.*)_seconds_total"
               as: "${1}_core_per_second"
             metricsQuery: 'sum(rate(<<.Series>>{<<.LabelMatchers>>}[1m])) by (<<.GroupBy>>)'
           # Example: convert http_requests_total to http_requests_per_second
           - seriesQuery: 'http_requests_total{namespace!="",pod!=""}'
             resources:
               overrides:
                 namespace: {resource: "namespace"}
                 pod: {resource: "pod"}
             name:
               matches: "^(.*)_total"
               as: "${1}_per_second"
             metricsQuery: 'sum(rate(<<.Series>>{<<.LabelMatchers>>}[2m])) by (<<.GroupBy>>)'
   ......

A tabela a seguir lista os principais campos do adapter. Para a referência completa, consulte Adapter configuration reference.

Verificar se o adapter está funcionando

Execute estes comandos para confirmar se o adapter está expondo métricas por meio da API de agregação do Kubernetes.

Verificar Custom Metrics:

# List all available Custom Metrics
kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/" | jq .

# Query container_memory_working_set_bytes_per_second for pods in kube-system
kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/namespaces/kube-system/pods/*/container_memory_working_set_bytes_per_second" | jq .

# Query container_cpu_usage_core_per_second for pods in kube-system
kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/namespaces/kube-system/pods/*/container_cpu_usage_core_per_second" | jq .

Uma resposta bem-sucedida será semelhante a:

{
  "kind": "MetricValueList",
  "apiVersion": "custom.metrics.k8s.io/v1beta1",
  "metadata": {
    "selfLink": "/apis/custom.metrics.k8s.io/v1beta1/namespaces/kube-system/pods/%2A/container_cpu_usage_core_per_second"
  },
  "items": [
    {
      "describedObject": {
        "kind": "Pod",
        "namespace": "kube-system",
        "name": "ack-cost-exporter-7f44d55c66-cgtz7",
        "apiVersion": "/v1"
      },
      "metricName": "container_cpu_usage_core_per_second",
      "timestamp": "2025-12-30T03:30:21Z",
      "value": "4m",
      "selector": null
    }
  ]
}

Essa resposta confirma que o adapter descobriu e associou a métrica ao pod correto. O array items lista uma entrada por pod. O campo value utiliza o sufixo m (miliunidades), portanto 4m significa 0,004 núcleos de CPU por segundo.

Verificar External Metrics:

# List all available External Metrics
kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/" | jq .

# Query http_requests_per_second in the default namespace
kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/default/http_requests_per_second" | jq .

Uma resposta bem-sucedida será semelhante a:

{
  "kind": "ExternalMetricValueList",
  "apiVersion": "external.metrics.k8s.io/v1beta1",
  "metadata": {},
  "items": [
    {
      "metricName": "http_requests_per_second",
      "metricLabels": {},
      "timestamp": "2025-12-30T03:29:40Z",
      "value": "328m"
    }
  ]
}

Diferentemente das Custom Metrics, a resposta de External Metrics contém um único valor agregado (não por pod), pois a métrica não está vinculada a um objeto específico do Kubernetes.

Variáveis de modelo em metricsQuery

O campo metricsQuery é um modelo Go, não PromQL simples. O adapter o preenche com valores da requisição do HPA antes de consultar o Prometheus. Os delimitadores são << e >> (e não {{ e }}) para evitar conflitos com a sintaxe PromQL.

Descoberta

seriesQuery especifica qual métrica do Prometheus converter e aceita qualquer seletor PromQL válido, incluindo filtros de rótulo.

- seriesQuery: 'http_requests_total{namespace!="",pod!=""}'

Os filtros de rótulo namespace!="" e pod!="" restringem a métrica a pods que possuem ambos os rótulos definidos, requisito necessário para a associação de recursos na próxima etapa.

Para refinar as séries correspondentes, adicione um bloco seriesFilters:

- seriesQuery: 'http_requests_total{namespace!="",pod!=""}'
  seriesFilters:
    - isNot: "^container_.*_seconds_total"

seriesFilters aceita dois operadores:

• is:<regex>: mantém apenas as séries cujo nome corresponde à expressão regular.

• isNot:<regex>: exclui as séries cujo nome corresponde à expressão regular.

Associação

resources.overrides mapeia nomes de rótulos do Prometheus para recursos da API do Kubernetes. Isso indica ao adapter qual rótulo corresponder quando o HPA solicitar uma métrica para um pod ou namespace específico.

- seriesQuery: 'http_requests_total{namespace!="",pod!=""}'
  resources:
    overrides:
      namespace: {resource: "namespace"}
      pod: {resource: "pod"}

As chaves (namespace, pod) são os nomes dos rótulos do Prometheus. Os valores ("namespace", "pod") são tipos de recursos da API do Kubernetes, conforme listado por kubectl api-resources -o wide. Cada chave deve existir como um rótulo nos seus dados do Prometheus.

Nomenclatura

name converte o nome da métrica do Prometheus no nome da métrica do HPA usando uma expressão regular. O nome original da métrica do Prometheus permanece inalterado.

- seriesQuery: 'http_requests_total{namespace!="",pod!=""}'
  resources:
    overrides:
      namespace: {resource: "namespace"}
      pod: {resource: "pod"}
  name:
    matches: "^(.*)_total"
    as: "${1}_per_second"

matches é uma expressão regular que captura parte do nome da métrica do Prometheus. as define o nome da métrica do HPA, usando ${1} para referenciar o primeiro grupo de captura. Neste caso, http_requests_total torna-se http_requests_per_second.

Para External Metrics, converta letras maiúsculas no nome da métrica do Prometheus para minúsculas no nome da métrica do HPA.

Para listar todos os nomes de métricas do HPA disponíveis:

kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1"

Consulta

metricsQuery define a expressão PromQL que o adapter envia ao Prometheus após substituir as variáveis de modelo.

- seriesQuery: 'http_requests_total{namespace!="",pod!=""}'
  resources:
    overrides:
      namespace: {resource: "namespace"}
      pod: {resource: "pod"}
  name:
    matches: "^(.*)_total"
    as: "${1}_per_second"
  metricsQuery: 'sum(rate(<<.Series>>{<<.LabelMatchers>>}[2m])) by (<<.GroupBy>>)'

Os seletores de rótulo em metricsQuery são injetados via <<.LabelMatchers>> no momento da consulta e não herdam filtros de seriesQuery .

Prometheus Service da Alibaba Cloud

1. Faça logon no console do ACK. No painel de navegação à esquerda, clique em Clusters.

2. Clique no nome do seu cluster. No painel de navegação à esquerda, escolha Operations > Prometheus Monitoring.

3. No canto superior direito, clique em Alert Settings . Se o link não aparecer, atualize o ack-arms-prometheus para a versão mais recente. Consulte Prerequisites.

4. No console do Prometheus Service, clique em Settings > Settings para localizar o HTTP API Address (Grafana Read URL) . Utilize o endereço de Internal Network quando disponível; caso contrário, use o endereço de Internet.

   

5. Configure a autenticação para sua versão do Prometheus.

   • Prometheus V1 (autenticação por token desativada por padrão): se ativada, copie o token do console do Prometheus e configure o adapter.

     

     prometheus:
       prometheusHeader:
       - Authorization: {Token}

   • Prometheus V2 (autenticação por AccessKey ativada por padrão): se o acesso livre de senha não estiver ativado, codifique seu AccessKey ID e AccessKey secret em Base64.

     1. Gere uma string codificada em Base64.

        Concatene seu AccessKey ID e AccessKey secret como AccessKey:AccessSecret e codifique em Base64:

        echo -n 'accessKey:secretKey' | base64

     2. Configure o componente.

        Insira a string gerada no formato Basic <encoded string> no campo Authorization de prometheusHeader.

        ...
            prometheus:
              prometheusHeader:
              - Authorization: Basic YWxxxxeQ==
        ...

Prometheus open source

Para Prometheus autogerenciado, exponha sua API por meio de um Service do Kubernetes e defina a URL do Service na configuração do adapter.

Este exemplo utiliza o chart Helm ack-prometheus-operator do ACK Marketplace. Consulte Open source Prometheus monitoring.

1. Implante o ack-prometheus-operator.

   1. Faça logon no console do ACK. No painel de navegação à esquerda, escolha Marketplace > Marketplace.

   2. Pesquise por ack-prometheus-operator, clique no cartão correspondente e depois em Deploy.

   3. Selecione o Cluster e o Namespace, defina o Release Name e clique em Next. Ajuste os Parameters conforme necessário e clique em OK.

2. Verifique a implantação.

   1. Exponha a API do Prometheus por meio de um Service. Este exemplo usa o Service ack-prometheus-operator-prometheus.

   2. Em um navegador, acesse ServiceIP:9090. Para acesso público, exponha o Service por meio de uma instância do SLB.

   3. No console do Prometheus, clique em Status > Targets para visualizar todos os jobs de coleta. Se todos os jobs exibirem um State como UP, a coleta está funcionando corretamente.

   4. Anote o nome do Service e o namespace na coluna Labels. Neste exemplo, o Service é ack-prometheus-operator-prometheus no namespace monitoring.

3. Defina a URL do Prometheus no adapter. Para acesso interno:

   AlibabaCloudMetricsAdapter:
     prometheus:
       enabled: true
       url: http://ack-prometheus-operator-prometheus.monitoring.svc.cluster.local:9090

   Para acesso público:

   AlibabaCloudMetricsAdapter:
     prometheus:
       enabled: true
       url: http://your_domain.com:9090   # Replace with your public IP address or domain.

Para adicionar uma fonte de dados do Prometheus, consulte Add a Prometheus data source in Grafana.