Horizontal Pod Autoscaler イベントを表示する

Autopilot Standard

---

このページでは、Google Kubernetes Engine（GKE）の Horizontal Pod Autoscaler によって出力される決定イベントについて説明します。これらのイベントを分析することで、Horizontal Pod Autoscaler コントローラがワークロードのスケーリングを管理する方法に関する分析情報を取得し、アクションの背後にある意思決定プロセスを把握できます。

Horizontal Pod Autoscaler は、決定イベントを発行します。このイベントは、Cloud Logging のログエントリとして保存されます。

始める前に

次の前提条件を満たしていることを確認してください。

プロジェクトの選択または作成

既存のプロジェクトを使用することも、このチュートリアル用の新しいプロジェクトを作成することもできます。

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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

API を有効にする

Enable the GKE, and Cloud Logging APIs.

Enable the APIs

Cloud Shell を設定する

このチュートリアルでは、Cloud Shell を使用して gcloud コマンドと kubectl コマンドを実行します。Cloud Shell は、 Google Cloudでホストされているリソースを管理するためのシェル環境です。Google Cloud CLI と kubectl コマンドライン ツールがプリインストールされています。

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

コンソールの下部にあるフレーム内で Cloud Shell セッションが開きます。

このチュートリアルでコマンドを実行する前に、デフォルト プロジェクトがサンプルアプリをデプロイするプロジェクト ID に設定されていることを確認します。まだ設定していない場合は、Cloud Shell で次のコマンドを実行します。

gcloud config set project PROJECT_ID

PROJECT_ID を実際のプロジェクト ID に置き換えます。

必要なロールと権限

ログの生成を有効にしてログにアクセスして処理するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

• クラスタで Horizontal Pod Autoscaler イベントのロギングを有効にするには、Kubernetes Engine クラスタ管理者 （roles/container.clusterAdmin）が必要です。
• ログにアクセスし、ログ エクスプローラとログ分析を使用する: ログビューア （roles/logging.viewer）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

要件

• GKE クラスタでバージョン 1.31.5-gke.1090000 以降または 1.32.1-gke.1260000 以降を実行している必要があります。
• GKE クラスタで Cloud Logging を有効にします。Cloud Logging の料金が適用されます。

Horizontal Pod Autoscaler の決定イベントを有効にする

注意: 既存のクラスタには、特定のロギング コンポーネントがすでに構成されている場合があります。Google Cloud CLI または API 呼び出しを使用して既存のクラスタを更新する場合は、既存の構成が上書きされないように、更新リクエストに既存のロギング構成を含める必要があります。

注: Cloud Logging にログを送信する場合は、システムログを送信する必要があります。KCP_HPA などの追加ソースからのログを有効にする場合は、システムログ コンポーネントを有効にしてください。

KCP_HPA 意思決定ログを有効にして新しいクラスタを作成するには、次のコマンドを実行します。

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

既存のクラスタで KCP_HPA の決定ログを有効にするには、次のコマンドを実行します。

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

次のように置き換えます。

• CLUSTER_NAME: 作成または更新するクラスタの名前。
• PROJECT_ID: Google Cloud プロジェクト ID。
• LOCATION: クラスタのコンピューティング リージョンまたはゾーン。

これらのコマンドを使用すると、KCP_HPA によって生成されたログをエクスポートし、Cloud Logging 内の宛先 logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fhpa-controller" に保存できます。

クラスタの更新されたロギング構成を取得し、ログのリストを調べて、KCP_HPA ログが有効になっていることを確認します。

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

出力は次のようになります。

SYSTEM_COMPONENTS,APISERVER,CONTROLLER_MANAGER,SCHEDULER,KCP_HPA

Horizontal Pod Autoscaler の決定イベントを無効にする

注意: 既存のクラスタには、特定のロギング コンポーネントがすでに構成されている場合があります。Google Cloud CLI または API 呼び出しを使用して既存のクラスタを更新する場合は、既存の構成が上書きされないように、更新リクエストに既存のロギング構成を含める必要があります。

注: システムログは、トラブルシューティングとサポートに必要です。システム ログを無効にしている場合、GKE のカスタマー サポートはベスト エフォートで提供されるため、自社のエンジニアリング チームで別途対応する必要が生じる場合があります。

クラスタを更新して、--logging フラグから KCP_HPA コンポーネントを削除します。

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

