Resolver problemas de escalonamento automático horizontal de pods

Quando o escalonamento automático horizontal de pods não funciona como esperado no Google Kubernetes Engine (GKE), as cargas de trabalho podem não ser escalonadas corretamente. Esse problema pode impedir que os aplicativos processem a carga, o que pode causar problemas de desempenho ou interrupções. É possível que os pods não aumentem apesar do uso alto da CPU, que os valores das métricas apareçam como <unknown> no status do HorizontalPodAutoscaler ou que as operações de escalonamento não ocorram.

Use este documento para diagnosticar e resolver problemas comuns com o escalonamento automático horizontal de pods, desde erros de configuração iniciais nos objetos HorizontalPodAutoscaler até falhas mais complexas no pipeline de métricas. Ao seguir estas etapas de solução de problemas, você ajuda a garantir que seus aplicativos sejam escalonados de maneira eficiente e confiável com base na demanda, fazendo uso eficaz do recurso HorizontalPodAutoscaler.

Essas informações são importantes para desenvolvedores de aplicativos que configuram objetos HorizontalPodAutoscaler e precisam garantir que os aplicativos sejam escalonados corretamente. Também ajuda os administradores e operadores da plataforma a resolver problemas com o pipeline de métricas ou a configuração do cluster que afetam todas as cargas de trabalho com escalonamento automático. Para mais informações sobre as funções comuns e as tarefas de exemplo que mencionamos no conteúdo do Google Cloud , consulte Funções e tarefas comuns do usuário do GKE.

Antes de começar

  • Use objetos HorizontalPodAutoscaler com cargas de trabalho escalonáveis, como implantações e StatefulSets. Não é possível usar o escalonamento automático horizontal de pods com cargas de trabalho que não podem ser escalonadas, como DaemonSets.

  • Para ter as permissões necessárias para resolver problemas de escalonamento automático horizontal de pods no GKE, o que inclui inspecionar objetos HorizontalPodAutoscaler e visualizar registros do cluster, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

    Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

    Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

  • Configure a ferramenta de linha de comando kubectl para se comunicar com o cluster do GKE:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location LOCATION \
    --project PROJECT_ID

    Substitua:

    • CLUSTER_NAME: o nome do cluster.
    • LOCATION: a região ou zona do Compute Engine (por exemplo, us-central1 ou us-central1-a) do cluster.
    • PROJECT_ID: o ID do projeto Google Cloud .

Diagnosticar problemas do HorizontalPodAutoscaler

Para diagnosticar problemas com um HorizontalPodAutoscaler, inspecione o status e a configuração usando comandos kubectl ou o console do Google Cloud .

Descreva o HorizontalPodAutoscaler:

Para conferir cálculos em tempo real e decisões de escalonamento recentes, use o comando kubectl describe hpa:

kubectl describe hpa HPA_NAME -n NAMESPACE_NAME

Substitua:

  • HPA_NAME: o nome do objeto HorizontalPodAutoscaler.
  • NAMESPACE_NAME: o namespace do objeto HorizontalPodAutoscaler.

O resultado será o seguinte:

Name:                                                  php-apache-hpa
Namespace:                                             default
Reference:                                             Deployment/php-apache
Metrics: ( current / target )
  resource cpu on pods (as a percentage of request):   1% (1m) / 50%
Min replicas:                                          1
Max replicas:                                          10
Conditions:
  Type            Status  Reason              Message
  ----            ------  ------              -------
  AbleToScale     True    ReadyForNewScale    recommended size matches current size
  ScalingActive   True    ValidMetricFound    the HorizontalPodAutoscaler was able to successfully calculate a replica count
Events:
  Type     Reason              Age   From                       Message
  ----     ------              ----  ----                       -------
  Normal   SuccessfulRescale   39m   horizontal-pod-autoscaler  New size: 4; reason: cpu resource utilization...
  Normal   SuccessfulRescale   26m   horizontal-pod-autoscaler  New size: 1; reason: cpu resource utilization...

Na saída, as três seções a seguir ajudam a diagnosticar o problema:

  • Metrics: mostra os valores atuais das métricas em comparação com as metas. Um valor de métrica <unknown> indica que o HorizontalPodAutoscaler não buscou a métrica ou que o pipeline de métricas está corrompido.
  • Conditions: mostra se o HorizontalPodAutoscaler pode buscar métricas (AbleToScale) e realizar cálculos de escalonamento (ScalingActive). Um status False em qualquer uma dessas condições indica uma falha.
  • Events: registra ações de escalonamento, avisos e erros recentes do controlador HorizontalPodAutoscaler. Muitas vezes, é o primeiro lugar para encontrar mensagens de erro ou motivos específicos, como FailedGetScale ou FailedGetResourceMetric.

Verificar o manifesto do HorizontalPodAutoscaler

O manifesto YAML do objeto HorizontalPodAutoscaler permite conferir informações sobre a configuração e o estado atual dele.

Para conferir o manifesto YAML, selecione uma das seguintes opções:

Console

  1. No console do Google Cloud , acesse a página Navegador de objetos.

    Acessar o navegador de objetos

  2. Na lista Tipos de objeto, marque a caixa de seleção HorizontalPodAutoscaler e clique em OK.

  3. Navegue até o grupo de APIs autoscaling e clique na seta de expansão para HorizontalPodAutoscaler.

  4. Clique no nome do objeto HorizontalPodAutoscaler que você quer inspecionar.

  5. Revise a seção YAML, que mostra a configuração completa do objeto HorizontalPodAutoscaler.

