Configurar o escalonamento automático vertical de pods

Pré-lançamento

Este produto ou 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 produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

O escalonamento automático vertical de pods automatiza a definição de solicitações e limites de recursos de CPU e memória para contêineres em pods do Kubernetes. O escalonamento automático vertical de pods analisa o uso de recursos histórico e atual para fornecer recomendações, que podem ser exibidas ou aplicadas automaticamente com a atualização dos pods. Esse recurso melhora a estabilidade e a eficiência de custos ao dimensionar corretamente as alocações de recursos.

Antes de começar

Antes de configurar o escalonamento automático vertical de pods, verifique se você atende aos seguintes pré-requisitos:

• Você tem um cluster bare metal em execução.
• Você tem acesso de kubectl ao cluster.
• O Metrics Server está disponível no cluster. Os clusters bare metal incluem o Metrics Server por padrão.

Ativar o Escalonamento automático vertical de pods

Ative o escalonamento automático vertical de pods no cluster bare metal definindo uma anotação de prévia e configurando a especificação do cluster:

1. Adicione ou atualize a anotação de prévia no recurso personalizado do cluster.

   Edite o recurso personalizado do cluster diretamente ou modifique o arquivo de configuração do cluster e use bmctl update.

   metadata:
     annotations:
       preview.baremetal.cluster.gke.io/vertical-pod-autoscaler: enable
   

2. Modifique o spec do recurso personalizado do cluster para incluir o campo verticalPodAutoscaling e especifique os modos enableUpdater e enableMemorySaver:

   apiVersion: baremetal.cluster.gke.io/v1
   kind: Cluster
   metadata:
     name: cluster1
     namespace: cluster-cluster1
     annotations:
       preview.baremetal.cluster.gke.io/vertical-pod-autoscaler: enable
   spec:
     # ... other cluster spec fields
     verticalPodAutoscaling:
       enableUpdater: true       # Set to true for automated updates
       enableMemorySaver: true   # Set to true to reduce recommender memory usage
   

3. Se você modificou o arquivo de configuração do cluster, aplique as mudanças usando o seguinte comando:

   bmctl update cluster -c CLUSTER_NAME --kubeconfig KUBECONFIG
   

   Substitua:

   • CLUSTER_NAME: o nome do cluster.

   • KUBECONFIG: o caminho do arquivo kubeconfig do cluster.

Criar um recurso personalizado VerticalPodAutoscaler

Depois de ativar o escalonamento automático vertical de pods no cluster, defina um recurso personalizado VerticalPodAutoscaler para segmentar cargas de trabalho específicas:

1. Defina um recurso VerticalPodAutoscaler no mesmo namespace que a carga de trabalho de destino.

   Esse recurso personalizado especifica quais pods ele segmenta usando targetRef e todas as políticas de recursos.

   apiVersion: "autoscaling.k8s.io/v1"
   kind: VerticalPodAutoscaler
   metadata:
     name: hamster-vpa
   spec:
     targetRef:
       apiVersion: "apps/v1"
       kind: Deployment
       name: hamster
     resourcePolicy:
       containerPolicies:
         -   containerName: '*'
           minAllowed:
             cpu: 100m
             memory: 50Mi
           maxAllowed:
             cpu: 1
             memory: 500Mi
           controlledResources: ["cpu", "memory"]
   

2. Aplique o manifesto VerticalPodAutoscaler usando o seguinte comando:

   kubectl apply -f VPA_MANIFEST \
       --kubeconfig KUBECONFIG
   

   Substitua:

   • VPA_MANIFEST: o caminho do arquivo de manifesto VerticalPodAutoscaler.

   • KUBECONFIG: o caminho do arquivo kubeconfig do cluster.

Entender os modos de escalonamento automático vertical de pods

O escalonamento automático vertical de pods opera em diferentes modos que controlam como ele aplica recomendações de recursos.

Modo de recomendação

