Conferir eventos do Escalonador automático horizontal de pods

Esta página fornece informações sobre eventos de decisão emitidos pelo Horizontal Pod Autoscaler no Google Kubernetes Engine (GKE). Ao analisar esses eventos, você pode ter insights sobre como o controlador do escalonador automático horizontal de pods gerencia o dimensionamento da carga de trabalho e entender o processo de tomada de decisão por trás das ações.

O escalonador automático horizontal de pods emite eventos de decisão, que são armazenados como entradas de registro no Cloud Logging.

Antes de começar

Siga os seguintes pré-requisitos:

Escolha ou crie um projeto

Você pode usar um projeto existente ou criar um novo para fins deste tutorial.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

Ativar as APIs

Enable the GKE, and Cloud Logging APIs.

Enable the APIs

Configurar o Cloud Shell

Neste tutorial, use o Cloud Shell para executar os comandos gcloud e kubectl. O Cloud Shell é um ambiente de shell para gerenciar recursos hospedados no Google Cloud. Ele vem pré-instalado com a CLI do Google Cloud e a ferramenta de linha de comando kubectl.

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

Uma sessão do Cloud Shell é aberta dentro de um quadro inferior no console.

Antes de executar comandos neste tutorial, verifique se o projeto padrão está definido como ID do projeto em que você quer implantar o aplicativo de amostra. Execute o seguinte comando no Cloud Shell, caso ele ainda não esteja definido:

gcloud config set project PROJECT_ID

Substitua PROJECT_ID pelo ID do projeto.

Papéis e permissões necessárias

Para receber as permissões necessárias para ativar a geração de registros e acessar e processar registros, 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 por meio de papéis personalizados ou de outros papéis predefinidos.

Requisitos

  • Seu cluster do GKE precisa estar executando a versão 1.31.5-gke.1090000 ou mais recente, ou 1.32.1-gke.1260000 ou mais recente.
  • Ative o Cloud Logging no cluster do GKE. Os preços do Cloud Logging são aplicáveis.

Ativar eventos de decisão do Escalonador automático horizontal de pods

Para criar um novo cluster com os registros de decisão KCP_HPA ativados, execute o seguinte comando:

gcloud container clusters create CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID \
    --logging=SYSTEM,KCP_HPA

Para ativar os registros de decisão KCP_HPA em um cluster, execute o seguinte comando:

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID \
    --logging=SYSTEM,KCP_HPA

Substitua:

  • CLUSTER_NAME: o nome do cluster que você quer criar ou atualizar.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • LOCATION: regiões ou zonas do Compute do cluster.

Esses comandos permitem exportar os registros gerados por KCP_HPA e salvá-los no destino logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fhpa-controller" no Cloud Logging.

Extraia a configuração atualizada de geração de registros do cluster e analise a lista de registros para garantir que o registro KCP_HPA esteja ativado:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=loggingConfig \
    --format='csv[delimiter=",",no-heading](componentConfig.enableComponents)'

O resultado será assim:

SYSTEM_COMPONENTS,APISERVER,CONTROLLER_MANAGER,SCHEDULER,KCP_HPA

Desativar eventos de decisão do Escalonador automático horizontal de pods

Atualize um cluster para remover o componente KCP_HPA da flag --logging:

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID \
    --logging=SYSTEM

Substitua:

  • CLUSTER_NAME: o nome do cluster que você quer criar ou atualizar.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • LOCATION: regiões ou zonas do Compute do cluster.

Esse comando desativa a exportação dos registros gerados por KCP_HPA. Não é possível recuperá-los usando o filtro logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fhpa-controller" no Cloud Logging.

Extraia a configuração atualizada de geração de registros do cluster e analise a lista de registros para garantir que o registro KCP_HPA esteja desativado:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=loggingConfig \
    --format='csv[delimiter=",",no-heading](componentConfig.enableComponents)'

O resultado será assim:

SYSTEM_COMPONENTS,APISERVER,CONTROLLER_MANAGER,SCHEDULER

Tipos de registros

Os eventos de decisão do escalonador automático horizontal de pods são armazenados no Cloud Logging, no local logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fhpa-controller" do bucket _Default no mesmo projeto do cluster do GKE. Todos os eventos registrados estão no formato JSON e podem ser encontrados no campo jsonPayload de uma entrada de registro.

Entenda as necessidades de armazenamento dos possíveis volumes de registro, além das implicações de desempenho ou custo. Os exemplos a seguir explicam com que frequência o Escalonador automático horizontal de pods gera cada tipo de evento de decisão:

  • Recomendação atômica: o escalonador automático horizontal de pods gera um evento de recomendação atômica a cada 15 segundos para cada métrica monitorada por cada objeto HPA no cluster. Por exemplo, se você tiver dois objetos HPA no cluster e cada um deles monitorar três métricas, seis recomendações atômicas serão registradas a cada 15 segundos.

  • Recomendação final: o escalonador automático horizontal de pods gera um evento de recomendação final a cada 15 segundos para cada objeto HPA no cluster. Por exemplo, se você tiver dois objetos HPA no cluster, duas recomendações finais serão registradas a cada 15 segundos.

