水平 Pod 自動スケーリングのトラブルシューティング

Google Kubernetes Engine（GKE）で水平 Pod 自動スケーリングが想定どおりに機能しない場合、ワークロードが正しくスケーリングされない可能性があります。この問題により、アプリケーションが負荷を処理できなくなり、パフォーマンスの問題や停止が発生する可能性があります。CPU 使用率が高いにもかかわらず Pod が増加しない、HorizontalPodAutoscaler のステータスに <unknown> と表示される指標値がある、スケーリング オペレーションがまったく発生しないといった状況が発生する可能性があります。

このページでは、HorizontalPodAutoscaler オブジェクトの初期構成ミスから指標パイプライン内のより複雑な障害まで、水平 Pod 自動スケーリングに関する一般的な問題を診断して解決する方法について説明します。これらのトラブルシューティングの手順に沿って対応することで、需要に基づいてアプリケーションを効率的かつ確実にスケーリングし、Horizontal Pod Autoscaler リソースを効果的に活用できます。

この情報は、HorizontalPodAutoscaler オブジェクトを構成し、アプリケーションが正しくスケーリングされるようにする必要があるアプリケーション デベロッパーにとって重要です。また、プラットフォーム管理者とオペレーターが、すべての自動スケーリング ワークロードに影響する指標パイプラインまたはクラスタ構成の問題をトラブルシューティングするのにも役立ちます。 Google Cloud のコンテンツで使用されている一般的なロールとタスクの例の詳細については、一般的な GKE ユーザーのロールとタスクをご覧ください。

すでに症状が発生している場合やエラー メッセージが表示されている場合は、次の表を使用して適切なガイダンスを見つけてください。

症状 考えられる解決策
スケーリングは行われないが、HorizontalPodAutoscaler の条件が True である 正常だが応答しない HorizontalPodAutoscaler のトラブルシューティング
HorizontalPodAutoscaler イベントに特定のエラー メッセージが表示される 水平 Pod オートスケーラーの一般的なエラーのトラブルシューティング
指標 <unknown> カスタム指標と外部指標のトラブルシューティング
スケールダウンしない 水平 Pod 自動スケーラーがスケールダウンしない問題のトラブルシューティング

始める前に

  • Deployment や StatefulSet などのスケーラブルなワークロードで HorizontalPodAutoscaler オブジェクトを使用してください。スケーリングできないワークロード（DaemonSet など）では、水平 Pod 自動スケーリングを使用できません。

  • GKE で水平 Pod 自動スケーリングのトラブルシューティング（HorizontalPodAutoscaler オブジェクトの検査やクラスタログの表示など）に必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

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

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

  • GKE クラスタと通信するように kubectl コマンドライン ツールを構成します。

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location LOCATION \
    --project PROJECT_ID

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

    • CLUSTER_NAME: クラスタの名前。
    • LOCATION: クラスタの Compute Engine のリージョンまたはゾーン（us-central1 や us-central1-a など）。
    • PROJECT_ID: 実際の Google Cloud プロジェクト ID。

HorizontalPodAutoscaler のステータスと構成を確認する

トラブルシューティングは、HorizontalPodAutoscaler オブジェクトの健全性と構成を調べることから始めます。この初期チェックは、スケーリングの問題の一般的な根本原因である基本的な構成ミスを特定して解決するのに役立ちます。

HorizontalPodAutoscaler の説明を取得する

HorizontalPodAutoscaler のリアルタイム計算と最近のスケーリング決定を表示するには、kubectl describe hpa コマンドを使用します。このコマンドは、HorizontalPodAutoscaler オブジェクトの概要と、問題の診断に役立つ Events ログを提供します。

kubectl describe hpa HPA_NAME -n NAMESPACE_NAME

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

  • HPA_NAME: HorizontalPodAutoscaler オブジェクトの名前。
  • NAMESPACE_NAME: HorizontalPodAutoscaler オブジェクトの Namespace。

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

Name:                                                  php-apache-hpa
Reference:                                             Deployment/php-apache
Metrics: ( current / target )
  resource cpu on pods (as a percentage of request):   1% (1m) / 50%
Min replicas:                                          1
Max replicas:                                          10
Conditions:
  Type            Status  Reason              Message
  ----            ------  ------              -------
  AbleToScale     True    ReadyForNewScale    recommended size matches current size
  ScalingActive   True    ValidMetricFound    the HorizontalPodAutoscaler was able to successfully calculate a replica count
Events:
  Type     Reason              Age   From                       Message
  ----     ------              ----  ----                       -------
  Normal   SuccessfulRescale   39m   horizontal-pod-autoscaler  New size: 4; reason: cpu resource utilization...
  Normal   SuccessfulRescale   26m   horizontal-pod-autoscaler  New size: 1; reason: cpu resource utilization...

出力では、次の 3 つのセクションが問題の診断に役立ちます。

  • Metrics: このセクションには、現在の指標値と目標値が比較して表示されます。HorizontalPodAutoscaler がデータを受信しているかどうかを確認します。<unknown> 指標値は、HorizontalPodAutoscaler が指標を取得していないか、指標パイプラインが破損していることを示します。
  • Conditions: この高レベルのヘルスチェックは、HorizontalPodAutoscaler が指標（AbleToScale）を取得してスケーリング計算（ScalingActive）を実行できるかどうかを示します。これらの条件のいずれかで False ステータスが表示された場合は、失敗を示します。
  • Events: このセクションには、HorizontalPodAutoscaler コントローラからの最近のスケーリング アクション、警告、エラーが記録されます。多くの場合、FailedGetScale や FailedGetResourceMetric などの特定のエラー メッセージや理由が最初に表示され、問題の原因を特定するのに役立ちます。

