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

Esta página fornece 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ã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. 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 do GKE e do Cloud Logging.

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter a 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, você pode receber essa permissão com o papel de administrador de uso do serviço (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 Cloud de Confiance console, 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 com papéis personalizados ou outros papéis predefinidos.

Requisitos

  • O cluster do GKE precisa executar 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 são aplicáveis quando você ativa o Cloud Logging e coleta registros de decisão do escalonador automático 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 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 atual, 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 do. Cloud de Confiance
  • LOCATION: Regiões ou zonas do Compute para o cluster.

Esses comandos ativam a exportação dos registros gerados por KCP_HPA e os salvam em o 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 revise a lista de registros para verificar se o registro KCP_HPA está 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

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

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

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

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

    Acesse "Cargas de trabalho"

  2. Selecione a carga de trabalho que está sendo 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 a identificar a configuração mais eficaz para o escalonamento automático das cargas de trabalho. Na seção Registros , você encontra as mesmas informações dos registros e pode filtrar 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: o 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 para o cluster.

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

Recupere a configuração de geração de registros atualizada do cluster e revise a lista de registros para verificar se o KCP_HPA registro está 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 logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fhpa-controller" local 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 volumes de registro em potencial, 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 objeto HPA 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, o registro KCP_HPA log 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, recurso, externo).
  • spec: nome da métrica e um destino definido nessa métrica.
  • 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 o amortecimento à recomendação e à direção dela para tentar reduzir a magnitude de uma possível escala. O amortecimento pode acontecer das seguintes maneiras:
    • up: uma direção de amortecimento significa que o HPA assume pods de métricas ausentes com 100% de uso da métrica.
    • down: uma direção de amortecimento significa que o HPA assume pods de 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 coloca em prática. A atuaçã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 horizontal 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 HPA ScaleTargetRef associado a uma recomendação.
configured_size O último número registrado de réplicas antes que o 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 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 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 de estabilização e limitação da seguinte maneira, se presente:

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 flutuando. O campo stabilization consiste nos seguintes subcampos:

  • replicas: número de réplicas 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 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 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 atuação falhou.
actuation_time Carimbo de data/hora da atuação em caso de sucesso.
actuation_latency_seconds Tempo decorrido, em segundos, desde o início do cálculo da recomendação até a atuação ser bem-sucedida.

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 nenhum evento de decisão do escalonador automático horizontal de pods, verifique se você 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 KCP_HPA, entre em contato com o Cloud de Confiance suporte.

A seguir