gke-alert-configuration

GKE アラートの設定

このスキルでは、Google Cloud Managed Service for Prometheus と Terraform を使用して、Google Kubernetes Engine のワークロード向けに堅牢で重要なシグナルを捉えるアラートポリシーを作成するためのガイドラインとベストプラクティスを提供します。アラートのノイズを最小限に抑えながら、4 つのゴールデンシグナルと主要なクラスターの健全性メトリクスを包括的にカバーできます。

---

帰属情報

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

重要なルール

• GKE 以外のスタンドアロンランタイムに対する除外条件とスコープのリダイレクト：
  • このスキルの対象は、PromQL と Google Cloud Managed Service for Prometheus を使用する Google Kubernetes Engine（GKE）の ワークロード、クラスター、サービスに厳密に限定されます。
  • スタンドアロンの Compute Engine 仮想マシンや、GKE を使用しないスタンドアロンの Cloud Run サービスなど、GKE 以外のコンピューティングランタイムには使用しないでください。
  • 停止して、直接回答してください（ファイルは編集しないでください）：ユーザーが GKE 以外のコンピューティングインフラストラクチャ向けのアラート設定を依頼した場合：
    1. ディスク上の Terraform ファイルを記述、作成、編集、検証しないでください。
    2. 直ちに処理を停止し、チャットでユーザーに直接回答してください：
       • 対象範囲外であることを明示する：スタンドアロンの Compute Engine 仮想マシンのモニタリングやスタンドアロンの Cloud Run のモニタリングは、GKE ワークロード向けに設計された、Google Cloud Managed Service for Prometheus と PromQL を使用するこの GKE 専用の PromQL アラートスキルの対象範囲外であることを明確に伝えてください。
       • GKE の PromQL アラートを生成しない：GKE 以外のインフラストラクチャ向けに、Kubernetes の PromQL アラートポリシーを作成または生成したり、Kubernetes のコンテナ、ポッド、ノードのリソースを捏造したりしないでください。
       • ユーザーを適切な方法へ案内する： compute.googleapis.com/instance/cpu/utilization や run.googleapis.com/request_latencies などの標準的な Google Cloud Monitoring 指標を、condition_threshold を使用する標準の google_monitoring_alert_policy または MQL と組み合わせて使用するよう案内してください。または、関連する専門の Cloud オブザーバビリティスキルを推奨してください。
• kube-state-metrics（KSM）の必須コストガードレール：
  • Google Cloud Managed Service for Prometheus でオープンソースの kube-state-metrics をデプロイすると、指標の取り込みに料金が発生します。
  • まず停止して許可を求めてください（ファイルは編集しないでください）：依頼されたアラートルールが Tier 2 KSM 指標（kube_cronjob_*、 kube_pod_status_phase、kube_persistentvolume_*、 kube_deployment_*、kube_statefulset_*、kube_job_*、 kube_daemonset_* など）に依存する場合、ユーザーの承認を得る前に Terraform ファイルを記述、作成、編集、検証したり、アラートポリシーを生成したりしないでください。
  • 代わりに、直ちに処理を停止し、ユーザーに直接回答して、次のことを行ってください：
    1. 依頼されたアラートには kube-state-metrics が必要であることをユーザーに伝えてください。
    2. コストへの影響を説明してください： kube-state-metrics を使用すると、Google Cloud Managed Service for Prometheus でサンプルの取り込みに料金が発生することを詳しく説明してください。
    3. 明示的な許可を求めてください：KSM に依存するアラート設定を想定、有効化、または生成する前に、ユーザーの明示的な許可を求めてください。
    4. フィルタリングまたは許可リストの設定を推奨してください： metricRelabeling（action: keep）を使用する PodMonitoring リソースや、KSM の --metric-allowlist などで、必要な指標だけをフィルタリングまたは許可リストに登録し、取り込みコストを最小限に抑える方法を提案し、推奨してください。具体的な許可リストの例を示してください。
  • 可能な場合は常に、metrics_and_alerts_catalog.md に記載されている、KSM を使用しないネイティブな代替手段（Tier 1 cAdvisor または GKE のネイティブ指標）を優先してください。たとえば、 kube_pod_container_resource_limits の代わりに container_memory_working_set_bytes と container_spec_memory_limit_bytes を使用してください。
  • 回答では Tier と追加コストを明示してください：アラートポリシーを生成または推奨するすべての回答で、その分類 Tier とコストへの影響を明示してください：
    • Tier 1 のネイティブ指標または標準指標（GKE 組み込み指標、cAdvisor の container_*、kubelet のボリューム統計、kubelet のノード状態、コントロールプレーン指標。詳細は metrics_and_alerts_catalog.md を参照）： KSM による追加コストがゼロの Tier 1 ネイティブ指標または標準指標であることを伝えてください。
    • Tier 2 KSM 指標：Tier 2 の KSM 依存指標であることを伝え、上記の許可および許可リストに関するガードレールに従ってください。 (ヒント：一般に、リソースの状態やメタデータを表す kube_ プレフィックスの指標は Tier 2 に該当します。)
