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), suas 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ê garante 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. Ele também ajuda 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, por exemplo, 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 Google Cloud .

Descrever 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 ou motivos de erro específicos, como FailedGetScale ou FailedGetResourceMetric.

Verificar o manifesto do HorizontalPodAutoscaler

O manifesto YAML do objeto HorizontalPodAutoscaler permite ver 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 de réplica mínima e máxima.
    • 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 o qual 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 registros de eventos

Para ter mais informações sobre o objeto HorizontalPodAutoscaler, use os seguintes tipos de registros:

  • Ver 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 fornecem informações estruturadas e legíveis para humanos que explicam como o HorizontalPodAutoscaler calcula uma recomendação, oferecendo insights detalhados sobre o processo de tomada de decisões.

Resolver erros de configuração do HorizontalPodAutoscaler

As seções a seguir abordam configurações incorretas no manifesto HorizontalPodAutoscaler, como campos digitados incorretamente, metas de métricas inválidas 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 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ê 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 em outro, ou vice-versa. Verifique o namespace dos dois objetos e confira se eles correspondem.

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

Métricas inválidas

Sintomas

Se o HorizontalPodAutoscaler não conseguir calcular as réplicas necessárias devido a um problema de configuração, a seção Events vai mostrar o motivo 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 do HorizontalPodAutoscaler. Por exemplo, você pode ter especificado um type de Utilization, mas fornecido um valor de destino de averageValue em vez de averageUtilization.

Resolução

Corrija o manifesto HorizontalPodAutoscaler para que o valor do campo target se alinhe à 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 do rótulo não permitido 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 no próprio campo spec.metrics. Portanto, a fusão permite que o objeto HorizontalPodAutoscaler escolhido considere 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, extraia 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 erros de carga de trabalho e 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 vê 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 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 segmentados 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 a carga de trabalho, verifique se você especificou solicitações de recursos para cada contêiner na 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 um para um 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 sua 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 atualizado do serviço ou da implantação.

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 de métricas ou consultar um backend de métricas.

Resolver problemas com 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 componentes: controlador do HPA, servidor da API do 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 aparece 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 principal da API Kubernetes para veicular métricas. Essa ação é a maneira mais direta de verificar 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 seu adaptador tenha falhado ou esteja mal configurado. Verifique os registros do pod do adaptador no namespace kube-system ou custom-metrics para 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, prossiga para a próxima etapa.

  2. Consultar a API de métricas diretamente: se o adaptador estiver disponível, ignore o HorizontalPodAutoscaler e peça sua métrica diretamente à API do 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 do 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 sendo executados.
    • 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 do 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á detectando:

        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 a outras partes do cluster, incluindo o servidor da API Kubernetes.
        • ADAPTER_NAMESPACE: o namespace em que o serviço de 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 seu 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

        Analise as políticas para verificar se elas permitem o tráfego de entrada do plano de controle ou do servidor da 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 origem da métrica.

      • Problemas com o pod do adaptador: inspecione os registros do pod do adaptador de métricas ou dos pods para 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 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).

      • Sem dados na origem: a métrica pode não existir 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 do cluster ou um reparo do plano de controle).
  • Os pods do adaptador de métricas (por exemplo, custom-metrics-stackdriver-adapter) estão com problemas, 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 o problema 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 brevemente indisponível durante esses períodos.

    4. Analise os registros de auditoria do Cloud em busca de 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 Depurar pods 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 de métricas 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 nenhuma 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 ao Cloud Monitoring durante o período em que os avisos do HorizontalPodAutoscaler ocorreram.
  4. Investigue erros: verifique os registros do aplicativo do mesmo período em busca de 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 inesperados, mas saudáveis

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 faz escalonamento

Sintomas

O HorizontalPodAutoscaler parece íntegro, as condições dele informam True e não mostram erros nos eventos. No entanto, ela 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 a meta 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 presos com um status Pending ou 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 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 da 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 maior valor 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 uma necessidade de 9 réplicas, mas uma métrica de solicitações por segundo calcular uma necessidade de 15, o HorizontalPodAutoscaler vai escalonar o Deployment 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 a métrica sair 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 da nova métrica: 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 a carga de trabalho verticalmente, 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 rápido para cima e para baixo ou o escalonamento para baixo com base em informações incompletas. Os principais motivos são:

  • Usar várias métricas: o HorizontalPodAutoscaler faz o escalonamento 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 alta contagem 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 exibida 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á com falha. 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 de redução da política de escalonamento: o campo behavior do HorizontalPodAutoscaler permite configurar políticas de escalonamento. A política padrão de redução de escala 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 ficam abaixo do limite desejado. Essa janela evita flutuações rápidas, mas pode tornar o redução de escala 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 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 depuração detalhada de pipeline, consulte a seção Resolver problemas com métricas personalizadas e externas.

  2. Para métricas indisponíveis, 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 indicador, 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 esse valor 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 de redução 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. É possível diminuir o stabilizationWindowSeconds para que o escalonador automático reduzir escala vertical 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.

A seguir

  • Se você não encontrar uma solução para seu problema na documentação, consulte Receber suporte para mais ajuda, incluindo conselhos sobre os seguintes tópicos: