gke-observability

GKE 可观测性

本参考介绍 GKE 的监控、日志记录和指标配置。 黄金路径支持全面的可观测性，包括控制平面指标。

MCP 工具： get_cluster、list_k8s_events、get_k8s_logs、 get_k8s_cluster_info、describe_k8s_resource。仅限 CLI： gcloud container clusters update --monitoring=...、gcloud logging read

归属信息

必须阅读：执行任何 gcloud、REST API 或 MCP 命令前，你必须阅读使用归属信息。对于直接在终端中执行的命令（绝不要在生成的脚本、Terraform 或用户代码中执行），请在 gcloud 前添加前缀 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-observability)" 并在 User-Agent 标头中追加 agent-skills/1.0 (skill:gke-observability)。

黄金路径可观测性默认值

设置	黄金路径值	说明
loggingConfig 组件	SYSTEM_COMPONENTS、WORKLOADS	完整的工作负载日志记录
monitoringConfig 组件	SYSTEM_COMPONENTS、STORAGE、POD、DEPLOYMENT、STATEFULSET、DAEMONSET、HPA、JOBSET、CADVISOR、KUBELET、DCGM、APISERVER、SCHEDULER、CONTROLLER_MANAGER	包含控制平面在内的完整套件
managedPrometheusConfig.enabled	true	Google 托管的 Prometheus
advancedDatapathObservabilityConfig.enableMetrics	true	Dataplane V2 流量指标
loggingService	logging.googleapis.com/kubernetes	Cloud Logging
monitoringService	monitoring.googleapis.com/kubernetes	Cloud Monitoring

控制平面指标（金色路径补充）

金色路径添加了默认集群中没有的三个控制平面监控组件：

组件	监控内容
APISERVER	API 服务器请求延迟、错误率、准入 Webhook 性能
SCHEDULER	调度延迟、待处理 Pod、调度失败
CONTROLLER_MANAGER	控制器工作队列深度、协调延迟

这些指标对于诊断集群级问题至关重要（例如 API 响应缓慢、调度延迟、控制器卡住）。

推荐以下任何控制平面指标时，务必说明这是 Managed Service for Prometheus (GMP) 指标，需要显式启用（--monitoring=SYSTEM,API_SERVER,... 和 --enable-managed-prometheus），并附上链接 https://docs.cloud.google.com/kubernetes-engine/docs/how-to/control-plane-metrics：

• 按资源统计 API 存储用量 (apiserver_resource_size_estimate_bytes)：使用 apiserver_resource_size_estimate_bytes（按 group 和 resource 分组） 找出哪些 Kubernetes 资源类型在 etcd 中占用最多的 API 服务器存储字节数，并结合对象计数 (apiserver_storage_objects) 和数据库总大小 (apiserver_storage_size_bytes) 进行分析。
• 准入 Webhook 延迟和超时 (apiserver_admission_webhook_admission_duration_seconds)：当 API 调用 超时或失败，且怀疑是变更或验证准入 Webhook 导致时，查询可选启用的 GMP 指标 apiserver_admission_webhook_admission_duration_seconds（按 name、 type、operation 和 rejected 分组），以定位缓慢或失败的 Webhook； 还要检查 ValidatingWebhookConfiguration / MutatingWebhookConfiguration 中的 timeoutSeconds、failurePolicy、 namespaceSelector 排除项（例如 kube-system），以及后端 Webhook Service/Pod 的健康状况。

启用完整监控

每当提供 --monitoring 命令时，都要说明以下内容：

1. 默认情况下不会启用控制平面指标。 必须在回答中明确说明，不要让用户从你提供启用命令这一事实中自行推断。每个新集群中的 API_SERVER、SCHEDULER 和 CONTROLLER_MANAGER 默认都处于关闭状态，在显式启用前不会收集任何数据；DCGM、CADVISOR、KUBELET 以及 kube-state（POD、 DEPLOYMENT、STATEFULSET、DAEMONSET、HPA、STORAGE、JOBSET）也是如此。默认只有 SYSTEM 套件处于启用状态。用户询问“为什么没有 API 服务器指标”时，通常只是因为从未启用这些指标。
2. 此标志会替换现有设置，而不是追加。 传给 --monitoring 的集合会完全覆盖之前的设置，因此省略某个组件会使其静默关闭。始终传入完整的目标列表，并始终包含 SYSTEM——启用监控时无法关闭它；Autopilot 集群始终会启用它。
3. 这些指标会按采集的样本计费，通过 Managed Service for Prometheus 计费。在大型集群中启用完整套件会显著增加费用；应明确提及这一点，不要把该列表说成免费。