kubectl

Execute este comando:

kubectl get hpa HPA_NAME -n NAMESPACE_NAME -o yaml

Substitua:

  • HPA_NAME: o nome do objeto HorizontalPodAutoscaler.
  • NAMESPACE_NAME: o namespace do objeto HorizontalPodAutoscaler.

Depois de recuperar o manifesto, procure estas seções principais:

  • spec (sua configuração):
    • scaleTargetRef: a carga de trabalho (como uma implantação) que o HorizontalPodAutoscaler está configurado para escalonar.
    • minReplicas e maxReplicas: as configurações mínima e máxima de réplicas.
    • metrics: as métricas configuradas para escalonamento (por exemplo, utilização da CPU ou métricas personalizadas).
  • status (o estado ativo do HorizontalPodAutoscaler):
    • currentMetrics: os valores de métrica mais recentes que o HorizontalPodAutoscaler observou.
    • currentReplicas e desiredReplicas: o número atual de pods e o número para que o HorizontalPodAutoscaler quer escalonar.
    • conditions: mostra a integridade do HorizontalPodAutoscaler:
      • AbleToScale: indica se o HorizontalPodAutoscaler pode encontrar a meta e as métricas.
      • ScalingActive: mostra se o HorizontalPodAutoscaler pode calcular e realizar o escalonamento.
      • ScalingLimited: mostra se o HorizontalPodAutoscaler quer escalonar, mas está sendo limitado pelas configurações de minReplicas ou maxReplicas.

Ver logs de eventos

Para ter mais insights sobre o objeto HorizontalPodAutoscaler, use os seguintes tipos de registros:

  • Conferir eventos do HorizontalPodAutoscaler no Cloud Logging: use um filtro de registros para encontrar todos os eventos do HorizontalPodAutoscaler de um cluster específico. Exemplo:

    1. No console do Google Cloud , 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_cluster"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.location="LOCATION"
logName="projects/PROJECT_ID/logs/events"
jsonPayload.involvedObject.kind="HorizontalPodAutoscaler"

      Substitua:

      • CLUSTER_NAME: o nome do cluster a que o HorizontalPodAutoscaler pertence.
      • LOCATION: a região ou zona do Compute Engine (por exemplo, us-central1 ou us-central1-a) do cluster.
      • PROJECT_ID: o ID do projeto.

    3. Clique em Executar consulta e analise a saída.

  • Ver eventos de escalonamento automático horizontal de pods: esses registros são estruturados e legíveis por humanos, explicando como o HorizontalPodAutoscaler calcula uma recomendação, oferecendo insights detalhados sobre o processo de tomada de decisão.

Resolver erros de configuração do HorizontalPodAutoscaler

As seções a seguir abordam configurações incorretas no manifesto do HorizontalPodAutoscaler, como campos digitados incorretamente, destinos de métricas inválidos ou configurações conflitantes.

Carga de trabalho de destino não encontrada

Sintomas

A seção Events tem uma condição de FailedGetScale com uma mensagem semelhante a esta:

the HorizontalPodAutoscaler controller was unable to get the target's current scale: WORKLOAD_TYPE.apps "TARGET_WORKLOAD" not found

Esta saída inclui os seguintes valores:

  • WORKLOAD_TYPE: o tipo de carga de trabalho, como Deployment ou StatefulSet.
  • TARGET_WORKLOAD: o nome da carga de trabalho.

Causa

O controlador HorizontalPodAutoscaler não consegue encontrar a carga de trabalho (como uma implantação ou um StatefulSet) que está configurado para gerenciar. Esse problema ocorre devido a uma configuração incorreta no campo scaleTargetRef do manifesto do HorizontalPodAutoscaler. O recurso especificado pode não existir, ter sido excluído ou ter um erro de ortografia.

Resolução

Tente as seguintes soluções:

  1. Verifique o campo scaleTargetRef do manifesto do HorizontalPodAutoscaler: confira se os valores de name, kind e apiVersion no campo scaleTargetRef correspondem exatamente aos metadados da sua carga de trabalho de destino. Se o nome da carga de trabalho estiver incorreto, atualize o campo scaleTargetRef do HorizontalPodAutoscaler para apontar para o nome correto.
  2. Confirme se a carga de trabalho existe: verifique se a carga de trabalho de destino está no mesmo namespace que o HorizontalPodAutoscaler. Para verificar isso, use um comando como kubectl get deployment DEPLOYMENT_NAME. Se você excluiu intencionalmente a carga de trabalho, exclua o objeto HorizontalPodAutoscaler correspondente para limpar o cluster. Se você precisar recriar a carga de trabalho, o HorizontalPodAutoscaler a encontrará automaticamente depois que ela estiver disponível, e o erro será resolvido.
  3. Verifique se o HorizontalPodAutoscaler e a carga de trabalho estão no mesmo namespace: o HorizontalPodAutoscaler e a carga de trabalho de destino precisam estar no mesmo namespace. Se você se esquecer de especificar um namespace ao criar um objeto com comandos kubectl, o Kubernetes vai colocar o objeto no namespace default. Esse comportamento pode causar uma incompatibilidade se o HorizontalPodAutoscaler estiver no namespace default e a carga de trabalho estiver em outro, ou vice-versa. Verifique o namespace dos dois objetos e confira se eles correspondem.