• 承認済みファイル編集の計画・検証・実行ループ：ワークスペース内の承認済み Terraform ファイルを変更、追加、またはマージする場合は、次の 3 段階のワークフローに従ってください：
  1. 計画：提案するポリシーリソース名、PromQL 式、グループ化ラベル、期間を含む、構造化された変更計画（changes.json）を作成します。
  2. 検証：編集前検証スクリプト（python3 scripts/validate_config.py --plan changes.json）を実行し、PromQL の文法、ルックバック期間、期間ルールを検証して、重複するシグナルがないことを確認します。
  3. 実行：計画の検証に合格したら、対象の Terraform 設定（alerts.tf）に変更をそのまま適用またはマージします。
  4. 注：質問への回答や Terraform スニペットをチャットで直接提示する場合など、ディスク上の変更が求められていない場合は、完全で有効な Terraform HCL ブロックを回答に出力してください。
• 4 つのゴールデンシグナルとクラスターの健全性を設定する：対象の Kubernetes ワークロードまたはサービスについて、常に次のアラート範囲が確保されるようにしてください：
  1. レイテンシ（P95 応答時間）
  2. エラー（Fast Burn 1 時間／5 分、係数 14.4、Slow Burn 6 時間／30 分、係数 6.0 などのマルチウィンドウ・マルチバーンレート SLO アラート。単純な固定比率は使用しないでください）
  3. トラフィック（absent() または default 0 構文による急激な減少または指標の完全な消失、あるいは過負荷による急増）
  4. 飽和（メモリ上限の使用率のみ）：クラスターまたはプロジェクトのアラートポリシーを説明または設定する場合、メモリ飽和（container_memory_working_set_bytes / container_spec_memory_limit_bytes）のみを含めてください。CFS クォータによってスロットリングされる圧縮可能なリソースであり、圧縮不可能な致命的終了（OOM）を引き起こすものではないため、CPU 飽和アラートを含めたり、container_cpu_usage_seconds_total をアラート指標として列挙したりしないでください。
  5. クラスターの健全性（ポッドの CrashLoop、ノードの NotReady）
• PromQL のみ（Managed Prometheus）：PromQL を使用する condition_prometheus_query_language を必ず使用してください。明示的に依頼された場合を除き、MQL または標準の condition_threshold は使用しないでください。Google Cloud Managed Service for Prometheus は、GKE の標準的なテレメトリー取り込み経路です。
• Terraform のみ：生成するオブザーバビリティ設定は、alerts.tf や variables.tf などの Terraform（.tf）ファイルとしてのみ記述してください。
• 動的な複数リソースのアラート（ハードコーディング禁止）：明示的に依頼された場合を除き、特定のポッド名、ノード名、サービス名をアラート条件にハードコーディングしないでください。アラートポリシーは、リソースを動的に対象とするように記述してください：
  • 常に、単一のインスタンスに絞り込むのではなく、グループ化集計（by (cluster, namespace, service, pod, container)）を使用してください。これにより、単一のアラートポリシーで各サービスまたはポッドを個別に動的に追跡できます。
  • 設定を複数の環境で再利用できるよう、常に project_id、 cluster_name、namespace の Terraform 変数（var.project_id、 var.cluster_name、var.namespace）を宣言して使用してください。これらの変数は必ず variables.tf（または設定内）で定義し、ポリシーまたは PromQL ラベルマッチャーで 3 つすべてを参照してください。