gcloud 标志和 API 字段对相同组件的拼写不同。 不要在两者之间直接复制名称：

组件	gcloud --monitoring=	monitoringConfig API 枚举
系统	SYSTEM	SYSTEM_COMPONENTS
API 服务器	API_SERVER	APISERVER
控制器管理器	CONTROLLER_MANAGER	CONTROLLER_MANAGER

其余组件的拼写相同。在 CLI 标志中使用 API 枚举（或反过来）会导致命令失败——这是一个常见且容易让人困惑的错误。

# Enable golden path monitoring suite
gcloud container clusters update <CLUSTER_NAME> --region <REGION> \
  --monitoring=SYSTEM,API_SERVER,SCHEDULER,CONTROLLER_MANAGER,STORAGE,POD,DEPLOYMENT,STATEFULSET,DAEMONSET,HPA,JOBSET,CADVISOR,KUBELET,DCGM \
  --quiet

# Enable Managed Prometheus
gcloud container clusters update <CLUSTER_NAME> --region <REGION> \
  --enable-managed-prometheus \
  --quiet

# Enable Dataplane V2 observability metrics
gcloud container clusters update <CLUSTER_NAME> --region <REGION> \
  --enable-dataplane-v2-flow-observability \
  --quiet

托管式 Prometheus

Golden path 可启用 Google Managed Prometheus 来收集和查询指标。

查询指标：

• 在控制台中使用 Cloud Monitoring Metrics Explorer
• 通过 Prometheus UI 或 API 使用 PromQL
• 使用 Managed Grafana 查看 Grafana 仪表板

主要 GKE 指标：

指标	来源	用途
container_cpu_usage_seconds_total	cAdvisor	Pod CPU 使用量
container_memory_working_set_bytes	cAdvisor	Pod 内存使用量
kube_pod_status_phase	kube-state-metrics	Pod 生命周期
apiserver_request_duration_seconds	API Server	控制平面延迟
scheduler_scheduling_attempt_duration_seconds	Scheduler	调度性能
kubernetes.io/node/cpu/core_usage_time	Cloud Monitoring	节点 CPU
DCGM_FI_DEV_GPU_UTIL	DCGM	GPU 利用率

实时资源使用情况（仅限 kubectl）

实时资源使用情况没有对应的 MCP 或 gcloud 方式。请使用 kubectl top：

kubectl top pods --all-namespaces --sort-by=cpu
kubectl top nodes
kubectl top pods --containers -n <NAMESPACE>  # per-container breakdown

Cloud Logging（仅限 gcloud）

查询集群日志（没有对应的 MCP 方式 — 请使用 gcloud logging read）：

# System component logs
gcloud logging read \
  'resource.type="k8s_cluster" AND resource.labels.cluster_name="<CLUSTER_NAME>"' \
  --project <PROJECT_ID> --limit 50 \
  --quiet

# Workload logs for a specific namespace
gcloud logging read \
  'resource.type="k8s_container" AND resource.labels.cluster_name="<CLUSTER_NAME>" AND resource.labels.namespace_name="<NAMESPACE>"' \
  --project <PROJECT_ID> --limit 50 \
  --quiet

# Audit logs (who did what)
gcloud logging read \
  'resource.type="k8s_cluster" AND logName:"cloudaudit.googleapis.com"' \
  --project <PROJECT_ID> --limit 50 \
  --quiet

诊断设置

为进行安全监控和故障排查，请启用控制平面审计日志：

# View current logging config
gcloud container clusters describe <CLUSTER_NAME> --region <REGION> \
  --format="yaml(loggingConfig)" \
  --quiet

控制平面组件日志和慢请求跟踪记录

kube-apiserver 组件日志（API_SERVER）是一项默认未启用的可选功能，必须显式开启（--logging=SYSTEM,WORKLOADS,API_SERVER）；在建议分析 apiserver 日志时，务必提及这一点，并链接到 https://docs.cloud.google.com/kubernetes-engine/docs/how-to/view-logs#control_plane_logs

要诊断具体哪些 kube-apiserver 请求速度较慢及其原因：