No modo de recomendação, o escalonamento automático vertical de pods instala o componente de recomendação. Esse componente analisa o uso de recursos e publica valores recomendados para solicitações e limites de CPU e memória na seção de status dos recursos personalizados VerticalPodAutoscaler que você cria.

Para conferir recomendações de solicitações e limites de recursos, use o seguinte comando:

kubectl describe vpa VPA_NAME \
    --kubeconfig KUBECONFIG \
    -n CLUSTER_NAMESPACE

Replace the following:

*   `VPA_NAME`: the name of the `VerticalPodAutoscaler`
    that's targeting the workloads for which you are considering resource
    adjustments.

*   `KUBECONFIG`: the path of the cluster kubeconfig
    file.

*   `CLUSTER_NAMESPACE`: the name of the cluster that's
    running vertical Pod autoscaling.

A resposta precisa conter uma seção Status semelhante a este exemplo:

Status:
  Conditions:
    Last Transition Time:  2025-08-04T23:53:32Z
    Status:                True
    Type:                  RecommendationProvided
  Recommendation:
    Container Recommendations:
      Container Name:  hamster
      Lower Bound:
        Cpu:     100m
        Memory:  262144k
      Target:
        Cpu:     587m
        Memory:  262144k
      Uncapped Target:
        Cpu:     587m
        Memory:  262144k
      Upper Bound:
        Cpu:     1
        Memory:  500Mi

Os pods não são atualizados automaticamente nesse modo. Use estas recomendações para atualizar manualmente as configurações do pod. Esse é o comportamento padrão se enableUpdater não estiver definido ou for false.

Modo de atualização automática

Quando você define enableUpdater enableUpdater como true, os controladores de ciclo de vida do bare metal implantam os componentes de atualização e controlador de admissão do escalonamento automático vertical de pods, além do recomendador. O updater monitora pods cujas solicitações de recursos atuais divergem significativamente das recomendações.

A política de atualização no recurso VerticalPodAutoscaler especifica como o updater aplica as recomendações. Por padrão, o modo de atualização é Auto, que determina que o atualizador atribua configurações de recursos atualizadas na criação do pod. A seguinte amostra de VerticalPodAutoscaler mostra como definir o modo de atualização como Initial:

apiVersion: "autoscaling.k8s.io/v1"
kind: VerticalPodAutoscaler
metadata:
  name: hamster-vpa
spec:
  targetRef:
    apiVersion: "apps/v1"
    kind: Deployment
    name: hamster
  resourcePolicy:
  updatePolicy:
    updateMode: "Initial"
    ...

O atualizador é compatível com os seguintes cinco modos:

• Auto: o atualizador desaloca o pod. O controlador de admissão intercepta a solicitação de criação do novo pod e a modifica para usar os valores de CPU e memória recomendados pelo Recommender. A atualização de recursos exige a recriação do pod, o que pode causar interrupções. Use orçamentos de interrupção de pod, que o atualizador respeita, para gerenciar o processo de despejo. Esse modo é equivalente a Recreate.

• Recreate: o atualizador remove pods e atribui solicitações e limites de recursos recomendados quando o pod é recriado.

• InPlaceOrRecreate(alfa): o atualizador tenta fazer atualizações no local da melhor maneira possível, mas pode voltar a recriar o pod se as atualizações no local não forem possíveis. Para mais informações, consulte a documentação sobre redimensionamento de pods no local.

• Initial: o atualizador atribui solicitações de recursos apenas na criação do pod e nunca as altera depois.

• Off: o atualizador não muda automaticamente os requisitos de recursos dos pods. As recomendações são calculadas e podem ser inspecionadas no objeto VerticalPodAutoscaler.

Para mais informações sobre o recurso personalizado VerticalPodAutoscaler, use kubectl para recuperar a definição de recurso personalizado verticalpodautoscalercheckpoints.autoscaling.k8s.io instalada no cluster da versão 1.33.0 ou mais recente.