次のように置き換えます。

• CLUSTER_NAME: 作成または更新するクラスタの名前。
• PROJECT_ID: Google Cloud プロジェクト ID。
• LOCATION: クラスタのコンピューティング リージョンまたはゾーン。

このコマンドは、KCP_HPA によって生成されたログのエクスポートを無効にします。Cloud Logging 内の logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fhpa-controller" フィルタを使用して取得することはできません。

クラスタの更新されたロギング構成を取得し、ログのリストを調べて、KCP_HPA ログが無効になっていることを確認します。

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

出力は次のようになります。

SYSTEM_COMPONENTS,APISERVER,CONTROLLER_MANAGER,SCHEDULER

ログの種類

Horizontal Pod Autoscaler の決定イベントは、GKE クラスタと同じプロジェクトの _Default バケットにある logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fhpa-controller" ロケーションに Cloud Logging に保存されます。ログに記録されるイベントはすべて JSON 形式で、ログエントリの jsonPayload フィールドで確認できます。

パフォーマンスや費用の影響に加えて、想定されるログボリュームのストレージ要件を理解してください。次の例は、Horizontal Pod Autoscaler が各タイプの決定イベントを生成する頻度を示しています。

• アトミック推奨事項: Horizontal Pod Autoscaler は、クラスタ内の各 HPA オブジェクトによってモニタリングされている指標ごとに、15 秒ごとに 1 つのアトミック推奨事項イベントを生成します。たとえば、クラスタに 2 つの HPA オブジェクトがあり、各 HPA オブジェクトが 3 つの指標をモニタリングしている場合、15 秒ごとに6 つのアトミック推奨事項がログに記録されます。

• 最終的な推奨事項: Horizontal Pod Autoscaler は、クラスタ内の HPA オブジェクトごとに 15 秒ごとに最終的な推奨事項イベントを 1 つ生成します。たとえば、クラスタに 2 つの HPA オブジェクトがある場合、15 秒ごとに2 つの最終的な推奨事項が記録されます。

2 つの HPA オブジェクトがそれぞれ3 つの指標をモニタリングすると、KCP_HPA ログには15 秒ごとに合計 8 件の決定イベント エントリが送信されます。

アトミック レコメンデーション

アトミック推奨ログには、Horizontal Pod Autoscaler で指定された個々の指標に基づく推奨事項が記述されます。

アトミック ログには次のフィールドが含まれます。

フィールド	説明
start_time	HPA が推奨事項の計算を開始した日時を示します。
hpa	推奨事項に関連付けられている HPA オブジェクトの名前。
pod_count	推奨を作成するときに HPA に関連付けられている Pod の合計数を示します。この数には、準備完了、準備完了前、無視の Pod も含まれます。
metric	推奨事項に使用された指標の仕様とステータスに関する情報を提供します。metric フィールドには次のサブフィールドが含まれます。 index: Spec metrics 配列内の指標のインデックス。 type: MetricSourceType の値を持つ指標タイプ（Resource、External など）。 spec: 指標の名前と、その指標に設定されたターゲット。 status: スケーラビリティとスケーリングの制限に関するステータス条件。 newest_sample_time: 最新の指標サンプルのタイムスタンプ。 newest_sample_age_seconds: 推奨事項の計算開始からの最新のサンプルの年齢（秒単位）。負の値は、指標のサンプルが計算の開始より前であることを示します。
summary	summary フィールドには、推奨されるレプリカ数など、推奨結果に関する情報が含まれます。推奨事項を提案できない場合は、エラー メッセージが表示されます。summary フィールドには次のサブフィールドが含まれます。 dampening: HPA は、推奨事項とその方向に減衰を適用して、潜在的なスケールの大きさを減らそうとします。減衰は次の方法で発生する可能性があります。 up: 上昇緩和方向は、HPA が指標の使用率が 100% の指標がない Pod を想定することを意味します。 down: 下方向の減衰方向は、指標がない Pod または指標の使用率が 0% の準備ができていない Pod を HPA が想定していることを意味します。 none: 減衰は適用されません。 override: HPA によって提案された推奨事項が適用されない理由（許容範囲が原因など）を示すメッセージ。オーバーライドが行われない場合は none。 result: 推奨の結果。推奨されるレプリカ数を提案するか、推奨値を計算できない場合はエラー メッセージを表示します。

