gke-workload-scaling-troubleshooting

GKE ワークロードのスケーリングに関するトラブルシューティングスキル

このスキルを使用して、GKE で発生するHorizontalPodAutoscaler（HPA）の障害を体系的に診断し、解決します。対象には、<unknown> と報告されるメトリクス、FailedGet* イベント、リソースリクエストの不足、カスタム／外部メトリクスパイプラインの障害、スケールアップまたはスケールダウンを拒む HPA、ゼロへのスケール／ゼロからのスケールに関する問題、大規模クラスターでの HPA の反応の遅れが含まれます。このスキルは非対話型で動作し、マニフェストや構成の修正を提案する前に、読み取り専用の診断範囲を徹底します。

HPA／VPA オブジェクトの構成とスケーリングのベストプラクティスについては、代わりに gke-workload-scaling スキルを使用してください。このスキルは障害の診断に焦点を当てています。

帰属情報

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、 必ず Usage Attribution をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコードでは実行しないでください）では、gcloud の先頭に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-workload-scaling-troubleshooting)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:gke-workload-scaling-troubleshooting) を追加してください。

🔍 診断と解決のワークフロー

ステップ 0：非対話型のコンテキスト検出とドライランへのフォールバック

1. パラメーターの抽出：ユーザープロンプト、アクティブな SETTINGS.md、または環境のデフォルト値から、必要なコンテキスト（project_id、 cluster_name、cluster_location、hpa_name、workload_name、 workload_namespace）を非対話型で抽出します。

   • 省略されている場合、workload_namespace は default に設定します。
   • 不足しているクラスターのパラメーターは、アクティブな環境（kubectl config current-context または gcloud config get-value project）から推測します。

2. クラスター認証情報とフォールバックモード：

   • 認証情報の取得を試みます：gcloud container clusters get-credentials {cluster_name} --location {cluster_location} --project {project_id}。
   • フォールバック／ドライランモード：クラスターに到達できない、クラスターが存在しない、またはライブコマンドの実行に失敗した場合（サンドボックス環境での評価、ドライランモード、オフライン分析など）：
     • リソースの枯渇やコンテキストの過剰な増大を避けるため、再試行回数を制限します。
     • 人間のオペレーターが実行するための正確な kubectl／gcloud 診断コマンドを直ちに提示します。
     • 報告された症状に基づいて根本原因の分析をまとめ、提案する GitOps の修正を出力します。

---

ステップ 1：HPA を調査し、症状を分類する

調査は必ず kubectl describe hpa から始め、一致する分岐に進みます。重要なセクションは、Metrics（値が <unknown> の場合、HPA がメトリクスを取得できていないか、パイプラインが壊れています）、Conditions（AbleToScale、ScalingActive、ScalingLimited — False の状態は障害を示します）、および Events（FailedGetScale や FailedGetResourceMetric などの具体的な理由）です。

診断コマンド：

kubectl describe hpa {hpa_name} -n {workload_namespace}
kubectl get hpa {hpa_name} -n {workload_namespace} -o yaml

過去のイベントを確認するには、Cloud Logging を検索します（HPA のイベントは、ライブの Events リストから消えた後も残ります）。

resource.type="k8s_cluster"
resource.labels.cluster_name="{cluster_name}"
resource.labels.location="{cluster_location}"
logName="projects/{project_id}/logs/events"
jsonPayload.involvedObject.kind="HorizontalPodAutoscaler"

シグナルに応じて分岐します。

• FailedGetScale、FailedComputeMetricsReplicas、Error 400 ... label is not allowed、または複数の HPA の競合によるレプリカ数の変動 → 分岐 A （構成エラー）。
• FailedGetResourceMetric、unable to fetch pod metrics、または multiple services selecting the same target → 分岐 B（ワークロードとサービスのエラー）。
• <unknown> のカスタム／外部メトリクス、FailedGetExternalMetric / FailedGetCustomMetric、または no known available metric versions found → 分岐 C（Metrics API とデータの可用性）。
• すべての Conditions が True／エラーはないが、ワークロードがスケールアップもスケールダウンもしない → 分岐 D（正常だが予期しないスケーリング）。
• minReplicas: 0 に設定されたワークロードが、ゼロへのスケールまたはゼロからのスケールを行わない → 分岐 E（ゼロへのスケール／ゼロからのスケール）。
• HPA は正しく構成されているが、HPA オブジェクトが多いクラスターで反応が遅い → 分岐 F（大規模クラスターでの再計算の遅延）。