Deployment の HorizontalPodAutoscaler のステータスを確認する

Deployment で使用される HorizontalPodAutoscaler オブジェクトのステータスを確認するには、 Google Cloud コンソールを使用します。

  1. Google Cloud コンソールで、[ワークロード] ページに移動します。

    [ワークロード] に移動

  2. Deployment の名前をクリックします。

  3. [詳細] タブに移動し、[自動スケーリング] セクションを見つけます。

  4. [ステータス] 行の値を確認します。

    • 緑色のチェックマークは、HorizontalPodAutoscaler が構成され、指標を読み取ることができることを意味します。
    • 黄色の三角形は、HorizontalPodAutoscaler が構成されているが、指標の読み取りに問題があることを意味します。これは、カスタム指標または外部指標でよく発生する問題です。この問題を解決するには、指標が利用できない理由を診断します。詳細については、カスタム指標と外部指標のトラブルシューティングをご覧ください。

StatefulSet などの他のワークロード タイプや詳細については、HorizontalPodAutoscaler オブジェクトのマニフェストを確認してください。

HorizontalPodAutoscaler のマニフェストを確認する

HorizontalPodAutoscaler オブジェクトの YAML マニフェストを使用すると、構成とその現在の状態に関する情報を確認できます。

YAML マニフェストを表示するには、次のいずれかのオプションを選択します。

コンソール

  1. Google Cloud コンソールで、[オブジェクト ブラウザ] ページに移動します。

    オブジェクト ブラウザに移動

  2. [オブジェクトの種類] リストで、[HorizontalPodAutoscaler] チェックボックスをオンにして、[OK] をクリックします。

  3. autoscaling API グループに移動し、HorizontalPodAutoscaler の展開矢印をクリックします。

  4. 検査する HorizontalPodAutoscaler オブジェクトの名前をクリックします。

  5. [YAML] セクションで、HorizontalPodAutoscaler オブジェクトの完全な構成を確認します。

kubectl

次のコマンドを実行します。

kubectl get hpa HPA_NAME -n NAMESPACE_NAME -o yaml

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

  • HPA_NAME: HorizontalPodAutoscaler オブジェクトの名前。
  • NAMESPACE_NAME: HorizontalPodAutoscaler オブジェクトの Namespace。

マニフェストを取得したら、次の重要なセクションを探します。

  • spec（構成）:
    • scaleTargetRef: HorizontalPodAutoscaler がスケーリングするワークロード（Deployment など）。
    • minReplicas と maxReplicas: レプリカの最小値と最大値の設定。
    • metrics: スケーリング用に構成した指標（CPU 使用率やカスタム指標など）。
  • status（HorizontalPodAutoscaler のライブ状態）:
    • currentMetrics: HorizontalPodAutoscaler が観測した最新の指標値。
    • currentReplicas と desiredReplicas: 現在の Pod の数と、HorizontalPodAutoscaler がスケーリングする数。
    • conditions: トラブルシューティングに最も役立つセクション。このセクションには、HorizontalPodAutoscaler の健全性が表示されます。
      • AbleToScale: HorizontalPodAutoscaler がターゲットと指標を見つけられるかどうかを示します。
      • ScalingActive: HorizontalPodAutoscaler がスケーリングの計算と実行を許可されているかどうかを示します。
      • ScalingLimited: HorizontalPodAutoscaler がスケールアップを希望しているが、minReplicas または maxReplicas の設定によって上限が設定されているかどうかを示します。

高度なロギング機能を使用する

HorizontalPodAutoscaler オブジェクトの詳細な分析情報を取得するには、次のタイプのログを使用します。

  • Cloud Logging で Horizontal Pod Autoscaler イベントを表示する: ログフィルタを使用して、特定のクラスタのすべての Horizontal Pod Autoscaler イベントを見つけます。次に例を示します。

    1. Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。

      [ログ エクスプローラ] に移動

    2. クエリペインに次のクエリを入力します。

      resource.type="k8s_cluster"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.location="LOCATION"