O exemplo a seguir mostra como as recomendações de recursos podem aparecer na seção Status do contêiner hamster. A amostra também mostra um exemplo de um evento de remoção de pod, que ocorre quando o atualizador remove um pod antes de atribuir automaticamente a configuração de recurso recomendada ao pod recriado:

Spec:
  Resource Policy:
    Container Policies:
      Container Name:  *
      Controlled Resources:
        cpu
        memory
      Max Allowed:
        Cpu:     1
        Memory:  500Mi
      Min Allowed:
        Cpu:     100m
        Memory:  50Mi
  Target Ref:
    API Version:  apps/v1
    Kind:         Deployment
    Name:         hamster
  Update Policy:
    Update Mode:  Auto
Status:
  Conditions:
    Last Transition Time:  2025-08-04T23:53:32Z
    Status:                True
    Type:                  RecommendationProvided
  Recommendation:
    Container Recommendations:
      Container Name:  hamster
      Lower Bound:
        Cpu:     100m
        Memory:  262144k
      Target:
        Cpu:     587m
        Memory:  262144k
      Uncapped Target:
        Cpu:     587m
        Memory:  262144k
      Upper Bound:
        Cpu:     1
        Memory:  500Mi
Events:
  Type    Reason      Age   From         Message
  ----    ------      ----  ----         -------
  Normal  EvictedPod  49s   vpa-updater  VPA Updater evicted Pod hamster-7cb59fb657-lkrk4 to apply resource recommendation.

Modo de economia de memória

O modo de economia de memória reduz o consumo de memória do componente de recomendação do escalonamento automático vertical de pods. Quando você define enableMemorySaver como true, o recomendador rastreia e calcula agregações apenas para pods que têm um recurso personalizado VerticalPodAutoscaler correspondente.

A desvantagem é que, ao criar um novo recurso personalizado VerticalPodAutoscaler para uma carga de trabalho atual, o recomendador leva algum tempo (até 24 horas) para coletar histórico suficiente e fornecer recomendações precisas. Esse modo é false por padrão para a maioria dos tipos de cluster, mas é true para clusters de borda.

Usar o Prometheus como um provedor de histórico permanente

Por padrão, o componente de recomendação mantém o histórico de consumo de recursos das cargas de trabalho em execução no cluster na memória e, periodicamente, salva o estado em um recurso personalizado VerticalPodAutoscalerCheckpoint no etcd para oferecer resiliência contra reinicializações.

A partir da versão 1.34 do Google Distributed Cloud, é possível usar sua própria instância do Prometheus como um provedor de histórico persistente para dados de consumo de recursos, ou seja, métricas de uso de CPU e memória. Quando essa integração está ativada, o recomendador pode consultar o servidor do Prometheus na inicialização ou reinicialização para recuperar dados históricos de uso de recursos de longo prazo para todos os pods gerenciados. A recuperação desses dados permite que o recomendador crie imediatamente um estado interno com um conjunto de dados avançado, gerando recomendações mais embasadas e precisas desde o início.

Usar o Prometheus como um provedor de histórico persistente oferece as seguintes vantagens:

• Otimização da utilização de recursos:gera recomendações bem fundamentadas e precisas assim que começa, para que você possa otimizar a utilização de recursos do cluster.

• Prevenção de erros de falta de memória (OOM):o Prometheus elimina a necessidade de armazenar o estado interno do recomendador em VerticalPodAutoscalerCheckpoint recursos personalizados (CRs, na sigla em inglês), tornando o uso da memória ETCD mais eficiente. Quando o componente de recomendação é reiniciado, ele perde os dados históricos na memória. Quando você usa o Prometheus como um provedor de histórico, o recomendador busca métricas históricas do Prometheus na reinicialização, o que elimina a necessidade do CR VerticalPodAutoscalerCheckpoint e economiza memória ETCD.

