このページでは、Google Kubernetes Engine（GKE）の HorizontalPodAutoscaler によって出力される決定イベントについて説明します。これらのイベントを分析することで、水平 Pod 自動スケーリングのコントローラがワークロードのスケーリングを管理する方法に関する分析情報を取得し、アクションの背後にある意思決定プロセスを把握できます。
水平 Pod 自動スケーリングにより、決定イベントが出力されます。このイベントは、Cloud Logging のログエントリとして保存されます。
始める前に
次の前提条件を満たしていることを確認してください。
プロジェクトの選択または作成
既存のプロジェクトを使用することも、このチュートリアル用の新しいプロジェクトを作成することもできます。
-
In the Trusted Cloud console, on the project selector page, select or create a Trusted Cloud project.
-
Make sure that billing is enabled for your Trusted Cloud project.
-
Enable the GKE, and Cloud Logging APIs.
-
In the Trusted Cloud console, activate Cloud Shell.
At the bottom of the Trusted Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
- クラスタで水平 Pod 自動スケーリングのイベントのロギングを有効にする: Kubernetes Engine クラスタ管理者（
roles/container.clusterAdmin） - ログにアクセスし、ログ エクスプローラとログ分析を使用する: ログ閲覧者（
roles/logging.viewer） - GKE クラスタでバージョン
1.31.5-gke.1090000以降または1.32.1-gke.1260000以降を実行している必要があります。 - GKE クラスタで Cloud Logging を有効にします。Cloud Logging の料金が適用されます。
CLUSTER_NAME: 作成または更新するクラスタの名前。PROJECT_ID: 実際の Trusted Cloud プロジェクト ID。LOCATION: クラスタのコンピューティング リージョンまたはゾーン。CLUSTER_NAME: 作成または更新するクラスタの名前。PROJECT_ID: 実際の Trusted Cloud プロジェクト ID。LOCATION: クラスタのコンピューティング リージョンまたはゾーン。アトミックな推奨事項: 水平 Pod 自動スケーリングは、クラスタ内の各 HPA オブジェクトによってモニタリングされている指標ごとに、15 秒ごとに 1 つのアトミックな推奨事項イベントを生成します。たとえば、クラスタに 2 つの HPA オブジェクトがあり、それぞれの HPA オブジェクトが 3 つの指標をモニタリングしている場合、15 秒ごとに 6 つのアトミックな推奨事項がログに記録されます。
最終的な推奨事項: 水平 Pod 自動スケーリングは、クラスタ内の HPA オブジェクトごとに最終的な推奨事項のイベントを 15 秒ごとに 1 つ生成します。たとえば、クラスタに 2 つの HPA オブジェクトがある場合、15 秒ごとに最終的な推奨事項が 2 つ記録されます。
index:Spec metrics配列内の指標のインデックス。type: MetricSourceType の値を持つ指標のタイプ（Resource、External など）。spec: 指標の名前と、その指標に設定されたターゲット。status: スケーラビリティとスケーリングの制限に関するステータス条件。newest_sample_time: 最新の指標サンプルのタイムスタンプ。newest_sample_age_seconds: 最新のサンプルの経過時間（推奨事項の計算開始からの秒数）。指標のサンプルが計算の開始より前の場合は、負の値になります。dampening: HPA では、推奨事項とその増減で調整が行われ、スケール増大の可能性が抑えられます。増減は次のように行われます。up: 増大の場合、HPA が指標のない Pod を、指標の使用率が 100% であると想定することを意味します。down: 減少の場合、HPA が指標のない Pod を、指標の使用率が 0% であると想定することを意味します。none: 増減は行われません。
override: HPA によって提案された推奨事項が適用されない理由（許容範囲が原因など）。オーバーライドが行われない場合はnone。result: 推奨の結果。推奨されるレプリカ数が提案されるか、推奨値を計算できない場合はエラー メッセージが表示されます。replicas: 安定化後のレプリカ数。reason: 適用された安定化タイプ -scaleUpまたはscaleDown。stabilization_window: 関連付けられた安定化の期間（秒単位）。replicas_before_stabilization: 安定化前の推奨レプリカ数。replicas: 制限後のレプリカ数。reason: レプリカの最小数または最大数を超えたらスケーリングを行わない理由。scaling_policy: 適用されるスケーリング ポリシー。selectPolicy: 特定の方向にスケーリングするときにポリシーを選択する方法。MaxChangeは MaxChangePolicySelect に、MinChangeは MinChangePolicySelect に対応します。スケーリングが無効になっている場合、selectPolicyフィールドは表示されません。replicas_before_limitation: 制限前の推奨レプリカ数。- クラスタで Cloud Logging を有効にしている。
- クラスタの
KCP_HPAログを有効にしている。 - 正しく構成された
hpaオブジェクトを少なくとも 1 つクラスタにデプロイしている。 - GKE ログについてを確認する。
- GKE ログについて理解する。
- サンプルクエリを使用して、特定の GKE ログを見つける方法を確認する。
- 指標に基づいて Pod の自動スケーリングを最適化する方法を確認する。
API を有効にする
Cloud Shell を設定する
このチュートリアルでは、Cloud Shell を使用して gcloud コマンドと kubectl コマンドを実行します。Cloud Shell は、 Trusted Cloud by S3NSでホストされているリソースを管理するためのシェル環境です。Google Cloud CLI と kubectl コマンドライン ツールがプリインストールされています。
コンソールの下部にあるフレーム内で Cloud Shell セッションが開きます。
このチュートリアルでコマンドを実行する前に、デフォルト プロジェクトがサンプルアプリをデプロイするプロジェクト ID に設定されていることを確認します。まだ設定していない場合は、Cloud Shell で次のコマンドを実行します。
gcloud config set project PROJECT_ID
PROJECT_ID は、実際のプロジェクト ID に置き換えます。
必要なロールと権限
ログの生成を有効にする権限、ログにアクセスして処理する権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。
要件
水平 Pod 自動スケーリングの決定イベントを有効にする
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
次のように置き換えます。
これらのコマンドを使用すると、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
水平 Pod 自動スケーリングの決定イベントを無効にする
クラスタを更新して、--logging フラグから KCP_HPA コンポーネントを削除します。
gcloud container clusters update CLUSTER_NAME \
--location=LOCATION \
--project=PROJECT_ID \
--logging=SYSTEM
次のように置き換えます。
このコマンドにより、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
ログの種類
水平 Pod 自動スケーリングの決定イベントは、GKE クラスタと同じプロジェクトの _Default バケットにある Cloud Logging の logName="projects/PROJECT_ID/logs/container.googleapis.com%2Fhpa-controller" ロケーションに保存されます。ログに記録されるイベントはすべて JSON 形式で、ログエントリの jsonPayloadjsonPayload フィールドで確認できます。
パフォーマンスや費用への影響だけでなく、想定されるログボリュームのストレージ要件も把握してください。次の例は、水平 Pod 自動スケーリングが各タイプの決定イベントを生成する頻度を示しています。
2 つの HPA オブジェクトがそれぞれ 3 つの指標をモニタリングすると、KCP_HPA ログには 15 秒ごとに合計 8 個の決定イベント エントリが送信されます。
アトミックな推奨事項
アトミックな推奨事項ログには、水平 Pod 自動スケーリングで指定された個々の指標に基づく推奨事項が記載されます。
アトミックログには次のフィールドがあります。
| フィールド | 説明 |
|---|---|
start_time |
HPA が推奨事項の計算を開始した時刻。 |
hpa |
推奨事項に関連付けられている HPA オブジェクトの名前。 |
pod_count |
推奨の作成時に HPA に関連付けられる Pod の合計数。この数には、準備完了、準備完了でない、無視された Pod も含まれます。 |
metric |
推奨事項に使用される指標の仕様とステータスに関する情報。metric フィールドには次のサブフィールドがあります。
|
summary |
summary フィールドには、推奨されるレプリカ数など、推奨結果に関する情報が表示されます。推奨事項を提案できない場合は、エラー メッセージが表示されます。summary フィールドには次のサブフィールドがあります。
|
アトミックな推奨事項のログの例:
{
"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"
}
最終的な推奨事項
最終的な推奨事項ログには、水平 Pod 自動スケーリングによって提案された統合された推奨事項が記述されます。水平 Pod 自動スケーリングは、さまざまな指標からすべてのアトミックな推奨事項を組み合わせて最終的な推奨事項を作成し、最終的な推奨事項を作動させます。作動とは、HPA が Deployment に、推奨値と一致するようにレプリカの数を調整するよう指示することを意味します。最終的な推奨値が実行中の Pod の数とは異なる Pod 数になっている場合、水平 Pod 自動スケーリングはスケールアップまたはスケールダウン イベントをトリガーして、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 |
安定化と制限の概要（ある場合）。
|
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"
}
トラブルシューティング
このセクションでは、水平 Pod 自動スケーリングのイベントに関連する問題と解決手順について説明します。
イベントがない
水平 Pod 自動スケーリングの決定イベントが表示されない場合は、次のすべてを行っていることを確認してください。
hpa オブジェクトの構成を確認するには、次のコマンドを実行します。
kubectl describe hpa $HPA_NAME
それでも KCP_HPA ログが表示されない場合は、Trusted Cloud サポートにお問い合わせください。