logName="projects/PROJECT_ID/logs/events"
jsonPayload.involvedObject.kind="HorizontalPodAutoscaler"`

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

      • CLUSTER_NAME: HorizontalPodAutoscaler が属するクラスタの名前。
      • LOCATION: クラスタの Compute Engine のリージョンまたはゾーン（us-central1 や us-central1-a など）。
      • PROJECT_ID: プロジェクト ID。

    3. [クエリを実行] をクリックして出力を確認します。

  • HorizontalPodAutoscaler イベントを表示する: これらのログは、HorizontalPodAutoscaler が推奨事項を計算する方法を説明する構造化された人間が読めるログを提供し、意思決定プロセスに関する詳細な分析情報を提供します。

正常だが応答しない HorizontalPodAutoscaler のトラブルシューティング

このセクションでは、HorizontalPodAutoscaler が正常に動作しているように見え、ステータスやイベントにエラーが報告されていない場合でも、スケーリング アクションがトリガーされない理由を診断するのに役立ちます。

症状:

HorizontalPodAutoscaler は正常に動作しているように見え、条件は True を報告し、イベントにエラーは表示されません。ただし、スケーリング アクションは実行されません。

原因:

この想定される動作を引き起こす要因はいくつかあります。

  • レプリカの上限: 現在のレプリカ数が、HorizontalPodAutoscaler 構成の minReplicas フィールドまたは maxReplicas フィールドで設定された上限に達しています。
  • 許容範囲: Kubernetes は、デフォルトの 10% の許容範囲を使用して、指標のわずかな変動によるスケーリングを防ぎます。スケーリングは、現在の指標と目標指標の比率が 0.9 ～ 1.1 の範囲外になった場合にのみ行われます。たとえば、目標が 85% の CPU で、現在の使用率が 93% の場合、比率は約 1.094（93/85≈1.094）になります。この値は 1.1 未満であるため、Horizontal Pod Autoscaler はスケールアップしません。
  • 準備ができていない Pod: HorizontalPodAutoscaler は、Ready ステータスの Pod のみをスケーリング計算に含めます。Pending ステータスのままになっている Pod、または Ready にならない Pod（ヘルスチェックの失敗やリソースの問題が原因）は無視され、スケーリングが妨げられる可能性があります。
  • 同期期間の遅延: HorizontalPodAutoscaler コントローラは指標を定期的にチェックします。指標がしきい値を超えてからスケーリング アクションが開始されるまでの遅延が 15 ～ 30 秒であるのは正常です。
  • 新しい指標のレイテンシ: HorizontalPodAutoscaler が新しいカスタム指標を初めて使用する場合、数分のレイテンシが 1 回発生することがあります。この遅延は、最初のデータポイントが書き込まれたときにモニタリング システム（Cloud Monitoring など）が新しい時系列を作成する必要があるために発生します。
  • 複数の指標の計算: 複数の指標を構成すると、Horizontal Pod Autoscaler は各指標に必要なレプリカ数を個別に計算し、計算された最大値を最終的なレプリカ数として選択します。この動作により、ワークロードは最もニーズの高い指標の需要を満たすようにスケーリングされます。たとえば、CPU 指標で 9 個のレプリカが必要と計算され、1 秒あたりのリクエスト数指標で 15 個のレプリカが必要と計算された場合、Horizontal Pod Autoscaler は Deployment を 15 個のレプリカにスケーリングします。

解決策:

次の解決策をお試しください。

  • レプリカの上限: HorizontalPodAutoscaler マニフェストまたは kubectl describe コマンドの出力で minReplicas 値と maxReplicas 値を確認します。必要なスケーリングが妨げられている場合は、これらの上限を調整します。
  • 許容範囲: デフォルトの許容範囲内でスケーリングが必要な場合は、別の許容範囲の値を構成します。それ以外の場合は、指標が 0.9 ～ 1.1 の比率から外れるまで待ちます。
  • 準備ができていない Pod: Pod が Pending である理由、または Ready でない理由を調査し、根本的な問題（リソースの制約、準備状況プローブの失敗など）を解決します。トラブルシューティングのヒントについては、Kubernetes ドキュメントの Pod のデバッグをご覧ください。
  • 同期期間の遅延と新しい指標のレイテンシ: これらのレイテンシは正常です。同期期間が完了するか、新しいカスタム指標の時系列が作成されるまで待ちます。
  • 複数の指標の計算: これは想定どおりの動作です。スケールアップが 1 つの指標（1 秒あたりのリクエスト数など）に基づいて行われている場合、別の指標の低い計算（CPU など）は正しくオーバーライドされます。

Horizontal Pod Autoscaler の一般的なエラーのトラブルシューティング

以降のセクションでは、HorizontalPodAutoscaler のステータスを検査するときに発生する可能性のある特定のエラー メッセージとイベントの理由に対する解決策について説明します。通常、これらのメッセージは kubectl describe hpa コマンドの出力の Events セクションに表示されます。

HorizontalPodAutoscaler 構成エラーのトラブルシューティング

このセクションのエラーは、HorizontalPodAutoscaler マニフェストの構成ミス（フィールドの入力ミスや構成の競合など）が原因で発生します。

エラー: 無効な指標

このエラーは、HorizontalPodAutoscaler 内の指標の構成が構文的に正しくないか、一貫性がない場合に発生することがあります。

症状:

構成の問題により HorizontalPodAutoscaler が必要なレプリカを計算できない場合、Events セクションに FailedComputeMetricsReplicas の理由と次のようなメッセージが表示されます。

invalid metrics (1 invalid out of 1)

原因:

このエラーは通常、指標 type と HorizontalPodAutoscaler マニフェストで定義した target の間に不一致があることを意味します。たとえば、type を Utilization に指定したのに、averageUtilization ではなく averageValue の目標値を指定した可能性があります。

解決策:

target フィールドの値が指標 type と一致するように、HorizontalPodAutoscaler マニフェストを修正します。

  • type が Utilization の場合、target フィールドの値は averageUtilization にする必要があります。
  • type が AverageValue の場合、target フィールドの値は averageValue にする必要があります。

エラー: 複数のサービスが同じターゲットを選択している

このエラーは、HorizontalPodAutoscaler の Service 構成が正しくないトラフィック ベースの自動スケーリングを使用している場合に表示されることがあります。

症状:

次のエラーが表示されます。

multiple services selecting the same target of HPA_NAME: SERVICE_NAME

この出力には次の値が含まれます。

  • HPA_NAME: HorizontalPodAutoscaler の名前。
  • SERVICE_NAME: Service の名前。

原因:

トラフィック ベースの自動スケーリングが構成されているが、複数の Kubernetes Service が HorizontalPodAutoscaler の scaleTargetRef フィールドをターゲットにしている。トラフィック ベースの自動スケーリングでは、Service と自動スケーリングされたワークロード間の 1 対 1 の関係のみがサポートされます。

解決策:

この問題を解決するには、ワークロードの Pod と一致する Service のラベルセレクタが 1 つだけであることを確認します。

  1. ワークロードの Pod ラベルを見つけます。

    kubectl get deployment HPA_TARGET_DEPLOYMENT \
    -n NAMESPACE \
    -o jsonpath='{.spec.template.metadata.labels}'

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

    • HPA_TARGET_DEPLOYMENT: HorizontalPodAutoscaler がターゲットとする Deployment の名前。
    • NAMESPACE: Deployment の Namespace。

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

    {"app":"my-app", "env":"prod"}

  2. Namespace 内のすべての Service の spec.selector フィールドを確認して、これらのラベルに一致するすべての Service を見つけます。

    kubectl get services -n NAMESPACE -o yaml

    セレクタが前のステップのラベルと一致するすべての Service を特定します。たとえば、{"app": "my-app"} と {"app": "my-app", "env": "prod"} の両方が Pod のラベルの例と一致します。

  3. 次のいずれかのオプションを選択して、競合を解決します。

    • Deployment の spec.template.metadata.labels フィールドに新しい一意のラベルを追加して、目的の Service のセレクタを一意にします。次に、目的の Service の spec.selector フィールドを更新して、この新しいラベルを含めます。
    • 競合するすべての 他の Service の spec.selector フィールドを変更して、他の Service セレクタをより制限的にし、ワークロードの Pod と一致しないようにします。

  4. 変更を適用するには、以下のコマンドを使用します。

    kubectl apply -f MANIFEST_NAME

    MANIFEST_NAME は、更新された Service または Deployment マニフェストを含む YAML ファイルの名前に置き換えます。

エラー: ラベルは許可されていません

症状:

次のエラーが表示されます。

unable to fetch metrics from external metrics API: googleapi: Error 400: Metric label: 'LABEL_NAME' is not allowed

この出力で、LABEL_NAME は正しくないラベルの名前です。

原因:

HorizontalPodAutoscaler マニフェストの metric.selector.matchLabels セクションで無効なラベルキーが指定されており、Cloud Monitoring はこのキーを認識せず、指標に使用することもできません。

解決策:

この問題を解決するには、次の操作を行います。

  1. エラー メッセージから、許可されていないラベル名を特定します。
  2. HorizontalPodAutoscaler マニフェストの metric.selector.matchLabels セクションで、このラベルキーを削除するか修正します。
  3. その指標の Cloud Monitoring ドキュメントを参照して、有効なフィルタリング可能なラベルキーを見つけます。

問題: 同じワークロードをターゲットとする複数の HorizontalPodAutoscaler

同じワークロードを管理するように複数の HorizontalPodAutoscaler オブジェクトを構成すると、スケーリング動作が競合して予測不能になります。

症状:

この競合を直接示す特定の Condition または Reason は、HorizontalPodAutoscaler のステータス内にありません。代わりに、次のような症状が見られることがあります。

  • ワークロードのレプリカ数が予期せず変動する可能性があります。
  • スケーリングの決定が、単一の HorizontalPodAutoscaler で定義された指標に対応していないように見えることがあります。
  • イベントを表示すると、異なる HorizontalPodAutoscaler オブジェクトから SuccessfulRescale イベントが交互に表示されたり、矛盾するイベントが表示されたりすることがあります。

原因:

この問題は、同じ Namespace 内の複数の HorizontalPodAutoscaler オブジェクトが spec.scaleTargetRef フィールドでまったく同じワークロードを指定しているために発生します。各 HorizontalPodAutoscaler はレプリカ数を個別に計算し、独自の指標とターゲットのセットに基づいてワークロードのスケーリングを試みます。Kubernetes はこの構成をブロックしませんが、HorizontalPodAutoscaler が互いに競合するため、スケーリング調整が不安定になります。

解決策:

競合を避けるため、すべてのスケーリング指標を 1 つの HorizontalPodAutoscaler オブジェクトで定義します。各 HorizontalPodAutoscaler は独自の spec.metrics フィールドからスケーリングの必要性を計算するため、それらを統合すると、選択した HorizontalPodAutoscaler オブジェクトは CPU や 1 秒あたりのリクエスト数などのすべての要素をまとめて考慮できます。

  1. 同じワークロードをターゲットとする HorizontalPodAutoscaler を特定するには、各 HorizontalPodAutoscaler オブジェクトの YAML マニフェストを取得します。出力の spec.scaleTargetRef フィールドに注意してください。

    kubectl get hpa -n NAMESPACE_NAME -o yaml

    NAMESPACE_NAME は、HorizontalPodAutoscaler オブジェクトの Namespace に置き換えます。

    異なる HorizontalPodAutoscaler リソースの scaleTargetRef フィールド内で、apiVersion、kind、name の値が同じであるインスタンスを探します。

  2. 指標を単一の HorizontalPodAutoscaler オブジェクトに統合します。

    1. 保持する HorizontalPodAutoscaler オブジェクトを 1 つ選択します。この HorizontalPodAutoscaler を変更します。
    2. 同じワークロードをターゲットとする他の HorizontalPodAutoscaler オブジェクトの各マニフェストの spec.metrics セクションを確認します。
    3. 重複する HorizontalPodAutoscaler オブジェクトの spec.metrics セクションから、保持する指標定義をコピーします。
    4. コピーした指標定義を、保持する HorizontalPodAutoscaler の spec.metrics 配列に貼り付けます。

  3. 変更を適用するには、以下のコマンドを使用します。

    kubectl apply -f MANIFEST_NAME

    MANIFEST_NAME は、保持する HorizontalPodAutoscaler マニフェストの名前に置き換えます。

  4. 同じワークロードをターゲットにしていた他の HorizontalPodAutoscaler オブジェクトを削除します。

    kubectl delete hpa DUPLICATE_MANIFEST_NAME -n NAMESPACE_NAME

    DUPLICATE_MANIFEST_NAME は、削除する冗長な HorizontalPodAutoscaler オブジェクトの名前に置き換えます。

ワークロードとターゲットのエラーのトラブルシューティング

このセクションのエラーは、HorizontalPodAutoscaler オブジェクト自体ではなく、Deployment、StatefulSet、または Pod のスケーリングが原因で発生します。

エラー: ターゲットの現在のスケールを取得できません

このエラーは、HorizontalPodAutoscaler がスケーリングするワークロードを見つけられないか、アクセスできない場合に発生することがあります。

症状:

Events セクションには、次のようなメッセージを含む FailedGetScale の条件があります。

the HorizontalPodAutoscaler controller was unable to get the target's current scale: WORKLOAD_TYPE.apps "TARGET_WORKLOAD" not found

この出力には次の値が含まれます。

  • WORKLOAD_TYPE: ワークロードのタイプ（Deployment、StatefulSet など）。
  • TARGET_WORKLOAD: ワークロードの名前。

原因:

HorizontalPodAutoscaler コントローラが、管理するように構成されているワークロード（Deployment や StatefulSet など）を見つけられない。この問題は、HorizontalPodAutoscaler のマニフェスト内の scaleTargetRef フィールドの問題が原因で発生します。指定されたリソースが存在しないか、削除されたか、スペルミスがある可能性があります。

解決策:

次の解決策をお試しください。

  1. HorizontalPodAutoscaler のマニフェストの scaleTargetRef フィールドを確認する: scaleTargetRef フィールドの name、kind、apiVersion の値が、ターゲット ワークロードの対応するメタデータと完全に一致していることを確認します。ワークロード名が正しくない場合は、HorizontalPodAutoscaler の scaleTargetRef フィールドを更新して、正しい名前を指すようにします。
  2. ワークロードが存在することを確認する: ターゲット ワークロードが HorizontalPodAutoscaler と同じ Namespace に存在することを確認します。これは、kubectl get deployment DEPLOYMENT_NAME などのコマンドで確認できます。ワークロードを意図的に削除した場合は、対応する HorizontalPodAutoscaler オブジェクトを削除してクラスタをクリーンアップします。ワークロードを再作成する必要がある場合、HorizontalPodAutoscaler はワークロードが使用可能になると自動的に検出するため、エラーは解決されます。
  3. HorizontalPodAutoscaler とワークロードが同じ Namespace にあることを確認する: HorizontalPodAutoscaler とそのターゲット ワークロードは同じ Namespace に存在する必要があります。kubectl コマンドでオブジェクトを作成するときに Namespace の指定を忘れると、Kubernetes はオブジェクトを default Namespace に配置します。この動作により、HorizontalPodAutoscaler が default 名前空間にあり、ワークロードが別の名前空間にある場合、またはその逆の場合に、不一致が発生する可能性があります。両方のオブジェクトの Namespace を確認し、一致していることを確認します。

HorizontalPodAutoscaler がターゲットを正常に特定すると、条件 AbleToScale が True になり、メッセージが the HorizontalPodAutoscaler controller was able to get the target's current scale に変わります。

エラー: レプリカ数を計算できません

このエラーは、HorizontalPodAutoscaler がリソース使用率に基づいてスケーリングを計算する必要があるが、Pod から必要なベースライン情報がない場合に発生することがあります。

症状:

ScalingActive 条件は False で、Reason は FailedGetResourceMetric です。通常、次のようなメッセージも表示されます。

the HorizontalPodAutoscaler was unable to compute the replica count

原因:

Horizontal Pod Autoscaler は、ワークロードをスケーリングするためにリソース使用率を割合として計算する必要がありますが、Pod 仕様内の少なくとも 1 つのコンテナに、対応するリソース（cpu または memory）の resources.requests 定義がないため、この計算を実行できません。

解決策:

この問題を解決するには、Deployment、StatefulSet、またはその他のコントローラ内の Pod マニフェストを更新して、HorizontalPodAutoscaler が Pod 内のすべてのコンテナでスケーリングしようとしているリソース（cpu または memory）の resources.requests フィールドを含めます。次に例を示します。

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
spec:
  containers:
  - name: example-container
...
    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"

エラー: Pod の指標を取得できません

このエラーは、HorizontalPodAutoscaler がスケーリングの決定に必要な指標を取得する際に問題が発生した場合に表示されることがあります。多くの場合、Pod リソース定義に関連しています。

症状:

次のようなメッセージが継続的に表示されます。

unable to fetch pod metrics for pod

指標サーバーの起動時にこのメッセージが一時的に表示されるのは、正常な状態です。

原因:

リソース使用率（cpu や memory など）に基づいてスケーリングするには、HorizontalPodAutoscaler オブジェクトのターゲットとなる Pod 内のすべてのコンテナに、その特定のリソースに対して resources.requests フィールドが定義されている必要があります。そうでないと、HorizontalPodAutoscaler が必要な計算を実行できないため、その指標に関連する処理を行いません。

解決策:

これらのエラー メッセージが引き続き表示され、ワークロードの Pod がスケーリングされない場合は、ワークロード内のコンテナごとにリソース リクエストを指定していることを確認してください。

指標 API とデータの可用性に関するエラーのトラブルシューティング

以降のセクションでは、HorizontalPodAutoscaler が指標 API からデータを取得しようとしたときに発生するエラーの解決方法について説明します。これらの問題は、指標 API が使用できない内部クラスタ通信の失敗から、指標プロバイダが拒否する無効なクエリ（多くの場合、400 レベルの HTTP エラーとして表示されます）まで多岐にわたります。

エラー: 利用可能な指標バージョンが見つかりません

症状:

次のエラーが表示されます。

unable to fetch metrics from custom metrics API: no known available metric versions found

原因:

このエラーは、クラスタ内の通信障害を示しており、指標ソース（Cloud Monitoring など）の問題を示しているわけではありません。一般的な原因は次のとおりです。

  • Kubernetes API サーバーが一時的に使用できない（クラスタのアップグレードやコントロール プレーンの修復中など）。
  • 指標アダプター Pod（custom-metrics-stackdriver-adapter など）が異常である、実行されていない、または API サーバーに正しく登録されていない。

解決策:

この問題は一時的なものであることがよくあります。問題が解決しない場合は、次の解決策をお試しください。

  1. Kubernetes コントロール プレーンの状態を確認する:

    1. Google Cloud コンソールで、クラスタの健全性とステータスを表示します。

      1. [Kubernetes クラスタ] ページに移動します。

        Kubernetes クラスタに移動

      2. クラスタの [ステータス] 列と [通知] 列を確認します。

      3. [通知] をクリックして、アップグレードや修理などの進行中のオペレーションがないか確認します。この間、API サーバーが一時的に使用できなくなることがあります。

    2. Cloud Audit Logs で、コントロール プレーン コンポーネントに関連するエラーを確認します。これらのログの表示方法については、GKE 監査ロギング情報をご覧ください。

  2. 指標アダプタ Pod の健全性とログを確認する: 指標アダプタ Pod が Running ステータスであり、最近再起動されていないことを確認します。

    kubectl get pods -n custom-metrics,kube-system -o wide

    Pod のステータスが Running 以外の場合や、再起動回数が多い場合は、Pod を調べて根本原因を特定します。トラブルシューティングのヒントについては、Kubernetes ドキュメントの Pod のデバッグをご覧ください。

  3. 指標 API が登録され、使用可能であることを確認します。

    kubectl get apiservice | grep metrics.k8s.io

    指標 API が正常な場合、出力は次のようになります。

    NAME                            SERVICE                                             AVAILABLE   AGE
v1beta1.custom.metrics.k8s.io   custom-metrics/custom-metrics-stackdriver-adapter   True        18d
v1beta1.external.metrics.k8s.io custom-metrics/custom-metrics-stackdriver-adapter   True        18d
v1beta1.metrics.k8s.io          kube-system/metrics-server                          True        18d

    AVAILABLE 列の値が False の場合、完全な APIService マニフェストの Message 列に詳細が記載されていることがあります。

    次のコマンドを使用して、マニフェスト全体を表示できます。

    kubectl get apiservice API_SERVICE_NAME -o yaml

    API_SERVICE_NAME は、APIService オブジェクトの名前（v1beta1.custom.metrics.k8s.io など）に置き換えます。

エラー: クエリは時系列を返しません

症状:

次のエラーが表示されます。

unable to fetch metrics from custom or external metrics API: googleapi: Error
400: The supplied filter [...] query will not return any time series

原因:

Cloud Monitoring に送信されたクエリは有効でしたが、データは返されませんでした。これは、フィルタに一致するデータポイントが存在しないことを意味します（値が 0 の指標が見つかった場合とは異なります）。この問題の最も可能性の高い原因は、カスタム指標の生成を担当するアプリケーションまたはワークロードが、エラーが報告された期間に Cloud Monitoring にデータを書き込んでいなかったことです。

解決策:

次の解決策をお試しください。

  1. 構成を確認する: HorizontalPodAutoscaler オブジェクトの指標名とラベルが、アプリケーションによって出力されるものと正確に一致していることを確認します。
  2. 権限を確認する: Cloud Monitoring に指標を公開するために必要な権限と API エンドポイントを使用して、アプリケーションが正しく構成されていることを確認します。
  3. アプリケーションのアクティビティを確認する: 指標を担当するアプリケーションが動作しており、Horizontal Pod Autoscaler の警告が発生した期間中に Cloud Monitoring にデータを送信しようとしていたことを確認します。
  4. エラーを調査する: 同じ期間のアプリケーションのログを調べて、接続エラー、無効な認証情報、形式の問題など、指標の出力に関連する明示的なエラーがないか確認します。

カスタム指標と外部指標のトラブルシューティング

HorizontalPodAutoscaler がデフォルトの CPU またはメモリ以外のソースの指標に依存している場合、カスタム指標または外部指標のパイプライン内で問題が発生する可能性があります。このパイプラインは、次の図に示すように、HorizontalPodAutoscaler コントローラ、Kubernetes 指標 API サーバー、指標アダプタ、指標ソース（Cloud Monitoring や Prometheus など）で構成されています。

HPA 指標パイプラインのコンポーネント（HPA コントローラ、Kubernetes API サーバー、指標アダプタ、指標ソース）。

このセクションでは、指標アダプタから指標ソースまで、このパイプラインをデバッグする方法について詳しく説明します。

症状:

指標パイプラインの問題の最も一般的な症状は次のとおりです。

  • 指標の値は <unknown> と表示されます。
  • HorizontalPodAutoscaler イベントに FailedGetExternalMetric や FailedGetCustomMetric などのエラーが表示される。

原因:

カスタム指標または外部指標のパイプライン内に問題があります。

解決策:

次の手順に沿ってパイプラインをデバッグします。

  1. 指標アダプタが登録されて使用可能かどうかを確認する: 指標アダプタは、指標を提供するためにメインの Kubernetes API サーバーに登録する必要があります。このアクションは、アダプタが実行されていて API サーバーからアクセスできるかどうかを確認する最も直接的な方法です。

    kubectl get apiservice | grep -E 'NAME|metrics.k8s.io'

    出力には、v1beta1.custom.metrics.k8s.io または v1beta1.external.metrics.k8s.io のエントリと、Available 列に True の値が表示されます。次に例を示します。

    NAME                   SERVICE                      AVAILABLE   AGE
v1beta1.metrics.k8s.io kube-system/metrics-server   True        18d

    • Available 列の値が False であるか、欠落している場合、アダプタがクラッシュしているか、正しく構成されていない可能性があります。kube-system または custom-metrics 名前空間でアダプタの Pod ログを調べて、権限、指標ソースへのネットワーク接続、指標が見つからなかったことを示すメッセージに関連するエラーがないか確認します。

    • 値が True の場合は、次のステップに進みます。

  2. 指標 API を直接クエリする: アダプタが使用可能な場合は、HorizontalPodAutoscaler をバイパスして、Kubernetes API に指標を直接リクエストします。このコマンドは、API サーバーから指標アダプタ、データソースまでのパイプライン全体をテストします。

    外部指標をクエリするには、次のコマンドを実行します。

    kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/NAMESPACE_NAME/METRIC_NAME" | jq .

    カスタム Pod 指標をクエリするには、次のコマンドを実行します。

    kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/namespaces/NAMESPACE_NAME/pods/*/METRIC_NAME" | jq .

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

    • NAMESPACE_NAME: Pod が実行されている Namespace。
    • METRIC_NAME: クエリを実行しようとしているカスタム指標または外部指標の名前。たとえば、requests_per_second や queue_depth です。

  3. コマンド出力を分析する: 前のコマンドの結果から、問題の発生場所を特定できます。出力に一致するシナリオを選択します。

    • 値を含む JSON レスポンスが成功した場合: 指標パイプラインは正しく機能しています。この問題は、HorizontalPodAutoscaler マニフェストの構成の問題である可能性があります。指標名にスペルミスがないか、matchLabels が正しくないかを確認します。

    • Error: Error from server (Service Unavailable): このエラーは通常、ネットワーク接続の問題を示します。これは、ネットワーク分離を使用するクラスタのファイアウォールの問題であることがよくあります。

      1. 指標アダプタ サービスを特定します。通常は、custom-metrics または kube-system Namespace にあります。

        kubectl get service -n custom-metrics,kube-system | grep -E 'adapter|metrics'

      2. アダプターがリッスンしているポートを確認します。

        kubectl get service ADAPTER_SERVICE -n ADAPTER_NAMESPACE -o yaml

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

        • ADAPTER_SERVICE: デプロイした指標アダプタに関連付けられている Kubernetes Service の名前。この Service は、前の手順で確認した Service です。この Service は、Kubernetes API サーバーなど、クラスタの他の部分にアダプタの機能を公開します。
        • ADAPTER_NAMESPACE: アダプタ サービスが存在する Namespace（custom-metrics、kube-system など）。

      3. クラスタのコントロール プレーンのインバウンド ファイアウォール ルールを確認します。

        gcloud compute firewall-rules list \
    --filter="name~gke-CLUSTER_NAME-[0-9a-z]*-master"

        CLUSTER_NAME は、使用するクラスタの名前に置き換えます。

      4. アダプターの targetPort をルールに追加します。

        1. 現在のルールを説明して、既存の許可ポートを確認します。

          gcloud compute firewall-rules describe FIREWALL_RULE_NAME

          FIREWALL_RULE_NAME は、Kubernetes クラスタのコントロール プレーンへのネットワーク トラフィックを制御するファイアウォール ルールの名前に置き換えます。

        2. アダプター ポートをリストに追加するようにルールを更新します。

          gcloud compute firewall-rules update FIREWALL_RULE_NAME \
    --allow tcp:443,tcp:10250,tcp:ADAPTER_PORT

          ADAPTER_PORT は、指標アダプタがリッスンしているネットワーク ポートに置き換えます。

      5. Kubernetes ネットワーク ポリシーが指標アダプタ Pod へのトラフィックをブロックしていないことを確認します。

        kubectl get networkpolicy -n custom-metrics,kube-system

        ポリシーを確認して、コントロール プレーンまたは API サーバーから ADAPTER_PORT の ADAPTER_SERVICE への上り（内向き）トラフィックが許可されていることを確認します。

    • 空のリスト []: この出力は、アダプタは実行されているが、特定の指標を取得できないことを意味します。これは、アダプタの構成または指標ソース自体に問題があることを示しています。

      • アダプタ Pod の問題: 指標アダプタ Pod のログを調べて、API 呼び出し、認証、指標の取得に関連するエラーがないか確認します。ログを検査する手順は次のとおりです。

        1. アダプタ Pod の名前を確認します。

          kubectl get pods -n ADAPTER_NAMESPACE

        2. ログを表示します。

          kubectl logs ADAPTER_POD_NAME \
    -n ADAPTER_NAMESPACE

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

          • ADAPTER_POD_NAME: 前の手順で特定したアダプタ Pod の名前。
          • ADAPTER_NAMESPACE: アダプタ Pod が存在する Namespace（custom-metrics や kube-system など）。

      • ソースにデータがない: 指標がソースシステムに存在しない可能性があります。Metrics Explorer などのモニタリング ツールを使用して、指標が存在し、名前とラベルが正しいことを確認します。

HorizontalPodAutoscaler がスケールダウンに失敗する問題のトラブルシューティング

このセクションでは、HorizontalPodAutoscaler がワークロードを想定どおりにスケールダウンしない理由について説明します。

症状:

HorizontalPodAutoscaler はワークロードを正常にスケールアップしますが、CPU 使用率などの指標が低い場合でもスケールダウンできません。

原因:

この動作は、不完全な情報に基づいて迅速にスケールアップ / ダウンしたり、スケールダウンしたりすることを防ぐように設計されています。主な理由は次の 2 つです。

  • 複数の指標を使用する: Horizontal Pod Autoscaler は、最も多くのレプリカを必要とする指標に基づいてスケーリングします。複数の指標がある場合、すべての指標がレプリカの削減が必要であることを示していない限り、ワークロードはスケールダウンされません。1 つの指標でレプリカ数が多いことが求められると、他の指標が低くてもスケールダウンが防止されます。
  • 使用できない指標: 指標が使用できなくなった場合（多くの場合 <unknown> と表示されます）、HorizontalPodAutoscaler はワークロードのスケールダウンを保守的に拒否します。使用量が実際にゼロであるか、指標パイプラインが破損しているかによって、指標が欠落しているかどうかを判断できません。この問題は、レートベースのカスタム指標（messages_per_second など）でよく発生します。アクティビティがないとデータのレポートが停止し、Horizontal Pod Autoscaler が指標を利用不可と認識してスケールダウン オペレーションが停止します。
  • スケーリング ポリシーからのスケールダウン遅延: HorizontalPodAutoscaler の behavior フィールドを使用すると、スケーリング ポリシーを構成できます。スケールダウンのデフォルト ポリシーには、300 秒（5 分）の安定化ウィンドウが含まれています。この期間中、指標の値が目標しきい値を下回っても、HorizontalPodAutoscaler はレプリカ数を減らしません。このウィンドウにより急激な変動は防止されますが、スケールダウンが予想よりも遅くなる可能性があります。

解決策:

次の解決策をお試しください。

  1. 複数の指標と使用できない指標については、問題の原因となっている指標を診断します。

    kubectl describe hpa HPA_NAME -n NAMESPACE_NAME

    出力の Metrics セクションでステータスが <unknown> の指標を探し、Events セクションで FailedGetCustomMetric や FailedGetExternalMetric などの警告を探します。パイプラインのデバッグの詳細については、カスタム指標と外部指標のトラブルシューティングをご覧ください。

  2. 使用できない指標の場合、トラフィックの少ない期間に指標が使用できなくなった場合（レートベースの指標でよくある）、次のいずれかの解決策を試してください。

    • 可能な場合は、レートベースの指標ではなくゲージベースの指標を使用します。キュー内のメッセージの合計数（subscription や num_undelivered_messages など）のようなゲージ指標は、値が 0 であっても、値を一貫して報告するため、HorizontalPodAutoscaler はスケーリングの決定を確実に行うことができます。
    • 指標ソースがゼロ値をレポートしていることを確認します。カスタム指標を制御する場合は、データをまったく送信するのではなく、非アクティブ期間中に 0 を公開するように構成します。

  3. スケーリング ポリシーからのスケールダウン遅延については、スケールダウンのデフォルトの 5 分間の安定化ウィンドウが長すぎる場合は、カスタマイズします。HorizontalPodAutoscaler マニフェストの spec.behavior.scaleDown セクションを調べます。stabilizationWindowSeconds を小さくすると、指標が低下した後にオートスケーラーがより迅速にスケールダウンできるようになります。これらのポリシーの構成の詳細については、Kubernetes ドキュメントのスケーリング ポリシーをご覧ください。

次のステップ

  • このドキュメントで問題を解決できない場合は、サポートを受けるで、次のトピックに関するアドバイスなど、詳細なヘルプをご覧ください。