É possível ativar e desativar o uso do Prometheus como um provedor de histórico persistente a qualquer momento.

Pré-requisitos para usar o Prometheus com o escalonamento automático vertical de pods

Para usar sua própria instância do Prometheus como um provedor de histórico para o escalonamento automático vertical de pods, configure-a para extrair as métricas necessárias, o que envolve as seguintes etapas:

1. Se necessário, implante o operador do Prometheus no cluster em que você quer usá-lo como um provedor de histórico permanente para o escalonamento automático vertical de pods. Para mais informações, consulte Como implantar e configurar o operador do Prometheus no Kubernetes.

2. Configure permissões para extrair métricas.

   Para permitir que o Prometheus extraia métricas do cAdvisor usando um arquivo de configuração, é necessário conceder outras permissões à conta de serviço usada pelo servidor do Prometheus. Crie ou atualize um ClusterRole que contenha essas regras e verifique se ele está vinculado à conta de serviço correta do Prometheus usando um ClusterRoleBinding:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
      name: prometheus-role
      labels:
         app: prometheus-server
   rules:
      - apiGroups: [""]
        resources:
          - nodes
        verbs:
          - get
          - list
          - watch
      - apiGroups: [""]
        resources:
          - nodes/proxy
          - nodes/metrics
        verbs:
          - get
       ---
   
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: prometheus-binding
     labels:
       app: prometheus-server
   subjects:
     - kind: ServiceAccount
       name: prometheus-server        # Service account being used by prometheus
       namespace: prometheus          # Service account's namespace
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: prometheus-role            # Name of the ClusterRole created above
   

3. Atualize o arquivo de configuração do Prometheus para extrair as seguintes métricas do cAdvisor:

   • container_cpu_usage_seconds_total
   • container_memory_working_set_bytes

   As linhas a seguir definem os detalhes de extração das métricas do cAdvisor:

   - job_name: 'kubernetes-cadvisor'
     scheme: https
     tls_config:
       ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
     bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
     kubernetes_sd_configs:
       - role: node
     relabel_configs:
       - action: labelmap
         regex: __meta_kubernetes_node_label_(.+)
       - target_label: __address__
         replacement: kubernetes.default.svc:443
       - source_labels: [__meta_kubernetes_node_name]
         regex: (.+)
         target_label: __metrics_path__
         replacement: /api/v1/nodes/${1}/proxy/metrics/cadvisor
   
     metric_relabel_configs:
     # Keep only the metrics VPA uses to save disk space
       - source_labels: [__name__]
         regex: (container_cpu_usage_seconds_total|container_memory_working_set_bytes)
         action: keep
   

4. Atualize o arquivo de configuração do Prometheus para extrair a seguinte métrica do serviço kube-state-metrics:

   • kube_pod_labels

   1. Implante um serviço kube-state-metrics no cluster.

      Observação: embora um serviço kube-state-metrics seja instalado por padrão em clusters bare metal, ele não expõe a métrica kube_pod_labels necessária.

      É possível usar os seguintes comandos do Helm para instalar o novo serviço:

      helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
      helm repo update
      

   2. Crie um arquivo ksm-values.yaml com o seguinte conteúdo:

      fullnameOverride: vpa-kube-state-metrics
      metricAllowlist:
        - kube_pod_labels
      metricLabelsAllowlist:
        - "pods=[*]"
      

   3. Instale um gráfico do Helm com base no arquivo de valores da etapa anterior:

      helm install vpa-ksm prometheus-community/kube-state-metrics \
          -f ksm-values.yaml --namespace kube-system
      

   4. Adicione as linhas a seguir ao arquivo de configuração do Prometheus para extrair a métrica kube_pod_labels do serviço kube-state-metrics instalado:

      - job_name: 'kube-state-metrics'
        static_configs:
          - targets: ['vpa-kube-state-metrics.kube-system.svc.cluster.local:8080']
        metric_relabel_configs:
          - source_labels: [ __name__ ]
            regex: 'kube_pod_labels'
            action: keep
      