---

ステップ 2：解決策 — 一致する分岐に進む

ステップ 1 で分類したシグナルに基づいて、以下の相互排他的な分岐（A～F）から1 つに進みます。これらは代替の手順であり、順番にすべて実行するものではありません。分岐の修正を適用したら、ステップ 3 に進み、レビュー可能な GitOps の変更として提示します。

分岐 A：HorizontalPodAutoscaler の構成エラー

• FailedGetScale — unable to get the target's current scale: ... "TARGET" not found：scaleTargetRef が、スケーラブルな既存のワークロードを参照していません。

  • scaleTargetRef の name、kind、apiVersion が、対象ワークロードのメタデータと正確に一致していることを確認します。
  • 対象のワークロードが HPA と同じ名前空間に存在することを確認します（-n を指定し忘れると、オブジェクトが default に作成され、不一致が発生します）。
  • 対象はスケーラブルな種類（Deployment、StatefulSet、ReplicaSet）である必要があります。DaemonSet をオートスケールすることはできません。

• FailedComputeMetricsReplicas — invalid metrics (1 invalid out of 1)： メトリクスの type と target が一致していません。

  • type: Utilization の場合、ターゲットは averageUtilization である必要があります。
  • type: AverageValue の場合、ターゲットは averageValue である必要があります。

• unable to fetch metrics from external metrics API: googleapi: Error 400: Metric label: 'LABEL' is not allowed：metric.selector.matchLabels のキーが無効です。

  • 許可されていないラベルを削除または修正します。有効なフィルター可能ラベルは Cloud Monitoring のメトリクスに関するドキュメントで確認してください。

• レプリカ数が変動する／異なる HPA から矛盾する SuccessfulRescale イベントが発生する：複数の HPA が spec.scaleTargetRef で同じワークロードを対象にしており、競合しています。この状態を示す専用の condition はありません。kubectl get hpa -n {workload_namespace} -o yaml を実行し、重複する scaleTargetRef の値がないか確認します。

  • すべてのメトリクスを1 つの HPA オブジェクトに統合し（spec.metrics のうち最も高い値が採用されます）、重複したオブジェクトを削除します。

---

ブランチ B：ワークロードとサービスのエラー

• ScalingActive: False、reason FailedGetResourceMetric、message unable to compute the replica count（または unable to fetch pod metrics が継続する場合）：HPA は、コンテナの リソースリクエストに対する割合として使用率を計算しますが、Pod 内の少なくとも 1 つのコンテナで、スケーリング対象のリソース（cpu または memory）に対する resources.requests エントリが不足しています。

  • Pod 仕様内の すべての コンテナ（サイドカーを含む）に、スケーリング対象のリソースに対する resources.requests を追加してください。メトリクスサーバーの起動直後に unable to fetch pod metrics が短時間表示されるのは正常で、自然に解消されます。

• multiple services selecting the same target of HPA_NAME: SERVICE： トラフィックベースのオートスケーリングには、Service とワークロードの関係が 1 対 1 である必要がありますが、複数の Service のセレクターがワークロードの Pod に一致しています。

  • 対象の Service のセレクターを一意にしてください（ワークロードとその Service のみに固有のラベルを追加します）。または、他の Service のセレクターを絞り込み、ワークロードの Pod に一致しないようにしてください。

---

分岐 C：メトリクス API とデータの可用性（カスタム／外部メトリクス）

カスタム／外部メトリクスのパイプラインは、HPA コントローラー → Kubernetes メトリクス API サーバー → メトリクスアダプター（例：custom-metrics-stackdriver-adapter）→ メトリクス ソース（Cloud Monitoring／Prometheus）です。メトリクス値が<unknown>になったり、 FailedGetExternalMetric／FailedGetCustomMetricイベントが発生したりする場合は、このパイプラインに問題があります。

1. アダプターは登録され、利用可能ですか？

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

   v1beta1.custom.metrics.k8s.ioや v1beta1.external.metrics.k8s.ioがAVAILABLE: Trueの状態であることを確認してください。Falseまたは存在しない場合は、 アダプターがクラッシュしているか、設定に問題があります。custom-metricsまたはkube-system名前空間にある Podのログを調べ、権限、接続、または 「metric not found」エラーがないか確認してください。