• ルックバックに重複した期間を設定しない：
  • PromQL 式ですでに集約ルックバック期間（increase(...[15m]) > 3 やマルチウィンドウ SLO バーンレートなど）を使用している場合、クエリの時間範囲によって一時的なスパイクはすでに平滑化されています。
  • PromQL のルックバック期間に Terraform の期間を追加すると、平滑化の利点が得られないまま平均検出時間（MTTD）が長くなります。
  • この場合、Terraform の duration = "0s"（または "60s"）を設定してください。[15m] に対して duration = "300s" を設定しないでください。重要な CrashLoop アラートの検知が最大 20 分（15 分＋5 分）遅れるためです。
  • duration = "300s" は、kube_node_status_condition == 0 などの瞬時ゲージ条件にのみ使用してください。
• 単純な比率ではなく SLO バーンレートを使用する：エラー率のアラートでは、トラフィックが少ない場合に過剰な誤報が発生する単純なエラー率比率（rate(5xx)/rate(total) > 0.05）ではなく、常にマルチウィンドウ・マルチバーンレート（MWMBR）SLO アラート（99% SLO に対して 1 時間と 5 分のウィンドウで 14.4 倍のバーンレートなど）を生成してください。
• 堅牢なトラフィック減少の検出（absent()／default 0）：トラフィックがゼロに減少していないかを監視する場合、rate(...) == 0 のみを使用しないでください。リクエストがない場合、Prometheus の時系列は完全に消失し、0 ではなく空のベクトルとして評価されるためです。sum(rate(...[5m])) default 0 == 0 のような default 0 構文、または absent(...) == 1 を使用してください。
• 通知チャネル：デフォルトでは、ユーザーからの入力なしに通知チャネルを設定しないでください。ユーザーが通知チャネルを明示的に指定した場合は、そのチャネルを使用するようにアラートを設定してください。それ以外の場合は、通知チャネルを設定するかどうか、回答でユーザーに必ず確認してください。
• GKE 指標とオープンソースアラートのカタログを参照する：評価スイートまたはアラートポリシーを設計または生成する場合は、公開されている GKE 指標（kubernetes.io/）とオープンソースの Kubernetes アラート（awesome-prometheus-alerts）について、 metrics_and_alerts_catalog.md を参照してください。
• 平易な英語で回答する：回答には、アラートの動作について平易な英語での説明を含めてください。アラートが何を測定するか、しきい値が何を表すか、トリガーが何を示すかを説明してください。
• ユーザーラベル：このスキルで作成されたポリシーを追跡できるよう、すべての google_monitoring_alert_policy リソースに user_labels ブロックを含めてください：

  user_labels = {
    created-with-google-skill = "gke-alert-configuration"
  }
  

---

Terraform でのアラートポリシーの構造

アラートポリシーは、condition_prometheus_query_language を指定した google_monitoring_alert_policy リソースを使用して定義する必要があります。必ず variables.tf で project_id、cluster_name、namespace の変数を宣言してください。

# variables.tf
variable "project_id" {
  type        = string
  description = "Google Cloud Project ID"
}

variable "cluster_name" {
  type        = string
  description = "GKE Cluster Name"
}

variable "namespace" {
  type        = string
  description = "Target Kubernetes Namespace"
  default     = "default"
}

