Esta página foi traduzida pela API Cloud Translation.

Resolver problemas de escalonamento automático horizontal de pods

Autopilot Standard

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 esta página 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 de Escalonador automático horizontal de pods.

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.

Se você já teve sintomas ou recebeu uma mensagem de erro, use a tabela a seguir para encontrar a orientação certa:

Sintoma	Possível solução
Sem escalonamento, mas as condições do HorizontalPodAutoscaler são `True`	Resolver problemas em um HorizontalPodAutoscaler íntegro, mas sem resposta
Você vê uma mensagem de erro específica nos eventos do HorizontalPodAutoscaler	Resolver problemas comuns do escalonador automático horizontal de pods
Métrica `<unknown>`	Resolver problemas com métricas externas e personalizadas
Não está reduzindo a escala vertical	Resolver problemas de falha na redução do escalonamento automático horizontal de pods

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:
- Inspecionar recursos do GKE: Leitor do GKE (roles/container.viewer)
- Ver registros do cluster: Visualizador de registros (roles/logging.viewer)
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 .

Verificar o status e a configuração do escalonador automático horizontal de pods

Comece a solução de problemas inspecionando a integridade e a configuração do objeto HorizontalPodAutoscaler. Essa verificação inicial ajuda a identificar e resolver configurações incorretas básicas, que são uma causa raiz comum de problemas de escalonamento.

Descrever o HorizontalPodAutoscaler

Para conferir os cálculos em tempo real e as decisões de escalonamento recentes do HorizontalPodAutoscaler, use o comando kubectl describe hpa. Esse comando fornece um resumo do objeto HorizontalPodAutoscaler e um registro Events útil para diagnosticar problemas:

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á assim:

Name:                                                  php-apache-hpa
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: esta seção mostra os valores atuais das métricas em comparação com as metas. Marque aqui para conferir se o HorizontalPodAutoscaler está recebendo dados. 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: essa verificação de integridade de alto nível 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: esta seção 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, que ajudam a descobrir a origem do problema.

Verificar o status do HorizontalPodAutoscaler em implantações

Para verificar o status dos objetos HorizontalPodAutoscaler usados com suas implantações, use o console Google Cloud :

No console Google Cloud , acesse a página Cargas de trabalho.

Acesse "Cargas de trabalho"
Clique no nome da implantação.
Acesse a guia Detalhes e encontre a seção Escalonamento automático.
Revise o valor na linha Status:
- Uma marca de seleção verde significa que o HorizontalPodAutoscaler está configurado e pode ler as métricas dele.
- Um triângulo amarelo significa que o HorizontalPodAutoscaler está configurado, mas está com problemas para ler as métricas. Esse é um problema comum com métricas personalizadas ou externas. Para resolver esse problema, diagnostique por que as métricas estão indisponíveis. Para mais informações, consulte a seção Solução de problemas com métricas personalizadas e externas.

Para outros tipos de carga de trabalho, como StatefulSets, ou para mais detalhes, confira o manifesto do objeto HorizontalPodAutoscaler.

Verifique 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

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

Acessar o navegador de objetos
Na lista Tipos de objeto, marque a caixa de seleção HorizontalPodAutoscaler e clique em OK.
Navegue até o grupo de APIs autoscaling e clique na seta de expansão de HorizontalPodAutoscaler.
Clique no nome do objeto HorizontalPodAutoscaler que você quer inspecionar.
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 deve escalonar.
- minReplicas e maxReplicas: as configurações de réplica mínima e máxima.
- metrics: as métricas que você configurou para escalonamento (por exemplo, utilização da CPU ou métricas personalizadas).
status (o estado ativo do HorizontalPodAutoscaler):
- currentMetrics: os valores de métricas 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: a seção mais valiosa para a solução de problemas. Esta seção 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.

Usar recursos avançados de geração de registros

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

Ver eventos do escalonador automático horizontal de pods no Cloud Logging: use um filtro de registros para encontrar todos os eventos do escalonador automático horizontal de pods de um cluster específico. Exemplo:
1. No console do Google Cloud , acesse a página Análise de registros.
  
  Acessar o Explorador 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 do escalonador automático horizontal de pods: esses registros fornecem informações estruturadas e legíveis por humanos que explicam como o HorizontalPodAutoscaler calcula uma recomendação, oferecendo insights detalhados sobre o processo de tomada de decisões.

Resolver problemas de um HorizontalPodAutoscaler íntegro, mas sem resposta

Esta seção ajuda você a diagnosticar por que o HorizontalPodAutoscaler pode não estar acionando ações de escalonamento, mesmo quando parece íntegro e não informa erros no status ou eventos.

Sintomas:

O HorizontalPodAutoscaler parece íntegro, 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 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 escalonador automático horizontal de pods não escalonar verticalmente.
Pods não prontos: o escalonador automático horizontal de pods 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. É normal haver um atraso de 15 a 30 segundos entre uma métrica cruzar o limite e o início de uma ação de escalonamento.
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 Escalonador automático horizontal de pods 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 escalonador automático horizontal de pods vai dimensionar 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 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).

Resolver erros comuns do escalonador automático horizontal de pods