2. メトリクス API を直接クエリします（パイプライン全体をテストするため、HPAを介しません。 jqは省略可能です）。

   kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/{workload_namespace}/{metric_name}" | jq .
   kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/namespaces/{workload_namespace}/pods/*/{metric_name}" | jq .
   

3. 結果を解釈します。

   • 値を含む有効なJSON → パイプラインは機能しています。問題はHPA マニフェストにあります（メトリクス名の誤記、またはmatchLabelsの誤り）。
   • Error from server (Service Unavailable) → ネットワーク分離により、 コントロールプレーンからアダプターに接続できません。既存の tcp:443とtcp:10250に加えて、アダプターのtargetPortをコントロールプレーンのファイアウォールルールに追加してください。 gcloud compute firewall-rules list --filter="name~gke-{cluster_name}-[0-9a-z]*-master"でルールを特定し、 NetworkPolicyがアダプターのPodへのイングレスをブロックしていないことも確認してください。
   • 空のリスト[] → アダプターは稼働していますが、メトリクスを取得できません。 アダプターのPodログを調べ、Metrics Explorerで、想定される名前とラベルのメトリクスがソースに実際に存在することを確認してください。

• unable to fetch metrics from custom metrics API: no known available metric versions found：通信の問題です（アップグレード／修復中にコントロールプレーンが一時的に利用できなかった、またはアダプターのPodが正常でないか、登録されていない）。メトリクスソースの問題ではありません。コントロールプレーンの状態と通知を確認し、アダプターのPodが再起動なしでRunningであること（kubectl get pods -n custom-metrics,kube-system -o wide）を確認したうえで、 APIServicesがAVAILABLE: Trueであることを再確認してください。一時的な問題であることがよくあります。

• googleapi: Error 400: The supplied filter ... will not return any time series：クエリは有効ですが、条件に一致するデータがありません（値が0である場合とは異なります）。対象期間中、アプリケーションがメトリクスを書き込んでいませんでした。 メトリクス名とラベルがアプリケーションの出力と一致すること、アプリケーションに権限があり稼働していたことを確認し、 メトリクス出力エラーがないかアプリケーションのログを確認してください。

---

ブランチ D：正常だが、想定どおりにスケーリングされない

HPA の条件は True でエラーも表示されませんが、想定どおりにスケーリングされません。

• スケールアップしない場合 — 次の順に確認してください。

  • レプリカ数の上限：currentReplicas がすでに minReplicas／ maxReplicas に達しています（ScalingLimited 条件を参照）。上限値を調整してください。
  • 許容範囲：現在値と目標値の比率が 0.9～1.1 の範囲内にある間、Kubernetes は変化を無視します（デフォルトの**許容範囲は 10％**です）。例：目標 CPU 使用率が 85％、現在の使用率が 93％の場合、比率は約 1.094 < 1.1 となるため、スケールアップしません。メトリクスがこの範囲を超えるまで待つか、許容範囲を変更してください。
  • Ready でない Pod：Pending／Ready でない Pod は計算から除外されます。根本的なスケジューリングまたはプローブの問題を解決してください。
  • 同期の遅延：しきい値を超えてからアクションが実行されるまで、15～30 秒の遅延が発生するのは正常です。

• スケールダウンしない場合 — 次の順に確認してください。

  • 複数のメトリクス：HPA は必要なレプリカ数が最も多いメトリクスを使用するため、すべてのメトリクスが一致しない限りスケールダウンしません。
  • 利用できないメトリクスによるスケールダウンの停止：いずれかのメトリクスが <unknown> になると、HPA は安全を優先してスケールダウンを拒否します。トラフィックがゼロになると報告を停止する、レートベースのカスタムメトリクスでよく発生します。ゲージメトリクス（例：num_undelivered_messages）を使用するか、データを送信しないのではなく、非アクティブ時にソースから 0 を送信してください。
  • スケールダウンの安定化ウィンドウ：デフォルトの behavior.scaleDown.stabilizationWindowSeconds は **300 秒（5 分）**です。 スケールダウンを速める必要がある場合は、値を小さくしてください。

---

ブランチ E：ゼロへのスケール／ゼロからのスケール（GKE 1.37 以降）

HPA（minReplicas: 0）を使用したワークロードのレプリカ数ゼロへのスケール、およびゼロからのスケールは、GKE 1.37 以降でサポートされています。

• ゼロにスケールしない場合：

  • minReplicas: 0 を設定する必要があります。
  • HPA は Resource（CPU／メモリ）メトリクスのみを使ってゼロにスケールすることはできません。少なくとも 1 つの External または Object メトリクスを設定してください。
  • 複数のメトリクスがある場合は、すべてがゼロと評価される必要があります。
  • 需要がゼロになってから 1→0 になるまで、GKE は 5 分間のスケールダウン安定化ウィンドウを待ちます。
  • <unknown> を示すメトリクスがあると、スケールダウンは一時停止します（ブランチ D を参照）。

• ゼロからスケールアップしない場合：kubectl describe hpa {hpa_name} を実行して、次の項目を確認してください。

  • メトリクス：値は > 0 で、<unknown> ではない必要があります。値がない場合は、外部ソース（例：Pub/Sub）が公開しており、Cloud Monitoring が受信していることを確認してください。
  • 条件：正常なアイドル状態では、AbleToScale: True、ScalingActive: True、ScaledToZero: True と表示されます。理由が ScalingDisabledExternalScaleToZero または ScalingDisabledReplicaCountZero で ScalingActive: False の場合、ワークロードは手動でゼロにスケールされています（例：kubectl scale）。そのため、自動スケーリングは一時停止しています。Deployment を --replicas=1 にスケールして再開してください。
  • ノードのプロビジョニングによるコールドスタートの遅延が加わる場合があります。Capacity Buffers を使用すると、スタンバイ容量を確保できます。

---

分岐 F：大規模クラスターでの HPA 再計算の遅延

HPA の設定が正しいにもかかわらず反応が遅い場合、クラスターの HPA オブジェクト数が、標準コントローラーが 15 秒の再計算間隔内に処理できる上限を超えている可能性があります。

• 標準コントローラー：最大 300 個の HPA オブジェクトを 15 秒以内に処理（GKE 1.22 以降）。
• Performance HPA プロファイル：最大 1,000 個の HPA オブジェクトを 15 秒以内に処理（GKE 1.31 以降）、または最大 5,000 個の HPA オブジェクトを 15 秒以内に処理（GKE 1.33 以降。有効化対象のクラスターではデフォルトで有効）。

対象となるクラスターで有効化します（これはクラスターの変更です。オペレーターが実行できるよう提示し、実行しないでください）。

gcloud container clusters update {cluster_name} \
    --location {cluster_location} --project {project_id} \
    --hpa-profile=performance

HPA あたりのメトリクス数が多い場合や、カスタムメトリクスアダプターの処理が遅い場合（約 50 ミリ秒超）も、再計算間隔が長くなります。スケーリングの判断を確認できるようにするには、HPA イベントログを有効にし、構造化された HPA 判断ログを確認してください。

---

ステップ 3：GitOps による修正を提案する

読み取り専用の診断範囲を守ってください。ライブ環境への変更を適用しないでください。これには、クラスターやマニフェストの変更（kubectl edit、kubectl patch、kubectl apply、kubectl scale、kubectl delete）と、Google Cloud / gcloud の変更（--hpa-profile などのクラスター更新や、gcloud compute firewall-rules の更新）の両方が含まれます。代わりに、修正した HorizontalPodAutoscaler、PodSpec（resources.requests）、Service セレクター、ワークロードのオートスケーリング設定、または gcloud コマンドを、ユーザーの GitOps パイプライン（Config Sync、Argo CD、Flux など）経由で適用するか、権限のあるオペレーターが適用できるよう、レビュー可能なパッチまたはコマンドとして提示してください。

参考資料

• GKE での水平 Pod オートスケーリングのトラブルシューティング
• 水平 Pod オートスケーリング（概念、Performance HPA プロファイルと制限）
• 水平 Pod オートスケーリングの設定（hpa-profile）
• 水平 Pod オートスケーリングのイベントを表示する
• HPA を使用したゼロへのスケーリングとゼロからのスケーリング
• Kubernetes HorizontalPodAutoscaler（許容範囲とスケーリングポリシー）