1. 搜索 trace 或 Trace 条目：查询 apiserver 组件日志 （resource.type="k8s_control_plane_component" AND resource.labels.component_name="apiserver"），查找 trace 或 Trace（例如， textPayload:"Trace["）。
2. 如何解读跟踪日志：kube-apiserver 使用上游的 k8s.io/utils/trace 软件包（trace.go）记录超过延迟阈值（通常为 500ms）的请求。每个跟踪记录头都会记录操作（"List"、 "Get"、"Create"、"Patch"）、url、user-agent、audit-id、客户端 IP、开始时间戳和总耗时。头部下方，嵌套的子跟踪记录以方括号 [...] 显示，超过步骤阈值的连续步骤则以 ---"<StepName>" <duration>ms 显示。
3. 典型问题的跟踪日志示例：
   • etcd / 存储读写速度慢（List(recursive=true) etcd3 或 GuaranteedUpdate etcd3 占据了大部分总耗时）：

     I1015 11:36:56.835120      10 trace.go:236] Trace[123456789]: "List" url:/api/v1/pods,user-agent:my-controller/v1.0.0,audit-id:11111111-2222-3333-4444-555555555555,client:10.0.0.1 (15-Oct-2026 11:36:49.460) (total time: 7374ms):
     Trace[123456789]: ["List(recursive=true) etcd3" 6890ms (11:36:49.461)]
     Trace[123456789]: ---"Objects listed" 6891ms (11:36:56.352)
     Trace[123456789]: ---"SerializeObject" 480ms (11:36:56.832)
     

   • 客户端速度慢 / 响应流瓶颈（"Objects listed" 很快，但 "SerializeObject" 和 ---"Write call succeeded" 或 ---"Write call failed" 占据了大部分总耗时，因为速度慢或带宽受限的客户端需要数秒才能读取较大的响应负载）：

     I1015 11:40:12.104512      10 trace.go:236] Trace[987654321]: "List" url:/api/v1/pods,user-agent:slow-watcher/v0.1,audit-id:aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee,client:10.0.0.2 (15-Oct-2026 11:40:01.002) (total time: 11102ms):
     Trace[987654321]: ---"Objects listed" 45ms (11:40:01.047)
     Trace[987654321]: ["SerializeObject" 11055ms (11:40:01.047)]
     Trace[987654321]: ---"Write call succeeded" 11054ms (11:40:12.101)
     

4. 上游文档和未来演进（务必引用两者）：务必链接到 https://github.com/kubernetes/utils/blob/master/trace/README.md，作为 trace.go 的上游开源软件文档；并提及 https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/647-apiserver-tracing （KEP-647：APIServer 跟踪），说明它可能会通过 OpenTelemetry 改变 kube-apiserver 跟踪记录的生成方式。

从 HTTP 访问日志中识别高负载 API 服务客户端

要识别哪些客户端为 kube-apiserver 带来了最大负载，请分析 apiserver 组件日志中的 httplog.go HTTP 访问条目（此功能为可选功能，必须通过 --logging=SYSTEM,WORKLOADS,API_SERVER 显式启用；务必始终说明这一点，并链接到 https://docs.cloud.google.com/kubernetes-engine/docs/how-to/view-logs#control_plane_logs）：

1. httplog.go 日志结构非常稳定（务必始终提及这一点并展示日志行示例）：明确告知用户，kube-apiserver 的 httplog.go 日志结构在各个 Kubernetes 版本之间非常稳定（因此正则提取和 Log Analytics 查询都可靠），并包含以下日志行示例：

   I1015 11:36:56.835535      10 httplog.go:137] "HTTP" verb="GET" URI="/api/v1/namespaces/default/pods" latency="7.374935s" userAgent="my-controller/v1.0.0 (linux/amd64)" audit-ID="11111111-2222-3333-4444-555555555555" srcIP="10.0.0.1:12345" apf_pl="workload-low" apf_fs="everybody" apf_iseats=1 apf_fseats=0 apf_additionalLatency="0s" apf_execution_time="7.374765s" resp=200
   

2. 客户端负载分析的关键字段：
   • user_agent（原始日志文本中的 userAgent）：用于识别发出请求的客户端二进制程序、控制器或 Operator。
   • verb：用于区分高开销的请求类型（例如集群范围的 LIST 或修改数据的 PATCH/UPDATE 调用）与开销较低的 GET 调用。
   • apf_iseats（以及 apf_fseats 和 apf_execution_time）：表示请求占用的 API Priority and Fairness（APF）初始并发席位；按 user_agent 和 verb 对 apf_iseats * apf_execution_time 加权或求和，可以揭示哪些客户端消耗了最多的 API 服务并发容量。

告警

针对关键情况设置告警：

条件	指标	阈值
API 服务延迟高	apiserver_request_duration_seconds	P99 > 5s
Pod 崩溃循环	kube_pod_container_status_restarts_total	> 5 in 10min
节点未就绪	kube_node_status_condition	condition=Ready, status!=True
GPU 利用率高	DCGM_FI_DEV_GPU_UTIL	> 95% sustained
PVC 接近容量上限	kubelet_volume_stats_used_bytes / capacity	> 85%
调度失败	scheduler_schedule_attempts_total{result="error"}	> 0