Depois que o HorizontalPodAutoscaler localizar o destino, a condição AbleToScale vai se tornar True, e a mensagem vai mudar para: the HorizontalPodAutoscaler controller was able to get the target's current scale.

Métricas inválidas

Sintomas

Se o HorizontalPodAutoscaler não puder calcular as réplicas necessárias devido a um problema de configuração, a seção Events mostrará um motivo de FailedComputeMetricsReplicas com uma mensagem semelhante a esta:

invalid metrics (1 invalid out of 1)

Causa

Esse erro geralmente significa que há uma incompatibilidade entre a métrica type e o target definido no manifesto HorizontalPodAutoscaler. Por exemplo, você pode ter especificado um type de Utilization, mas fornecido um valor de segmentação de averageValue em vez de averageUtilization.

Resolução

Corrija o manifesto HorizontalPodAutoscaler para que o valor do campo target esteja alinhado à métrica type:

  • Se type for Utilization, o valor no campo target precisará ser averageUtilization.
  • Se type for AverageValue, o valor no campo target precisará ser averageValue.

O rótulo da métrica não é permitido

Sintomas

Você vai encontrar o seguinte erro:

unable to fetch metrics from external metrics API: googleapi: Error 400: Metric label: 'LABEL_NAME' is not allowed

Nessa saída, LABEL_NAME é o nome do rótulo incorreto.

Causa

O manifesto HorizontalPodAutoscaler especifica uma chave de rótulo inválida na seção metric.selector.matchLabels, e o Cloud Monitoring não reconhece nem permite essa chave para a métrica.

Resolução

Para resolver esse problema, faça o seguinte:

  1. Identifique o nome de rótulo proibido na mensagem de erro.
  2. Remova ou corrija essa chave de rótulo na seção metric.selector.matchLabels do manifesto HorizontalPodAutoscaler.
  3. Consulte a documentação do Cloud Monitoring para essa métrica e encontre uma chave de rótulo válida e filtrável.

Vários HorizontalPodAutoscalers têm como destino a mesma carga de trabalho

Sintomas

Não há um Condition ou Reason específico no status de um HorizontalPodAutoscaler que indique diretamente esse conflito. Em vez disso, você pode observar os seguintes sintomas:

  • A contagem de réplicas da carga de trabalho pode variar de forma inesperada.
  • As decisões de escalonamento podem não corresponder às métricas definidas em um único HorizontalPodAutoscaler.
  • Ao visualizar eventos, você pode encontrar eventos SuccessfulRescale alternados ou contraditórios de diferentes objetos HorizontalPodAutoscaler.

Causa

Esse problema ocorre porque mais de um objeto HorizontalPodAutoscaler no mesmo namespace especifica exatamente a mesma carga de trabalho no campo spec.scaleTargetRef. Cada HorizontalPodAutoscaler calcula de forma independente as contagens de réplicas e tenta escalonar a carga de trabalho com base no próprio conjunto de métricas e metas. O Kubernetes não bloqueia essa configuração, mas ela leva a ajustes de escalonamento irregulares porque os HorizontalPodAutoscalers competem entre si.

Resolução

Para evitar conflitos, defina todas as métricas de escalonamento em um único objeto HorizontalPodAutoscaler. Cada HorizontalPodAutoscaler calcula as necessidades de escalonamento com base no próprio campo spec.metrics. Portanto, ao mesclá-los, o objeto HorizontalPodAutoscaler escolhido considera todos os fatores, como CPU e solicitações por segundo, juntos:

  1. Para identificar quais HorizontalPodAutoscalers têm como destino a mesma carga de trabalho, acesse o manifesto YAML de cada objeto HorizontalPodAutoscaler. Preste atenção ao campo spec.scaleTargetRef na saída.

    kubectl get hpa -n NAMESPACE_NAME -o yaml

    Substitua NAMESPACE_NAME pelo namespace do objeto HorizontalPodAutoscaler.

    Procure instâncias em que diferentes recursos HorizontalPodAutoscaler tenham os mesmos valores para apiVersion, kind e name no campo scaleTargetRef.

  2. Consolide as métricas em um único objeto HorizontalPodAutoscaler:

    1. Escolha um objeto HorizontalPodAutoscaler para manter. Este HorizontalPodAutoscaler será o que você vai modificar.
    2. Examine a seção spec.metrics no manifesto de cada um dos outros objetos HorizontalPodAutoscaler que têm como destino a mesma carga de trabalho.
    3. Copie as definições de métricas que você quer manter das seções spec.metrics dos objetos HorizontalPodAutoscaler duplicados.
    4. Cole essas definições de métricas copiadas na matriz spec.metrics do HorizontalPodAutoscaler que você decidiu manter.

  3. Aplique as alterações:

    kubectl apply -f MANIFEST_NAME

    Substitua MANIFEST_NAME pelo nome do manifesto HorizontalPodAutoscaler que você decidiu manter.

  4. Exclua os outros objetos HorizontalPodAutoscaler que estavam segmentando a mesma carga de trabalho:

    kubectl delete hpa DUPLICATE_MANIFEST_NAME -n NAMESPACE_NAME

    Substitua DUPLICATE_MANIFEST_NAME pelo nome do objeto HorizontalPodAutoscaler redundante que você quer excluir.