アトミック推奨事項ログの例:

{
  "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"
}

最終的な推奨事項

最終的な推奨事項ログには、HorizontalPodAutoscaler によって提案された統合された推奨事項が記述されます。Horizontal Pod Autoscaler は、さまざまな指標のすべてのアトミック推奨事項を組み合わせて最終的な推奨事項を作成し、最終的な推奨事項を実行します。アクチュエーションとは、HPA が Deployment に、推奨値と一致するようにレプリカの数を調整するよう指示することを意味します。最終的な推奨値が、実行中の Pod の数とは異なる Pod 数を示している場合、Horizontal Pod Autoscaler はスケールアップまたはスケールダウン イベントをトリガーして、Deployment を適切に調整します。

最終的な推奨事項ログには、次のフィールドが含まれます。

フィールド	説明
start_time	HPA が推奨事項の計算を開始した日時を示します。
hpa	推奨事項に関連付けられている HPA オブジェクトの名前。
target_ref	推奨事項に関連付けられた HPA ScaleTargetRef オブジェクトを示します。
configured_size	HPA がこの推奨事項を計算して適用する前に最後に記録されたレプリカの数。
top_level_override	HPA によって提案された推奨事項が適用されない理由（許容範囲が原因など）を指定します。オーバーライドが実行されていない場合は none を指定します。
top_level_limit	HPA によって提案された推奨事項を調整する必要がある場合の理由を指定します（HPA 仕様の MinReplicas フィールドまたは MaxReplicas フィールドで定義されたレプリカ数など）。
leading_metric_index	Spec metrics 配列の先頭の指標は、関連するアトミック レコメンデーションが最終的なレコメンデーションとして使用される指標です。
normalization	安定化と制限の概要を次のように提供します（存在する場合）。 stabilization: 適用された場合の安定化状態を記述します。安定化は、スケーリングに使用される指標が変動し続けている場合に、レプリカ数のフラッペングを制限するために使用されます。stabilization フィールドは次のサブフィールドで構成されています。 replicas: 安定化後のレプリカ数。 reason: 適用された安定化タイプ - scaleUp または scaleDown。 stabilization_window: 関連付けられた安定化時間（秒）。 replicas_before_stabilization: 安定化前の推奨レプリカ数。 limitation: スケーリングの上限が適用された場合の処理方法を指定します。この動作により、適用されている制限に基づいて HPA が提案する推奨事項が変更されます。limitation フィールドは、次のサブフィールドで構成されています。 replicas: 制限後のレプリカ数。 reason: レプリカの最小数または最大数を超えてスケーリングしない理由。 scaling_policy: 適用されるスケーリング ポリシー。 selectPolicy: 特定の方向にスケーリングするときにポリシーを選択する方法。MaxChange は MaxChangePolicySelect に対応し、MinChange は MinChangePolicySelect に対応します。スケーリングが無効になっている場合、selectPolicy フィールドは存在しません。 replicas_before_limitation: 制限前の推奨レプリカ数。
replicas	推奨されるレプリカ数。
actuation_error	アクチュエーションが失敗した場合のエラーに関連付けられたエラー メッセージ。
actuation_time	成功時の動作のタイムスタンプ。
actuation_latency_seconds	推奨事項の計算開始から動作が成功するまでの経過時間（秒単位）。

最終的な推奨事項ログの例:

{
  "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"
}

トラブルシューティング

このセクションでは、Horizontal Pod Autoscaler イベントに関連する問題と解決手順について説明します。

予定はありません

Horizontal Pod Autoscaler の決定イベントが表示されない場合は、次の操作をすべて行っていることを確認します。

• クラスタで Cloud Logging を有効にしている。
• クラスタの KCP_HPA ログを有効にしました。
• 正しく構成された hpa オブジェクトを少なくとも 1 つクラスタにデプロイしている。

hpa オブジェクトの構成を表示するには、次のコマンドを実行します。

  kubectl describe hpa $HPA_NAME

それでも KCP_HPA ログが表示されない場合は、Google Cloud サポートにお問い合わせください。

次のステップ

• GKE ログについてをご覧ください。
• GKE ログについて理解する。
• サンプルクエリを使用して特定の GKE ログを見つける方法を学びます。
• 指標に基づいて Pod の自動スケーリングを最適化する方法を確認する。