Ativar e usar o Prometheus

O escalonamento automático vertical de pods é compatível com autenticação básica e baseada em token de acesso para se conectar ao Prometheus. Ao usar a autenticação, é necessário criar um Secret com as credenciais necessárias no namespace do cluster. O controlador encaminha esse secret para o cluster de destino e o monta como um volume ou variável de ambiente no pod do recomendador. Também é possível usar o Prometheus sem autenticação.

Para ativar e usar sua própria instância do Prometheus com o escalonamento automático vertical de pods, configure a seção verticalPodAutoscaling na especificação do cluster com detalhes para se conectar à sua instância do Prometheus.

Confira um exemplo da configuração na especificação do cluster para uso com um token de autenticação:

apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: cluster1
  namespace: cluster-cluster1
  annotations:
    preview.baremetal.cluster.gke.io/vertical-pod-autoscaler: enable
spec:
  # ... other existing cluster configurations ...
  verticalPodAutoscaling:
    # ... other vertical Pod autoscaling configurations ...
    # Add this new section to configure the vpa to use prometheus using bearer token authentication as history provider
    prometheus:
      url: "http://prometheus.prometheus.monitoring.svc.cluster.local:9090"
      auth:
        bearerTokenAuth:
            name: prom-bearer-creds
            key: bearertoken

Para ativar o Prometheus para uso com o escalonamento automático vertical de pods:

1. Verifique se a instância do Prometheus está configurada para extrair as métricas necessárias, conforme descrito em Pré-requisitos para usar o Prometheus com o escalonamento automático vertical de pods.

2. Atualize o recurso personalizado do cluster spec para que o campo verticalPodAutoscaling.prometheus especifique as configurações de conexão do servidor do Prometheus.

3. Adicione o url à seção prometheus e defina-o como o nome de domínio totalmente qualificado (FQDN) para se conectar ao Prometheus de dentro do cluster:

   spec:
     # ... other existing cluster configurations ...
     verticalPodAutoscaling:
       # ... other vpa configurations ...
       # Add this new section to configure the vpa to use prometheus as history provider
       prometheus:
         # Required: The URL of the Prometheus server
         url: "http://prometheus.prometheus.svc.cluster.local:9090"
   