Resolver problemas de carga de trabalho e erros de serviço

As seções a seguir abordam erros causados pela carga de trabalho de destino ou pelos serviços associados a ela, e não pelo objeto HorizontalPodAutoscaler em si.

Solicitações de recursos ausentes para cálculo de escalonamento

Sintomas

A condição ScalingActive é False com um Reason de FailedGetResourceMetric. Normalmente, você também verá uma mensagem semelhante a esta:

the HorizontalPodAutoscaler was unable to compute the replica count

Causa

O HorizontalPodAutoscaler precisa calcular a utilização de recursos como uma porcentagem para escalonar a carga de trabalho, mas não pode realizar esse cálculo porque pelo menos um contêiner na especificação do pod não tem uma definição de resources.requests para o recurso correspondente (cpu ou memory).

Resolução

Para resolver esse problema, atualize o manifesto do pod na sua implantação, StatefulSet ou outro controlador para incluir um campo resources.requests para o recurso (cpu ou memory) que o HorizontalPodAutoscaler está tentando escalonar em todos os contêineres do pod. Exemplo:

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
# Multiple lines are omitted here
spec:
  containers:
  - name: example-container
    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"

Não foi possível buscar métricas do pod

Sintomas

Você observa uma mensagem persistente semelhante a esta:

unable to fetch pod metrics for pod

É normal que essa mensagem apareça temporariamente quando o servidor de métricas é iniciado.

Causa

Para escalonar com base na porcentagem de utilização de recursos (como cpu ou memory), todos os contêineres nos pods visados pelo objeto HorizontalPodAutoscaler precisam ter o campo resources.requests definido para esse recurso específico. Caso contrário, o HorizontalPodAutoscaler não poderá fazer os cálculos necessários e não reagirá às ações relacionadas a essa métrica.

Resolução

Se essas mensagens de erro persistirem e você notar que os pods não estão sendo escalonados para sua carga de trabalho, verifique se você especificou solicitações de recursos para cada contêiner na sua carga de trabalho.

Vários serviços selecionam o mesmo destino

Sintomas

Você vai encontrar o seguinte erro:

multiple services selecting the same target of HPA_NAME: SERVICE_NAME

Esta saída inclui os seguintes valores:

  • HPA_NAME: o nome do HorizontalPodAutoscaler.
  • SERVICE_NAME: o nome de um serviço.

Causa

O escalonamento automático com base no tráfego está configurado, mas mais de um serviço do Kubernetes está segmentando o campo scaleTargetRef do HorizontalPodAutoscaler. O escalonamento automático baseado em tráfego só oferece suporte a uma relação individual entre o serviço e a carga de trabalho escalonada automaticamente.

Resolução

Para corrigir esse problema, verifique se apenas um seletor de rótulos do Serviço corresponde aos pods da carga de trabalho:

  1. Encontre os rótulos do pod da sua carga de trabalho:

    kubectl get deployment HPA_TARGET_DEPLOYMENT \
    -n NAMESPACE \
    -o jsonpath='{.spec.template.metadata.labels}'

    Substitua:

    • HPA_TARGET_DEPLOYMENT: o nome da implantação que o HorizontalPodAutoscaler está segmentando.
    • NAMESPACE: o namespace da implantação.

    O resultado será o seguinte:

    {"app":"my-app", "env":"prod"}

  2. Encontre todos os serviços que correspondem a esses rótulos revisando o campo spec.selector para todos os serviços no namespace.

    kubectl get services -n NAMESPACE -o yaml

    Identifique todos os serviços cujo seletor corresponda aos rótulos da etapa anterior. Por exemplo, {"app": "my-app"} e {"app": "my-app", "env": "prod"} correspondem aos rótulos de pod de exemplo.

  3. Resolva o conflito escolhendo uma das seguintes opções:

    • Adicione um novo rótulo exclusivo ao campo spec.template.metadata.labels da implantação para tornar o seletor do serviço pretendido exclusivo. Em seguida, atualize o campo spec.selector do único serviço pretendido para incluir esse novo rótulo.
    • Mude o campo spec.selector de todos os outros serviços conflitantes para que eles sejam mais restritivos e não correspondam mais aos pods da sua carga de trabalho.

  4. Aplique as alterações:

    kubectl apply -f MANIFEST_NAME

    Substitua MANIFEST_NAME pelo nome do arquivo YAML que contém o manifesto de serviço ou implantação atualizado.

Resolver problemas de disponibilidade de dados e da API Metrics

As seções a seguir ajudam você a resolver erros que ocorrem quando o HorizontalPodAutoscaler tenta se comunicar com uma API Metrics ou consultar um backend de métricas.

Resolver problemas de métricas personalizadas e externas

Quando o HorizontalPodAutoscaler depende de métricas de fontes diferentes da CPU ou da memória padrão, podem ocorrer problemas no pipeline de métricas personalizadas ou externas. Esse pipeline consiste no controlador HorizontalPodAutoscaler, no servidor da API de métricas do Kubernetes, no adaptador de métricas e na origem da métrica (por exemplo, Cloud Monitoring ou Prometheus), conforme mostrado no diagrama a seguir:

Um pipeline de métricas do HPA mostrando os componentes: controlador do HPA, servidor de API Kubernetes, adaptador de métricas e origem de métricas.