No total, com dois objetos HPA que monitoram três métricas, seu registro KCP_HPA vai receber oito entradas de eventos de decisão no total a cada 15 segundos.

Recomendação atômica

Um registro de recomendação atômica descreve uma recomendação com base em uma métrica individual especificada no Escalonador automático horizontal de pods.

Um registro atômico inclui os seguintes campos:

Campo Descrição
start_time Indica quando a HPA começou a calcular uma recomendação.
hpa O nome do objeto HPA associado à recomendação.
pod_count Indica o número total de pods associados ao HPA ao fazer a recomendação. Esse número também inclui pods prontos, não prontos e ignorados.
metric Fornece informações sobre a especificação e o status da métrica usada para a recomendação. O campo metric contém os seguintes subcampos:
  • index: índice da métrica na matriz Spec metrics.
  • type: tipo de métrica com valores do MetricSourceType (por exemplo, "Resource", "External").
  • spec: nome da métrica e uma meta definida nela.
  • status: Condições de status relacionadas à escalonabilidade e às limitações de escalonamento.
  • newest_sample_time: carimbo de data/hora da amostra de métrica mais recente.
  • newest_sample_age_seconds: idade da amostra mais recente, medida em segundos, desde o início do cálculo da recomendação. Um valor negativo significa que a amostra de métricas é anterior ao início da computação.
summary O campo de resumo contém informações sobre o resultado da recomendação, incluindo o número de réplicas sugerido. Se não for possível propor uma recomendação, uma mensagem de erro vai aparecer. O campo summary contém os seguintes subcampos:
  • dampening: o HPA aplica atenuação à recomendação e à direção dela para tentar reduzir a magnitude de uma possível escala. A atenuação pode acontecer das seguintes maneiras:
    • up: uma direção de redução significa que o HPA assume pods de métricas ausentes com 100% de uso da métrica.
    • down: uma direção de atenuação para baixo significa que o HPA assume pods de métricas ausentes ou pods não preparados que consomem 0% da métrica.
    • none: nenhum amortecimento é aplicado.
  • override: mensagem que informa o motivo quando a recomendação proposta pelo HPA não é aplicada (por exemplo, devido à tolerância) ou none se não houver substituição.
  • result: resultado da recomendação. Ele propõe um número recomendado de réplicas ou mostra uma mensagem de erro se a recomendação não puder ser calculada.

Exemplo de registro de recomendação atômica:

{
  "insertId": "xiu4bty9k5b279wu",
  "jsonPayload": {
    "instance": {
      "vm_name": "my-unique-vm-identifier",
      "zone": "us-central1-a"
    },
    "atomicRecommendation": {
      "startTime": "2025-02-06T20:07:00.573419526Z",
      "hpa": "gke-managed-cim/kube-state-metrics",
      "metric": {
        "newestSampleAgeSeconds": -39.573419526,
        "status": {
          "averageValue": "25849856"
        },
        "newestSampleTime": "2025-02-06T20:06:21Z",
        "type": "Resource",
        "spec": {
          "target": {
            "averageValue": "400Mi"
          },
          "name": "memory"
        }
      },
      "podCount": {
        "ready": 1,
        "total": 1
      },
      "summary": {
        "override": "none",
        "replicas": 1,
        "dampening": "none"
      }
    }
  },
  "resource": {
    "type": "k8s_control_plane_component",
    "labels": {
      "project_id": "my-project-id",
      "cluster_name": "my-cluster",
      "location": "us-central1-a",
      "component_location": "us-central1-a",
      "component_name": "hpa-controller"
    }
  },
  "timestamp": "2025-02-06T20:07:00.593777835Z",
  "severity": "INFO",
  "labels": {
    "compute.googleapis.com/resource_name": "my-unique-vm-identifier"
  },
  "logName": "projects/my-project-id/logs/container.googleapis.com%2Fhpa-controller",
  "sourceLocation": {
    "file": "event_logger.go",
    "line": "61"
  },
  "receiveTimestamp": "2025-02-06T20:07:05.284753647Z"
}

Recomendação final

Um registro de recomendação final descreve uma recomendação consolidada proposta pelo Escalonador automático horizontal de pods. O Escalonador automático horizontal de pods combina todas as recomendações atômicas de diferentes métricas para criar uma recomendação final e aciona as recomendações finais. Acionamento significa que o HPA instrui a implantação a ajustar o número de réplicas para corresponder ao valor recomendado. Se a recomendação final sugerir um número diferente de pods em execução, o escalonador automático horizontal de pods vai acionar um evento de escalonamento para ajustar a implantação.