**前提条件：**上述 kube_* 序列（例如 kube_pod_status_phase、 kube_pod_container_status_restarts_total、kube_node_status_condition） 来自 kube-state-metrics，而 GKE 默认不会收集这些指标。 请先部署 Managed Prometheus kube-state-metrics 软件包。

提议仪表板和告警（生产规则）

为 GKE 设计或提议告警和仪表板策略时：

1. 务必明确将 Google Cloud Monitoring 指定为实现这些告警和仪表板的平台。
2. 务必在仪表板中加入 API 服务延迟（通过 apiserver_request_duration_seconds 指标），将其作为控制平面运行状况的关键指标，并与节点 CPU/Memory 和 Pod 崩溃循环并列展示。

节点健康状况（生产环境规则）

要全面评估节点健康状况，需要结合分析以下两项指标：

1. kubernetes.io/node/status_condition（按 status_condition="Ready" 过滤）：用于跟踪健康节点。请注意，它仅报告已成功引导的节点的值。
2. compute.googleapis.com/instance_group/size（按 instance_group_name="gke-<cluster_name>-.*" 过滤）：用于跟踪特定集群中的节点总数。请注意，它无法区分健康节点与不健康节点。

控制平面健康状况（生产环境规则）

若要检查 Google 是否认为 GKE 集群的控制平面处于健康状态，请使用 kubernetes.io/cluster/kcp_healthchecks 系统指标（位于 k8s_cluster 受监控资源上，包含在默认的 SYSTEM 指标包中）：

1. 指标语义：kubernetes.io/cluster/kcp_healthchecks 是一项增量（DELTA / CUMULATIVE 计数器）指标，每 60 秒采样一次，用于统计 Google 内部控制平面探测次数，并按布尔值 success（"true" 或 "false"）标记。
2. 绘制健康率图表：由于该指标是增量计数器，而非布尔型仪表盘指标，因此应将成功检查的速率（success="true"）除以所有 success 值对应的检查总速率，以此绘制控制平面的可用性：

sum by (project_id, location, cluster_name) (
  rate(
    kubernetes_io:cluster_kcp_healthchecks{
      monitored_resource="k8s_cluster", success="true"
    }[5m]
  )
)
/
sum by (project_id, location, cluster_name) (
  rate(
    kubernetes_io:cluster_kcp_healthchecks{
      monitored_resource="k8s_cluster"
    }[5m]
  )
)

成本注意事项

监控和日志记录会产生相关费用：

• Cloud Logging：超出免费额度的每 GiB 摄取量均收费（每月每个项目 50 GiB）
• Cloud Monitoring：GKE 系统指标免费；自定义指标按时间序列收费
• Managed Prometheus：按摄取的样本数量收费

若要降低非生产环境的成本：

# Reduce to system-only monitoring
gcloud container clusters update <CLUSTER_NAME> --region <REGION> \
  --monitoring=SYSTEM \
  --quiet

分布式跟踪与持续性能分析（推荐）

并非黄金路径默认配置——推荐用于生产微服务架构和对性能敏感的工作负载。

• Cloud Trace：在应用中添加 OpenTelemetry SDK，并使用 opentelemetry-operations-go（或等效）导出器。跟踪记录会显示在 Cloud Trace 控制台中，可用于识别跨服务的延迟瓶颈。
• Cloud Profiler：在应用中添加 Cloud Profiler Agent。它能以较低开销分析生产环境中的 CPU 和内存使用情况，帮助识别热点并比较不同版本。

近期新增：

• GKE 托管式 OpenTelemetry（预览版）：托管式集群内 OTLP 端点，以及针对跟踪、指标和日志的自动检测。要求使用 GKE 1.34.1-gke.2178000+；通过 gcloud beta container clusters update ... --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS 启用。
• PSI（压力停滞信息）指标：cAdvisor container_pressure_{cpu,memory,io}_{waiting,stalled}_seconds_total 序列 （Kubernetes 1.34 中为 Beta 版）可通过 Managed Prometheus ClusterNodeMonitoring 资源进行采集；GKE 文档说明的采集路径要求使用 GKE 1.35+。

LQL 查询示例

用于排查 GKE 问题的常见 Logging Query Language 模式：

# Error logs for a specific container
resource.type="k8s_container" AND resource.labels.container_name="my-app" AND severity>=ERROR