variable "slo_target" {
  type        = number
  description = "SLO Target fraction (for example 0.99 for 99%)"
  default     = 0.99
}

# alerts.tf
# Example: Multi-Window Multi-Burn-Rate (MWMBR) SLO Alert (Fast Burn: 14.4x, 1h & 5m windows)
resource "google_monitoring_alert_policy" "k8s_service_error_rate_slo" {
  project      = var.project_id
  display_name = "[K8s] ${var.cluster_name} - Service Error Rate SLO Fast Burn"
  combiner     = "OR"

  conditions {
    display_name = "Error Budget Fast Burn (14.4x over 1h and 5m)"
    condition_prometheus_query_language {
      query    = <<-EOT
        (
          (
            sum(
              rate(
                http_requests_total{
                  cluster="${var.cluster_name}",
                  namespace="${var.namespace}",
                  status=~"5.."
                }[5m]
              )
            ) by (service, namespace, cluster)
            /
            sum(
              rate(
                http_requests_total{
                  cluster="${var.cluster_name}",
                  namespace="${var.namespace}"
                }[5m]
              )
            ) by (service, namespace, cluster)
          ) > (1 - ${var.slo_target}) * 14.4
        )
        and
        (
          (
            sum(
              rate(
                http_requests_total{
                  cluster="${var.cluster_name}",
                  namespace="${var.namespace}",
                  status=~"5.."
                }[1h]
              )
            ) by (service, namespace, cluster)
            /
            sum(
              rate(
                http_requests_total{
                  cluster="${var.cluster_name}",
                  namespace="${var.namespace}"
                }[1h]
              )
            ) by (service, namespace, cluster)
          ) > (1 - ${var.slo_target}) * 14.4
        )
      EOT
      duration = "0s"
    }
  }
}

---

テレメトリ指標と PromQL の例

GKE 指標（kubernetes.io/）、コミュニティのオープンソースアラート （awesome-prometheus-alerts）、KSM のコストガードレール、KSM を使わないネイティブな代替手段については、以下を必ず読み、従ってください。

• metrics_and_alerts_catalog.md

Golden Signals のそれぞれに対応する具体的な PromQL クエリについては、以下を必ず読み、従ってください。

• promql_queries.md

GKE クラスタの前提条件、Google Cloud Managed Service for Prometheus の収集の有効化、PodMonitoring によるカスタムスクレイピングの設定、コントロールプレーン指標（API Server、Controller Manager、Scheduler）の収集の有効化については、以下を必ず読み、従ってください。

• gke_configuration_prerequisites.md

---

ツール用スクリプトと検証ループ

リポジトリで作業する際は、validate_config.py スクリプトを使用して変更計画と Terraform 設定を検証してください。

• 編集前の計画検証：提案するポリシー、クエリ、期間を指定した changes.json 計画を作成し、編集前に検証します。
  • コマンド：python3 scripts/validate_config.py --plan changes.json
• 編集後およびディレクトリの検証：既存または変更済みの Terraform ファイルをディレクトリ内でスキャンし、重複や構文エラーがないことを確認します。
  • コマンド：python3 scripts/validate_config.py --directory [TARGET_TF_DIR] --cluster-var "${var.cluster_name}"
  • 単一ファイルの検証：python3 scripts/validate_config.py --file [PATH_TO_TF_FILE]

---

技術上の考慮事項と注意点

• ルックバックウィンドウと継続時間バッファー：
  • increase(...[15m]) のような集約ルックバックウィンドウやマルチウィンドウ SLO レートをすでに使用しているアラートには、大きな duration = "300s" バッファーを追加しないでください。
  • increase(...[15m]) > 3 の [15m] ウィンドウによって、スパイクはすでに平滑化されています。duration = "300s" を追加すると、再起動回数がさらに連続5分間 3 を超えた状態であることが条件となり、MTTD が増加し、アラートが合計で最大20分遅れます。
  • ルックバックウィンドウ関数を使用する場合は、duration = "0s" または "60s" を使用してください。duration = "300s" は、kube_node_status_condition == 0 のような、生の瞬時ゲージ条件に限定してください。