As seções a seguir fornecem soluções para mensagens de erro e motivos de eventos específicos que podem aparecer ao inspecionar o status do HorizontalPodAutoscaler. Normalmente, essas mensagens estão na seção Events da saída do comando kubectl describe hpa.

Resolver problemas de configuração do escalonador automático horizontal de pods

Uma configuração incorreta no manifesto HorizontalPodAutoscaler, como um campo digitado incorretamente ou configurações conflitantes, causa os erros nesta seção.

Erro: métricas inválidas

Esse erro pode aparecer quando a configuração de uma métrica em um HorizontalPodAutoscaler está sintaticamente incorreta ou inconsistente.

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 segmentação 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.

Erro: vários serviços selecionando o mesmo destino

Esse erro pode aparecer ao usar o escalonamento automático com base no tráfego que tem uma configuração de serviço incorreta para o HorizontalPodAutoscaler.

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:

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á assim:
```
{"app":"my-app", "env":"prod"}
```
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"} corresponderiam aos rótulos de Pod de exemplo.
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.
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.

Erro: o rótulo 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:

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

Problema: vários HorizontalPodAutoscalers segmentando a mesma carga de trabalho

Configurar vários objetos HorizontalPodAutoscaler para gerenciar a mesma carga de trabalho causa um comportamento de escalonamento conflitante e imprevisível.

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 automático 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:

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.
Consolide as métricas em um único objeto HorizontalPodAutoscaler:
1. Escolha um objeto HorizontalPodAutoscaler para manter. É esse HorizontalPodAutoscaler 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.
Aplique as alterações:
```
kubectl apply -f MANIFEST_NAME
```
Substitua MANIFEST_NAME pelo nome do manifesto HorizontalPodAutoscaler que você decidiu manter.
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 destino

Os erros nesta seção são causados pelo escalonamento da implantação, do StatefulSet ou dos pods, não pelo objeto HorizontalPodAutoscaler em si.

Erro: não foi possível receber a escala atual do destino

Esse erro pode aparecer quando o HorizontalPodAutoscaler não consegue localizar ou acessar a carga de trabalho que ele precisa escalonar.

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 é causado por um problema 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:

Verifique o campo scaleTargetRef do manifesto do HorizontalPodAutoscaler: confira se o valor de name, kind e apiVersion no campo scaleTargetRef corresponde exatamente aos metadados da 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.
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.
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.

Erro: não foi possível calcular a contagem de réplicas

Esse erro pode aparecer quando o HorizontalPodAutoscaler precisa calcular o escalonamento com base na utilização de recursos, mas não tem as informações de linha de base necessárias dos pods.

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 escalonador automático horizontal de pods precisa calcular a utilização de recursos como uma porcentagem para escalonar a carga de trabalho, mas não pode fazer 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
spec:
  containers:
  - name: example-container
...
    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"

Erro: não foi possível buscar as métricas do pod

Esse erro pode aparecer quando há um problema ao recuperar as métricas necessárias para que um HorizontalPodAutoscaler tome decisões de escalonamento. Muitas vezes, isso está relacionado a definições de recursos de 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ê perceber 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.

Resolver problemas de erros de disponibilidade de dados e da API Metrics

As seções a seguir ajudam você a resolver erros que ocorrem quando o HorizontalPodAutoscaler tenta buscar dados de uma API de métricas. Esses problemas podem variar de falhas internas de comunicação do cluster, em que a API de métricas fica indisponível, até consultas inválidas que o provedor de métricas rejeita (geralmente vistas como erros HTTP no nível 400).

Erro: não foram encontradas versões de métricas disponíveis conhecidas

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 em estado ruim, 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:

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 da API pode ficar brevemente indisponível durante esses períodos.
2. 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.
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.

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.

Erro: a consulta não vai retornar 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:

Verifique a configuração:confira se os nomes e rótulos das métricas no objeto HorizontalPodAutoscaler correspondem exatamente aos emitidos pelo aplicativo.
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.
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 Horizontal Pod Autoscaler ocorreram.
Investigue erros:verifique os registros do aplicativo no 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 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:

Pipeline de métricas do HPA mostrando componentes: controlador do HPA, servidor da API Kubernetes, adaptador de métricas e origem de métricas.

Esta seção detalha como depurar esse pipeline, do adaptador à fonte 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:

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 o adaptador tenha falhado ou esteja mal configurado. Verifique os registros do pod do adaptador no namespace kube-system ou custom-metrics para encontrar 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.
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.

Observação: os comandos a seguir usam o processador JSON jq para imprimir a saída JSON. Se você não tiver o jq instalado, remova a seção | jq . dos comandos para conferir a resposta JSON bruta.

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 seus 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.
Analise a saída do 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 normalmente indica um problema de conectividade de rede, que geralmente é 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:
    
    Atenção: o comando a seguir substitui as portas permitidas atuais. Para evitar a interrupção da funcionalidade do cluster, inclua as portas existentes (normalmente tcp:443 para a API Kubernetes e tcp:10250 para o kubelet) mais o ADAPTER_PORT.
    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
```
    Revise as políticas para garantir que elas permitam 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 origem da métrica.
  - Problemas do pod do adaptador: inspecione os registros do pod ou dos pods do adaptador de métricas para encontrar 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: 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.