Coletar registros de eventos do escalonador automático horizontal de pods

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

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. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

Ative as APIs

Ative as APIs GKE e Cloud Logging.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar as APIs

Configurar o Cloud Shell

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

No console do Cloud de Confiance , ative o Cloud Shell.

Ativar o 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 usando papéis personalizados ou 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.
  • Verifique se você tem um escalonador automático horizontal de pods que quer monitorar. Verifique se os campos do escalonador automático horizontal de pods não incluem dados sensíveis.

Custos

Os preços do Cloud Logging se aplicam quando você ativa o serviço e coleta registros de decisão do autoescalador horizontal de pods.

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

Para criar um cluster com os registros de decisão do 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ões do KCP_HPA em um cluster atual, execute o seguinte comando:

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

Substitua:

  • CLUSTER_NAME: nome do cluster que você quer criar ou atualizar.
  • PROJECT_ID: o ID do projeto do Cloud de Confiance .
  • 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.

Recupere a configuração de geração de registros atualizada 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á o seguinte:

SYSTEM_COMPONENTS,APISERVER,CONTROLLER_MANAGER,SCHEDULER,KCP_HPA

Ver registros do escalonador automático horizontal de pods no console do Cloud de Confiance

É possível monitorar o comportamento do escalonador automático horizontal de pods no consoleCloud de Confiance . Essa visualização oferece uma maneira conveniente de conferir os mesmos registros de recomendações atômicas e finais disponíveis no Cloud Logging, sem sair do contexto da sua carga de trabalho.

Para conferir os registros do escalonador automático horizontal de pods no console do Cloud de Confiance , siga estas etapas:

  1. No console do Cloud de Confiance , acesse a página Cargas de trabalho:

    Acesse "Cargas de trabalho"

  2. Selecione a carga de trabalho gerenciada pelo escalonador automático horizontal de pods.

  3. Clique na guia Escalonamento.

Nessa guia, você encontra informações relacionadas ao escalonamento, incluindo uso de recursos, dados de eficiência e registros. Os dados nessa guia podem ajudar você a identificar a configuração mais eficaz para o escalonamento automático das suas cargas de trabalho. Na seção Registros, você encontra as mesmas informações de Registros e filtra esses registros por tipo, incluindo "Evento", "Recomendação final" e "Recomendação atômica". Para mais detalhes sobre os diferentes registros, consulte Tipos de registros.

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: nome do cluster que você quer criar ou atualizar.
  • PROJECT_ID: o ID do projeto do Cloud de Confiance .
  • LOCATION: regiões ou zonas do Compute do cluster.

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

Recupere a configuração de geração de registros atualizada 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á o seguinte:

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", que está no 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 registros, além de 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 cada um, seu registro KCP_HPA vai receber oito entradas de eventos de decisão 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 o 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 para ela.
  • status: condições de status em relação à 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 do cálculo.
summary O campo de resumo contém informações sobre o resultado da recomendação, incluindo o número de réplicas sugerido. Se uma recomendação não puder ser proposta, uma mensagem de erro será exibida. O campo summary contém os seguintes subcampos:
  • dampening: o HPA aplica amortecimento à recomendação e à direção dela para tentar reduzir a magnitude de um possível escalonamento. O amortecimento pode acontecer das seguintes maneiras:
    • up: uma direção de aumento significa que o HPA assume pods com métricas ausentes com 100% de uso da métrica.
    • down: uma direção de redução de taxa significa que o HPA assume pods com métricas ausentes ou pods não prontos que consomem 0% de uso da métrica.
    • none: nenhum amortecimento é aplicado.
  • override: mensagem que fornece um motivo quando a recomendação proposta pelo HPA não é aplicada (por exemplo, devido à tolerância) ou none se nenhuma substituição ocorrer.
  • 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 a implementa. A ativação 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 de pods diferente do número de pods em execução, o escalonador automático horizontal de pods vai acionar um evento de escalonamento vertical ou redução para ajustar a implantação de acordo.

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

Campo Descrição
start_time Indica quando o 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 de o HPA calcular e aplicar 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 ocorrer.
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 da 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 das limitações 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 de réplicas após a estabilização.
  • reason: tipo de estabilização aplicada: 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 pelo 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 escalonar em uma determinada direção. MaxChange corresponde a MaxChangePolicySelect; MinChange corresponde a MinChangePolicySelect. Se o escalonamento estiver desativado, 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 ação falhou.
actuation_time Carimbo de data/hora da ação em caso de sucesso.
actuation_latency_seconds Tempo decorrido, em segundos, desde o início do cálculo da recomendação até a ação ser concluída.

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 a eventos do escalonador automático horizontal de pods.

Nenhum evento

Se você não encontrar eventos de decisão do escalonador automático horizontal de pods, verifique se fez o seguinte:

  • 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 você ainda não encontrar nenhum registro do KCP_HPA, entre em contato com o suporte doCloud de Confiance .

A seguir