Conferir 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, é possível 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. 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.

    6. Ative 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 shell para gerenciar recursos hospedados no Google Cloud. Ele vem pré-instalado com a Google Cloud CLI 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 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 Google Cloud .
    • LOCATION: regiões ou zonas do Compute para o 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á 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: nome do cluster que você quer criar ou atualizar.
    • PROJECT_ID: o ID do projeto do Google Cloud .
    • 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 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á 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" 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 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 cada, 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 não for possível propor uma recomendação, 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 de amortecimento significa que o HPA assume pods com métricas ausentes com 100% de uso da métrica.
      • down: uma direção de redução 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 da limitação da seguinte forma, 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 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 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.

    Não há eventos

    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 doGoogle Cloud .

    A seguir