4. Especifique os detalhes da conexão:

   O escalonamento automático vertical de pods é compatível com os três métodos de conexão a seguir:

   • Sem autenticação
   • Autenticação básica (nome de usuário, senha)

   • Autenticação de token do portador

   Sem autenticação

   Se a instância do Prometheus não exigir autenticação, você concluiu a tarefa. A seção prometheus precisa incluir apenas um campo url.

   Autenticação básica

   Siga estas etapas para especificar a autenticação básica do Prometheus:

   1. Crie um Secret que contenha um nome de usuário e uma senha na seção stringData e a anotação baremetal.cluster.gke.io/mark-source: "true".

      O exemplo a seguir mostra um Secret que oferece suporte à autenticação básica:

      apiVersion: v1
      kind: Secret
      metadata:
        name: prom-basic-creds
        namespace: <cluster-namespace>
        annotations:
          baremetal.cluster.gke.io/mark-source: "true"
      type: Opaque
      stringData:
        username: admin
        password: pwd
      

      A anotação é necessária para garantir que o secret de origem e o secret no cluster de destino estejam sempre sincronizados. O secret é atualizado quando o secret de origem é atualizado.

      Observação: sempre que você fizer a rotação de credenciais, será necessário atualizar esse segredo.

   2. Atualize a seção prometheus.auth.basicAuth da especificação do cluster para referenciar o nome de usuário e a senha do campo data no Secret.

      O exemplo a seguir mostra uma seção basicAuth que faz referência ao nome de usuário e à senha no Secret da etapa anterior:

      # ... other vpa configurations ...
      prometheus:
        url: "http://prometheus.prometheus.svc.cluster.local:9090"
        auth:
          basicAuth:
            usernameRef:
              name: prom-basic-creds
              key: username
            passwordRef:
              name: prom-basic-creds
              key: password
      

      O nome de usuário e a senha precisam estar no mesmo secret. As chaves precisam ser válidas do campo data do Secret.

   A instância do Prometheus começa a funcionar como um provedor de histórico para o escalonador automático vertical de pods quando o recurso personalizado do cluster é atualizado.

   Autenticação de token do portador

   Siga estas etapas para especificar a autenticação de token do portador para o Prometheus:

   1. Crie um Secret que contenha um token do portador na seção stringData e a anotação baremetal.cluster.gke.io/mark-source: "true".

      O exemplo a seguir mostra um Secret que oferece suporte à autenticação de token do portador:

      apiVersion: v1
      kind: Secret
      metadata:
        name: prom-bearer-creds
        namespace: <cluster-namespace>
        annotations:
          baremetal.cluster.gke.io/mark-source: "true"
      type: Opaque
      stringData:
        bearertoken: "SAMPLE_TOKEN"
      

      A anotação é necessária para garantir que o secret de origem e o secret no cluster de destino estejam sempre sincronizados. O secret é atualizado quando o secret de origem é atualizado.

      Observação: sempre que você fizer a rotação de credenciais, será necessário atualizar esse segredo.

   2. Atualize a seção prometheus.auth.bearerTokenAuth da especificação do cluster para referenciar o token do portador do campo data no Secret.

      O exemplo a seguir mostra uma seção bearerTokenAuth que referencia o token do portador no Secret da etapa anterior:

      # ... other vertical Pod autoscaling configurations ...
      prometheus:
        url: "http://prometheus.prometheus.svc.cluster.local:9090"
        auth:
          bearerTokenAuth:
              name: prom-bearer-creds
              key: bearertoken
      

      A chave precisa ser válida e estar no campo data do Secret.

   A instância do Prometheus começa a funcionar como um provedor de histórico para o escalonamento automático vertical de pods quando o recurso personalizado do cluster é atualizado.

Desativar o uso do Prometheus

Para desativar o uso do Prometheus com o escalonamento automático vertical de pods, remova a seção prometheus da seção verticalPodAutoscaling do recurso personalizado do cluster.

Desativar o escalonamento automático vertical de pods

Desative o escalonamento automático vertical de pods removendo os recursos personalizados e a configuração do cluster:

1. Exclua todos os recursos personalizados VerticalPodAutoscaler que você criou.

2. Modifique o recurso personalizado do cluster e remova toda a seção verticalPodAutoscaling do spec.

   É possível editar o recurso personalizado do cluster diretamente ou modificar o arquivo de configuração do cluster e usar bmctl update.

3. Remova a anotação preview.baremetal.cluster.gke.io/vertical-pod-autoscaler do recurso personalizado do cluster.

Limitações

Considere as seguintes limitações ao usar o escalonamento automático vertical de pods:

• O escalonamento automático vertical de pods ainda não está pronto para uso com cargas de trabalho baseadas em JVM devido à visibilidade limitada do uso real da memória da carga de trabalho.
• O atualizador exige um mínimo de duas réplicas de pod para que as implantações substituam os pods por valores de recursos revisados.
• O atualizador não atualiza rapidamente os pods que estão em loop de falha devido a erros de memória insuficiente (OOM).
• A política de atualização InPlaceOrRecreate para pods é um recurso Alfa no escalonamento automático vertical de pods. Ele tenta fazer atualizações no local com o melhor esforço possível, mas pode recorrer à recriação do pod se as atualizações no local não forem possíveis.

A seguir

• Conheça os orçamentos de interrupção de pods.