# OOMKilled events
resource.type="k8s_event" AND jsonPayload.reason="OOMKilling"

# Pod scheduling failures
resource.type="k8s_event" AND jsonPayload.reason="FailedScheduling"

# Audit logs (who did what)
resource.type="k8s_cluster" AND logName:"cloudaudit.googleapis.com"

Managed Prometheus (GMP) 故障排查

诊断 GMP 摄取、规则和查询问题。保持只读（kubectl get / describe / logs），并提出配置更改建议；不要直接修改运行中的资源。

首先：区分摄取侧与查询侧

开始排查前，先在 Cloud Monitoring 的 Metrics Explorer PromQL 标签页中查询 up 指标。如果 up 返回数据，说明摄取正常，问题出在查询侧（Grafana / PromQL / 权限）。如果 up 结果为空，问题则出在摄取侧（采集器、抓取配置或写入权限）。

采集端

1. 检查 GMP 系统 Pod。 它们在 Standard 集群中运行于 gmp-system，在 Autopilot 集群中运行于 gke-gmp-system。检查 gmp-operator、collector （DaemonSet）和 rule-evaluator 是否未处于 Running 状态或重启次数过多：

   kubectl get pods -n gmp-system            # Autopilot 上使用 gke-gmp-system
   kubectl logs -n gmp-system -l app.kubernetes.io/name=collector -c prometheus
   

   如果 collector 处于 CrashLoopBackOff 且状态为 OOMKilled，通常意味着指标基数过高——删除不需要的序列/标签（参见下方成本部分），或为 collector 应用 VPA。

2. 检查 PodMonitoring / ClusterPodMonitoring。 最常见的三个错误：

   • spec.selector.matchLabels 与目标 Pod 标签不匹配。
   • PodMonitoring 只能发现其自身命名空间内的目标——要覆盖整个集群，请使用 ClusterPodMonitoring。
   • spec.endpoints.port 必须引用容器的命名端口（例如 port: web），而不是端口号。

3. 启用目标状态以排查抓取错误。 建议在 gmp-public 中为 OperatorConfig 应用补丁，设置 features.targetStatus.enabled: true； 应用后，运行 kubectl describe podmonitoring <name>，查看 Active Targets、 Unhealthy Targets 和 Last Error（例如 connection refused、HTTP 404、 context deadline exceeded）。完成后请再次禁用此功能——在大型集群上，它可能导致 operator OOM。

权限（403 / 未写入数据）

GMP 组件继承节点服务账号。采集需要 roles/monitoring.metricWriter（collector 日志中会出现错误 Permission monitoring.timeSeries.create denied）；rule-evaluator 和查询路径需要 roles/monitoring.viewer（403 / PermissionDenied）。如果查询应用（如 Grafana）使用 Workload Identity，绑定的 Google 服务账号也需要 roles/monitoring.viewer。

规则和告警评估

规则的作用范围由资源类型决定：Rules（单个命名空间）、 ClusterRules（整个集群）和 GlobalRules（指标范围内的所有数据）。针对 Cloud Monitoring 指标编写规则必须使用 GlobalRules——Rules/ClusterRules 资源对这些指标会静默返回无数据。检查 rule-evaluator 日志（-c evaluator），排查解析/权限错误。

查询端（Grafana / PromQL）

• 数据源必须指向 GMP 前端查询代理，而不是 localhost:9090，并且 HTTP Method 必须为 GET——使用 POST 会报错 no match[] parameter provided。
• **Grafana 模板变量：**使用双参数形式 label_values(<metric>, <label>)；GMP API 不支持单参数形式 label_values(<label>)。
• Cloud Monitoring 指标如果存在于多种资源类型中，必须添加 monitored_resource 标签匹配器，否则查询会报错 series selector must specify a label matcher on monitored resource name。

成本、基数和配额

使用 Cloud Monitoring 的 Metrics Management 页面，查找影响计费样本数和导致高基数的指标。通过在 PodMonitoring 中设置 metricRelabeling（对整个指标使用 action: drop，对 user_id/request_id 等无界标签使用 action: labeldrop），或调高抓取 interval，来减少这些指标。429 / RESOURCE_EXHAUSTED 错误表示已达到 Cloud Monitoring API 的采集或查询配额——先优化，再申请提高配额。

相关链接

• GKE 系统指标
• GKE 可观测性文档
• Google Cloud 托管式 Prometheus 服务
• 排查托管式 Prometheus 服务问题
• 规则评估（Rules / ClusterRules / GlobalRules）
• Cloud Logging 查询语言（LQL）
• Google Cloud Monitoring 警报