Sintomas

Os sintomas mais comuns de um problema no pipeline de métricas são:

  • O valor da métrica é exibido como <unknown>.
  • Os eventos do HorizontalPodAutoscaler mostram erros como FailedGetExternalMetric ou FailedGetCustomMetric.

Causa

Há um problema no pipeline de métricas personalizadas ou externas.

Resolução

Siga estas etapas para depurar o pipeline:

  1. Verifique se o adaptador de métricas está registrado e disponível: o adaptador de métricas precisa se registrar no servidor de API principal do Kubernetes para exibir métricas. Essa ação é a maneira mais direta de ver se o adaptador está em execução e acessível pelo servidor de API:

    kubectl get apiservice | grep -E 'NAME|metrics.k8s.io'

    Na saída, você vai encontrar as entradas v1beta1.custom.metrics.k8s.io ou v1beta1.external.metrics.k8s.io e um valor de True na coluna Available. Exemplo:

    NAME                   SERVICE                      AVAILABLE   AGE
v1beta1.metrics.k8s.io kube-system/metrics-server   True        18d

    • Se o valor na coluna Available for False ou estiver ausente, é provável que o adaptador tenha falhado ou esteja configurado incorretamente. Verifique os registros do pod do adaptador nos namespaces kube-system ou custom-metrics para ver se há erros relacionados a permissões, conectividade de rede com a origem da métrica ou mensagens indicando que a métrica não foi encontrada.

    • Se o valor for True, siga para a próxima etapa.

  2. Consultar a API Metrics diretamente: se o adaptador estiver disponível, ignore o HorizontalPodAutoscaler e peça sua métrica diretamente à API Kubernetes. Esse comando testa todo o pipeline, do servidor de API ao adaptador de métricas e à fonte de dados.

    Para consultar métricas externas, execute o seguinte comando:

    kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/NAMESPACE_NAME/METRIC_NAME" | jq .

    Para consultar métricas personalizadas de pod, execute o seguinte comando:

    kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/namespaces/NAMESPACE_NAME/pods/*/METRIC_NAME" | jq .

    Substitua:

    • NAMESPACE_NAME: o namespace em que os pods estão em execução.
    • METRIC_NAME: o nome da métrica personalizada ou externa que você está tentando consultar. Por exemplo, requests_per_second ou queue_depth.

  3. Analise a resposta ao comando: o resultado dos comandos anteriores informa onde está o problema. Escolha o cenário que corresponde à sua saída:

    • Resposta JSON bem-sucedida com um valor: o pipeline de métricas está funcionando corretamente. O problema provavelmente é um erro de configuração no manifesto HorizontalPodAutoscaler. Verifique se há erros de ortografia no nome da métrica ou matchLabels incorretos.

    • Error: Error from server (Service Unavailable): esse erro geralmente indica um problema de conectividade de rede, que costuma ser um problema de firewall em clusters que usam isolamento de rede.

      1. Identifique o serviço do adaptador de métricas. Geralmente, ele está no namespace custom-metrics ou kube-system:

        kubectl get service -n custom-metrics,kube-system | grep -E 'adapter|metrics'

      2. Encontre a porta em que o adaptador está aguardando conexões:

        kubectl get service ADAPTER_SERVICE -n ADAPTER_NAMESPACE -o yaml

        Substitua:

        • ADAPTER_SERVICE: o nome do serviço do Kubernetes associado ao adaptador de métricas implantado. Esse serviço é o que você encontrou na etapa anterior. Esse serviço expõe a funcionalidade do adaptador para outras partes do cluster, incluindo o servidor de API Kubernetes.
        • ADAPTER_NAMESPACE: o namespace em que o serviço adaptador reside (por exemplo, custom-metrics ou kube-system).

      3. Encontre as regras de firewall de entrada para o plano de controle do cluster:

        gcloud compute firewall-rules list \
    --filter="name~gke-CLUSTER_NAME-[0-9a-z]*-master"

        Substitua CLUSTER_NAME pelo nome do cluster.

      4. Adicione o targetPort do adaptador à regra:

        1. Descreva a regra atual para conferir as portas permitidas:

          gcloud compute firewall-rules describe FIREWALL_RULE_NAME

          Substitua FIREWALL_RULE_NAME pelo nome da regra de firewall que rege o tráfego de rede para o plano de controle do cluster do Kubernetes.

        2. Atualize a regra para adicionar a porta do adaptador à lista:

          gcloud compute firewall-rules update FIREWALL_RULE_NAME \
    --allow tcp:443,tcp:10250,tcp:ADAPTER_PORT

          Substitua ADAPTER_PORT pela porta de rede em que o adaptador de métricas está detectando.

      5. Verifique se as políticas de rede do Kubernetes não estão bloqueando o tráfego para os pods do adaptador de métricas:

        kubectl get networkpolicy -n custom-metrics,kube-system

        Revise as políticas para verificar se elas permitem o tráfego de entrada do plano de controle ou do servidor de API para o ADAPTER_SERVICE no ADAPTER_PORT.

    • Uma lista vazia []: essa saída significa que o adaptador está em execução, mas não consegue recuperar a métrica específica, indicando um problema com a configuração do adaptador ou com a própria origem da métrica.

      • Problemas com o pod do adaptador: inspecione os registros do pod ou dos pods do adaptador de métricas em busca de erros relacionados a chamadas de API, autenticação ou busca de métricas. Para inspecionar os registros, faça o seguinte:

        1. Encontre o nome do pod do adaptador:

          kubectl get pods -n ADAPTER_NAMESPACE

        2. Confira os registros:

          kubectl logs ADAPTER_POD_NAME \
    -n ADAPTER_NAMESPACE

          Substitua:

          • ADAPTER_POD_NAME: o nome do pod do adaptador que você identificou na etapa anterior.
          • ADAPTER_NAMESPACE: o namespace em que o pod do adaptador reside (por exemplo, custom-metrics ou kube-system).

      • Não há dados na origem: talvez a métrica não exista no sistema de origem. Use uma ferramenta de monitoramento, como o Metrics Explorer, para confirmar se a métrica existe e tem o nome e os rótulos corretos.

Versões de métricas não encontradas ou adaptador indisponível

Sintomas

Você vai encontrar o seguinte erro:

unable to fetch metrics from custom metrics API: no known available metric versions found

Causa

Esse erro indica uma falha na comunicação dentro do cluster, não um problema com a origem das métricas (como o Cloud Monitoring). As causas mais comuns incluem:

  • O servidor da API Kubernetes está temporariamente indisponível (por exemplo, durante um upgrade de cluster ou reparo do plano de controle).
  • Os pods do adaptador de métricas (por exemplo, custom-metrics-stackdriver-adapter) não estão íntegros, não estão em execução ou não estão registrados corretamente no servidor da API.

Resolução

Esse problema geralmente é temporário. Se ele persistir, tente as seguintes soluções:

  1. Verifique a integridade do plano de controle do Kubernetes:

    1. No console do Google Cloud , confira a integridade e o status do cluster.

      1. Acesse a página Clusters do Kubernetes.

        Acessar clusters do Kubernetes

    2. Verifique as colunas Status e Notificações do cluster.

    3. Clique em Notificações para procurar operações em andamento, como upgrades ou reparos. O servidor de API pode ficar temporariamente indisponível durante esses períodos.

    4. Revise os registros de auditoria do Cloud para verificar se há erros relacionados aos componentes do plano de controle. Para informações sobre como visualizar esses registros, consulte Informações sobre a geração de registros de auditoria do GKE.

  2. Verifique a integridade e os registros dos pods do adaptador de métricas: confira se os pods do adaptador de métricas estão no status Running e não foram reiniciados recentemente:

    kubectl get pods -n custom-metrics,kube-system -o wide

    Se o status de um pod for diferente de Running ou se ele tiver uma contagem alta de reinicializações, investigue o pod para encontrar a causa raiz. Para dicas de solução de problemas, consulte Pods de depuração na documentação do Kubernetes.

  3. Verifique se as APIs de métricas estão registradas e disponíveis:

    kubectl get apiservice | grep metrics.k8s.io

    Se as APIs Metrics estiverem íntegras, a saída será semelhante a esta:

    NAME                            SERVICE                                             AVAILABLE   AGE
v1beta1.custom.metrics.k8s.io   custom-metrics/custom-metrics-stackdriver-adapter   True        18d
v1beta1.external.metrics.k8s.io custom-metrics/custom-metrics-stackdriver-adapter   True        18d
v1beta1.metrics.k8s.io          kube-system/metrics-server                          True        18d

    Se a coluna AVAILABLE tiver um valor de False, a coluna Message no manifesto completo do APIService poderá fornecer mais detalhes.

    Para conferir o manifesto completo, use o seguinte comando:

    kubectl get apiservice API_SERVICE_NAME -o yaml

    Substitua API_SERVICE_NAME pelo nome do objeto APIService, como v1beta1.custom.metrics.k8s.io.

A consulta de métrica não retorna série temporal

Sintomas

Você vai encontrar o seguinte erro:

unable to fetch metrics from custom or external metrics API: googleapi: Error
400: The supplied filter [...] query will not return any time series

Causa

A consulta enviada ao Cloud Monitoring era válida, mas não retornou dados. Isso significa que não há pontos de dados que correspondam ao seu filtro, o que é diferente de encontrar uma métrica com um valor de 0. O motivo mais provável para esse problema é que o aplicativo ou a carga de trabalho responsável por gerar a métrica personalizada não estava gravando dados no Cloud Monitoring durante o período em que os erros foram informados.

Resolução

Tente as seguintes soluções:

  1. Verifique a configuração: confira se os nomes e rótulos das métricas no objeto HorizontalPodAutoscaler correspondem exatamente aos emitidos pelo aplicativo.
  2. Verifique as permissões: confirme se o aplicativo está configurado corretamente com as permissões e os endpoints de API necessários para publicar métricas no Cloud Monitoring.
  3. Confirme a atividade do aplicativo: verifique se o aplicativo responsável pela métrica estava operacional e tentando enviar dados para o Cloud Monitoring durante o período em que os avisos do HorizontalPodAutoscaler ocorreram.
  4. Investigue erros: verifique os registros do aplicativo no mesmo período para encontrar erros explícitos relacionados à emissão de métricas, como falhas de conexão, credenciais inválidas ou problemas de formatação.

Resolver problemas de comportamentos de escalonamento saudáveis, mas inesperados

As seções a seguir abordam cenários em que a configuração do HorizontalPodAutoscaler é válida e as métricas estão disponíveis, mas as ações de escalonamento não ocorrem conforme o esperado.

O HorizontalPodAutoscaler está íntegro, mas não é escalonado

Sintomas

O HorizontalPodAutoscaler parece estar em bom estado, as condições dele informam True e não mostram erros nos eventos. No entanto, ele ainda não realiza nenhuma ação de escalonamento.

Causa

Vários fatores podem causar esse comportamento esperado:

  • Limites de réplica: o número atual de réplicas já está no limite definido pelo campo minReplicas ou maxReplicas na configuração do HorizontalPodAutoscaler.
  • Janela de tolerância: o Kubernetes usa uma janela de tolerância padrão de 10% para evitar o escalonamento em pequenas flutuações de métricas. O escalonamento só ocorre se a proporção da métrica atual para a métrica de destino estiver fora do intervalo de 0,9 a 1,1. Por exemplo, se o destino for 85% de CPU e o uso atual for 93%, a proporção será de aproximadamente 1,094 (93/85≈1,094). Como esse valor é menor que 1,1, o HorizontalPodAutoscaler não faz escalonar verticalmente.
  • Pods não prontos: o HorizontalPodAutoscaler inclui apenas pods com um status Ready nos cálculos de escalonamento. Os pods que estão travados com um status Pending ou que não estão se tornando Ready (devido a falhas nas verificações de integridade ou problemas de recursos) são ignorados e podem impedir o escalonamento.
  • Atraso no período de sincronização: o controlador do HorizontalPodAutoscaler verifica as métricas periodicamente. Um atraso de 15 a 30 segundos entre uma métrica que ultrapassa o limite e o início de uma ação de escalonamento é normal.
  • Latência de nova métrica: quando um HorizontalPodAutoscaler usa uma nova métrica personalizada pela primeira vez, pode haver uma latência única de vários minutos. Esse atraso ocorre porque o sistema de monitoramento (como o Cloud Monitoring) precisa criar a nova série temporal quando o primeiro ponto de dados é gravado.
  • Cálculo de várias métricas: quando você configura várias métricas, o HorizontalPodAutoscaler calcula a contagem de réplicas necessária para cada métrica de forma independente e escolhe o valor mais alto calculado como o número final de réplicas. Devido a esse comportamento, sua carga de trabalho é escalonada para atender às demandas da métrica com as maiores necessidades. Por exemplo, se as métricas de CPU calcularem a necessidade de nove réplicas, mas uma métrica de solicitações por segundo calcular a necessidade de 15, o HorizontalPodAutoscaler escalonará a implantação para 15 réplicas.

Resolução

Tente as seguintes soluções:

  • Limites de réplica: verifique os valores minReplicas e maxReplicas no manifesto do HorizontalPodAutoscaler ou na saída do comando kubectl describe. Ajuste esses limites se eles estiverem impedindo o escalonamento necessário.
  • Janela de tolerância: se o escalonamento for necessário dentro da tolerância padrão, configure um valor de tolerância diferente. Caso contrário, aguarde até que a métrica saia da proporção de 0,9 a 1,1.
  • Pods não prontos: investigue por que os pods estão Pending ou não Ready e resolva os problemas subjacentes (por exemplo, restrições de recursos, falha nas sondagens de prontidão). Para dicas de solução de problemas, consulte Depurar pods na documentação do Kubernetes.
  • Atraso no período de sincronização e latência de novas métricas: essas latências são normais. Aguarde a conclusão do período de sincronização ou a criação da nova série temporal de métrica personalizada.
  • Cálculo de várias métricas: esse é o comportamento esperado. Se o escalonamento vertical estiver ocorrendo com base em uma métrica (como solicitações por segundo), ele vai substituir corretamente o cálculo mais baixo de outra métrica (como CPU).

O HorizontalPodAutoscaler não consegue reduzir escala vertical

Sintomas

O HorizontalPodAutoscaler escalona verticalmente a carga de trabalho, mas não consegue reduzir o escalonamento, mesmo quando métricas como a utilização da CPU estão baixas.

Causa

Esse comportamento foi projetado para evitar o escalonamento vertical e a redução de escala vertical rápidos com base em informações incompletas. Os principais motivos são:

  • Uso de várias métricas: o HorizontalPodAutoscaler é escalonado com base na métrica que exige o maior número de réplicas. Se você tiver várias métricas, a carga de trabalho não reduzir escala vertical vertical, a menos que todas as métricas indiquem que menos réplicas são necessárias. Uma métrica que exige uma contagem alta de réplicas impede a redução da escala, mesmo que outras estejam baixas.
  • Métricas indisponíveis: se alguma métrica ficar indisponível (geralmente aparecendo como <unknown>), o HorizontalPodAutoscaler se recusará a reduzir a carga de trabalho. Não é possível determinar se a métrica está ausente porque o uso é realmente zero ou porque o pipeline de métricas está corrompido. Esse problema é comum com métricas personalizadas baseadas em taxa (por exemplo, messages_per_second), que podem parar de gerar relatórios de dados quando não há atividade, fazendo com que o HorizontalPodAutoscaler veja a métrica como indisponível e interrompa as operações de redução de escala.
  • Atraso na redução da escala da política de escalonamento: o campo behavior do HorizontalPodAutoscaler permite configurar políticas de escalonamento. A política padrão para reduzir escala vertical inclui uma janela de estabilização de 300 segundos (cinco minutos). Durante esse período, o HorizontalPodAutoscaler não reduz a contagem de réplicas, mesmo quando os valores das métricas caem abaixo do limite de destino. Essa janela evita flutuações rápidas, mas pode tornar a redução mais lenta do que o esperado.

Resolução

Tente as seguintes soluções:

  1. Para várias métricas e métricas indisponíveis, diagnostique a métrica que está causando problemas:

    kubectl describe hpa HPA_NAME -n NAMESPACE_NAME

    Na saída, procure na seção Metrics qualquer métrica com o status <unknown> e na seção Events avisos como FailedGetCustomMetric ou FailedGetExternalMetric. Para uma depuração detalhada do pipeline, consulte a seção Resolver problemas de métricas personalizadas e externas.

  2. Se uma métrica ficar indisponível durante períodos de baixo tráfego (comum com métricas baseadas em taxa), tente uma das seguintes soluções:

    • Use métricas baseadas em indicadores em vez de métricas baseadas em taxas sempre que possível. Uma métrica de medição, como o número total de mensagens em uma fila (por exemplo, subscription ou num_undelivered_messages), informa um valor de forma consistente, mesmo que seja 0, permitindo que o HorizontalPodAutoscaler tome decisões de escalonamento de maneira confiável.
    • Verifique se a fonte da métrica informa valores zero. Se você controlar a métrica personalizada, configure-a para publicar um 0 durante períodos de inatividade, em vez de não enviar dados.

  3. Para atrasos na redução da escala da política de escalonamento, se a janela de estabilização padrão de cinco minutos para reduções for muito longa, personalize-a. Inspecione a seção spec.behavior.scaleDown do manifesto HorizontalPodAutoscaler. Você pode diminuir o stabilizationWindowSeconds para permitir que o escalonador automático reduzir escala vertical mais rapidamente após a queda das métricas. Para mais informações sobre como configurar essas políticas, consulte Políticas de escalonamento na documentação do Kubernetes.

Resolver problemas de escalonamento de cargas de trabalho do GKE de e para zero usando o HPA

Esta seção ajuda você a diagnosticar problemas ao configurar cargas de trabalho para escalonar para e de zero usando o HPA (minReplicas: 0) no GKE 1.37 ou mais recente.

A carga de trabalho não reduz a escala a zero

Se a carga de trabalho permanecer em uma ou mais réplicas quando a demanda cair para zero, verifique o seguinte:

  1. Verifique minReplicas: confira se o par campo-valor minReplicas: 0 está definido no manifesto HorizontalPodAutoscaler.
  2. Verifique os tipos de métricas: o HPA não pode ser escalonado para zero se usar apenas métricas de CPU ou memória (Resource). É necessário configurar pelo menos uma métrica External ou Object.
  3. Verificar várias métricas: o HPA faz o escalonamento com base na métrica que exige a maior contagem de réplicas. Se você configurar várias métricas, a carga de trabalho não será escalonada para zero, a menos que todas as métricas monitoradas sejam avaliadas como zero.
  4. Aguarde a janela de estabilização da redução da escala vertical: por padrão, o GKE aguarda cinco minutos (scaleDown.stabilizationWindowSeconds: 300) de demanda zero contínua antes de reduzir a escala de uma para zero réplicas.
  5. Verifique se há métricas indisponíveis: se o valor de alguma métrica aparecer como <unknown>, o HPA vai pausar as operações de redução de escala para evitar uma redução prematura. Para mais informações, consulte Resolver problemas de falha na redução de escala vertical do autoescalonador horizontal de pods.

A carga de trabalho não é escalonar verticalmente a partir de zero

Se a carga de trabalho permanecer em zero réplicas quando a demanda aumentar, verifique o seguinte:

  1. Inspecione o HorizontalPodAutoscaler: execute o comando kubectl describe hpa HPA_NAME e verifique as seguintes seções na saída:

    • Seção de métricas: verifique se o valor da métrica é maior que zero e se não é exibido como <unknown>. Se a métrica estiver ausente ou não estiver sendo atualizada, verifique se a origem externa (como o Pub/Sub) está publicando eventos e se o Cloud Monitoring está recebendo esses eventos.
    • Seção "Condições":
      • Estado íntegro de zero réplica: verifique se as condições mostram AbleToScale: True, ScalingActive: True e ScaledToZero: True (com o motivo ScaledToZero). Nesse estado, o GKE escalona automaticamente a carga de trabalho quando a demanda aumenta.
      • Substituição externa detectada: verifique se o valor da condição ScalingActive é False com o motivo ScalingDisabledExternalScaleToZero ou ScalingDisabledReplicaCountZero, o que indica que a carga de trabalho foi escalonada manualmente para zero. Por exemplo, a carga de trabalho foi escalonada manualmente com o comando kubectl scale, que pausa o escalonamento automático para evitar alterações conflitantes.

    • Resolução: para retomar o escalonamento automático, faça o escalonamento manual da implantação de volta para uma ou mais réplicas:

      kubectl scale deployment DEPLOYMENT_NAME --replicas=1

  2. Verifique a latência de inicialização a frio: se a carga de trabalho começar lentamente, o provisionamento de nós poderá estar causando atraso. Para garantir que a capacidade de computação em espera esteja pronta ao escalonar do zero, use os buffers de capacidade.

A seguir