• クラスターのアラートにはメモリ飽和のみを使用：
  • クラスターまたはワークロードのモニタリングに CPU 飽和アラートを設定しないでください。CPU は圧縮可能（CFS スケジューラーによってスロットリングされる）ですが、メモリは圧縮できず、OOMKill を引き起こします。
  • container_memory_working_set_bytes と container_spec_memory_limit_bytes を使って、メモリ飽和を設定してください。
• リソース制限がない場合の盲点（必須の説明）：使用量を制限値（container_spec_memory_limit_bytes など）と比較する飽和アラートは、ワークロードの Kubernetes マニフェストでメモリ制限が明示的に設定されていない場合、解決に失敗するか、NaN を返します。
  • 必須の指示：使用量と制限値を比較するメモリ飽和アラート（container_spec_memory_limit_bytes を使う非 KSM の cAdvisor 代替手段を含む）を生成、説明、または推奨する場合は必ず、飽和クエリが解決され（NaN を返したり、解決に失敗したりしない）ために、Kubernetes の Pod 仕様またはマニフェストでコンテナのメモリ制限（resources.limits.memory）を明示的に設定する必要があることを、回答でユーザーに明確に説明し、警告してください。
• 線形ディスク予測（predict_linear）：predict_linear(kubelet_volume_stats_available_bytes[6h:5m], 4 * 24 * 3600) < 0 を使ってボリュームの枯渇を予測する場合、predict_linear は直近のルックバックウィンドウ（例：6時間）の線形回帰に基づいて、使用可能なディスク容量が 0 を下回る時期（例：4日以内）を予測することを説明してください。kubelet_volume_stats_available_bytes は、KSM による追加料金がゼロの Tier 1 ネイティブ kubelet メトリクスであることを明記してください。
• API サーバーのエラーとクライアントメトリクス：
  • apiserver_request_total と rest_client_requests_total は、KSM による追加コストがゼロの Tier 1 コントロールプレーンメトリクスです。apiserver_request_total は API サーバーの各エンドポイントにおける 5xx HTTP エラー率を監視し、rest_client_requests_total は API サーバーと通信する REST クライアントから送信された 4xx および 5xx リクエストを監視することを説明してください。
• トラフィック消失時の注意点（absent()／default 0）：
  • トラフィックが完全にゼロになると、Prometheus と GMP は http_requests_total の時系列データの出力を停止します。
  • sum(rate(...[5m])) == 0 は空のベクトルとして評価されるため、アラートが発火しません。
  • トラフィックの完全な消失を確実に検出するには、必ず sum(rate(...[5m])) default 0 == 0 または absent(...) == 1 を使用してください。
• CrashLoop と通常の再起動の違い：コンテナが時折再起動するのは、ジョブの完了や軽微なローリングアップデートなど、正常な場合があります。ノイズを避けるため、単発の再起動ではなく、kube_pod_container_status_restarts_total を使用して、duration = "0s" で15分間に3回を超える再起動など、頻繁な再起動をアラートしてください。
• ノードのアップグレード：GKE クラスターのアップグレード中は、ノードがドレインされて再起動するため、「Node NotReady」アラートが発火することがあります。メンテナンス時間帯にこれらのアラートが発火する可能性があることをユーザーに警告するか、サポートされている場合はメンテナンス時間帯の設定を提案してください。

---

追加リソース

• Google Cloud Managed Service for Prometheus のドキュメント
• GKE の可観測性とモニタリングの概念
• Terraform での Google Cloud アラートポリシー
• [Google Cloud Monitoring の料金](https://docs.cloud.google.com/monitoring/pricing.md.txt
• Google SRE ワークブック：SLO のアラート設定
• Awesome Prometheus Alerts リポジトリ