Um registro de recomendação final inclui os seguintes campos:

Campo Descrição
start_time Indica quando a HPA começou a calcular uma recomendação.
hpa O nome do objeto HPA associado à recomendação.
target_ref Indica o objeto ScaleTargetRef do HPA associado a uma recomendação.
configured_size O último número registrado de réplicas antes que a HPA calcule e aplique essa recomendação.
top_level_override Fornece um motivo se a recomendação proposta pelo HPA não for aplicada (por exemplo, devido à tolerância) ou none se nenhuma substituição acontecer.
top_level_limit Fornece um motivo se a recomendação proposta pelo HPA precisar ser ajustada (por exemplo, devido ao número de réplicas definidas pelos campos MinReplicas ou MaxReplicas na especificação do HPA).
leading_metric_index O índice de métrica principal na matriz Spec metrics é a métrica cuja recomendação atômica associada é usada como a recomendação final.
normalization Fornece um resumo da estabilização e da limitação da seguinte forma, se houver:

stabilization: descreve o estado de estabilização, se ele foi aplicado. A estabilização é usada para restringir a oscilação da contagem de réplicas quando as métricas usadas para escalonamento continuam variando. O campo stabilization consiste nos seguintes subcampos:

  • replicas: número da réplica após a estabilização.
  • reason: tipo de estabilização aplicado, scaleUp ou scaleDown.
  • stabilization_window: período de estabilização associado, em segundos.
  • replicas_before_stabilization: número de réplicas recomendado antes da estabilização.

limitation: descreve como as limitações de escalonamento são processadas se forem aplicadas. Esse comportamento modifica as recomendações propostas pela HPA com base nas limitações em vigor. O campo limitation consiste nos seguintes subcampos:

  • replicas: número de réplicas após a limitação.
  • reason: motivo para não escalonar além da contagem mínima ou máxima de réplicas.
  • scaling_policy: a política de escalonamento aplicada.
  • selectPolicy: especifica como uma política é selecionada ao dimensionar em uma determinada direção. MaxChange corresponde a MaxChangePolicySelect e MinChange corresponde a MinChangePolicySelect. Se a escala estiver desativada, o campo selectPolicy não vai estar presente.
  • replicas_before_limitation: número de réplicas recomendado antes da limitação.
replicas Número de réplicas recomendado.
actuation_error Uma mensagem de erro associada à falha, se a acionamento tiver falhado.
actuation_time Carimbo de data/hora da ativação em caso de sucesso.
actuation_latency_seconds Tempo decorrido, em segundos, desde o início do cálculo da recomendação até a ativação.

Exemplo de registro de recomendação final:

{
  "insertId": "qzyv7alfv1sm19ns",
  "jsonPayload": {
    "finalRecommendation": {
      "actuationTime": "2025-02-06T20:06:57.487786873Z",
      "targetRef": {
        "name": "kube-state-metrics",
        "kind": "StatefulSet",
        "apiVersion": "apps/v1"
      },
      "topLevelLimit": "none",
      "hpa": "gke-managed-cim/kube-state-metrics",
      "topLevelOverride": "noRecommendation",
      "replicas": 1,
      "configuredSize": 1,
      "actuationLatencySeconds": 0.003722451,
      "startTime": "2025-02-06T20:06:57.484064422Z"
    },
    "instance": {
      "vm_name": "my-unique-vm-identifier",
      "zone": "us-central1-a"
    }
  },
  "resource": {
    "type": "k8s_control_plane_component",
    "labels": {
      "cluster_name": "my-cluster",
      "component_location": "us-central1-a",
      "component_name": "hpa-controller",
      "location": "us-central1-a",
      "project_id": "my-project-id"
    }
  },
  "timestamp": "2025-02-06T20:06:57.488193527Z",
  "severity": "INFO",
  "labels": {
    "compute.googleapis.com/resource_name": "my-unique-vm-identifier"
  },
  "logName": "projects/my-project-id/logs/container.googleapis.com%2Fhpa-controller",
  "sourceLocation": {
    "file": "event_logger.go",
    "line": "61"
  },
  "receiveTimestamp": "2025-02-06T20:06:57.844898727Z"
}

Solução de problemas

Esta seção descreve problemas e etapas de resolução relacionados aos eventos do Escalonador automático horizontal de pods.

Não há eventos

Se você não encontrar eventos de decisão do Escalonador automático horizontal de pods, verifique se cumpriu todas as seguintes condições:

  • Você ativou o Cloud Logging para o cluster.
  • Você ativou os registros KCP_HPA para o cluster.
  • Você implantou pelo menos um objeto hpa configurado corretamente no cluster.

Para conferir a configuração do objeto hpa, execute o seguinte comando:

  kubectl describe hpa $HPA_NAME

Se ainda não houver registros KCP_HPA, entre em contato com o Google Cloud Suporte.

A seguir