Kubernetes 1.35：版本化 z-pages API 带来更强大的调试能力

调试 Kubernetes 控制平面组件可能很具挑战性， 尤其是在需要快速理解组件运行时状态或验证配置时。 在 Kubernetes 1.35 中，我们为 z-pages 调试端点带来结构化、可被机器解析的响应， 让构建工具和自动化排障流程变得更加轻松。

什么是 z-pages？

z-pages 是 Kubernetes 控制平面组件所公开的特殊调试端点。 它们在 Kubernetes 1.32 中以 Alpha 特性引入，为 kube-apiserver、kube-controller-manager、 kube-scheduler、kubelet 与 kube-proxy 等组件提供运行时诊断。 "z-pages" 这一名称源自使用 /*z 路径来公开调试端点的惯例。

目前，Kubernetes 支持两个主要的 z-page 端点：

/statusz

显示组件的高级信息，包括版本、启动时间、运行时长以及可用调试路径

/flagz

展示用于启动组件的全部命令行参数及其取值（敏感值会出于安全考虑被屏蔽）

这些端点对于需要快速检查组件状态的人工运维人员非常有价值， 但在此之前它们只返回难以通过程序解析的纯文本输出。

Kubernetes 1.35 有哪些新内容？

Kubernetes 1.35 为 /statusz 与 /flagz 两个端点都引入了结构化、具备版本控制的响应。 这一增强在保留现有纯文本格式向后兼容性的同时，新增了对机器可读 JSON 响应的支持。

向后兼容的设计

新的结构化响应是按需启用的。 如果未指定 Accept 头，端点仍会返回熟悉的纯文本格式：

$ curl --cert /etc/kubernetes/pki/apiserver-kubelet-client.crt \
  --key /etc/kubernetes/pki/apiserver-kubelet-client.key \
  --cacert /etc/kubernetes/pki/ca.crt \
  https://localhost:6443/statusz

kube-apiserver statusz
Warning: This endpoint is not meant to be machine parseable, has no formatting compatibility guarantees and is for debugging purposes only.

Started: Wed Oct 16 21:03:43 UTC 2024
Up: 0 hr 00 min 16 sec
Go version: go1.23.2
Binary version: 1.35.0-alpha.0.1595
Emulation version: 1.35
Paths: /healthz /livez /metrics /readyz /statusz /version

结构化 JSON 响应

若要获得结构化响应，需要提供合适的 Accept 头：

Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Statusz

这样即可返回具备版本号的 JSON 响应：

{
  "kind": "Statusz",
  "apiVersion": "config.k8s.io/v1alpha1",
  "metadata": {
    "name": "kube-apiserver"
  },
  "startTime": "2025-10-29T00:30:01Z",
  "uptimeSeconds": 856,
  "goVersion": "go1.23.2",
  "binaryVersion": "1.35.0",
  "emulationVersion": "1.35",
  "paths": [
    "/healthz",
    "/livez",
    "/metrics",
    "/readyz",
    "/statusz",
    "/version"
  ]
}

类似地，/flagz 也支持结构化响应，只需设置以下头部：

Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Flagz

响应示例如下：

{
  "kind": "Flagz",
  "apiVersion": "config.k8s.io/v1alpha1",
  "metadata": {
    "name": "kube-apiserver"
  },
  "flags": {
    "advertise-address": "192.168.8.4",
    "allow-privileged": "true",
    "authorization-mode": "[Node,RBAC]",
    "enable-priority-and-fairness": "true",
    "profiling": "true"
  }
}

结构化响应为什么很重要

引入结构化响应使得一系列新的用例成为可能：

1. 自动化健康检查与监控

相比解析纯文本，监控工具现在可以轻松提取特定字段。 例如，你可以通过程序检查组件是否以异常的模拟版本运行，或确认关键参数是否配置正确。

2. 更好的调试工具

开发者能够构建更加智能的调试工具，用于跨组件比较配置或随时间追踪配置漂移。 结构化格式让对配置执行 diff 或验证组件是否按预期设置运行变得轻而易举。

3. API 版本化与稳定性

通过引入带版本的 API（从 v1alpha1 开始），我们为稳定性提供了明确路径。 随着特性不断成熟，我们会发布 v1beta1 甚至 v1， 让你更有信心确保这些工具在未来的 Kubernetes 版本中依然能够正常工作。

如何使用结构化 z-pages

前提条件

两个端点都需要启用相应的特性门控：

• /statusz：启用 ComponentStatusz 特性门控
• /flagz：启用 ComponentFlagz 特性门控

示例：获取结构化响应

下面示例展示如何使用 curl 从 kube-apiserver 中获取结构化 JSON 响应：

# 获取结构化状态响应
curl \
  --cert /etc/kubernetes/pki/apiserver-kubelet-client.crt \
  --key /etc/kubernetes/pki/apiserver-kubelet-client.key \
  --cacert /etc/kubernetes/pki/ca.crt \
  -H "Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Statusz" \
  https://localhost:6443/statusz | jq .

# 获取结构化标记响应
curl \
  --cert /etc/kubernetes/pki/apiserver-kubelet-client.crt \
  --key /etc/kubernetes/pki/apiserver-kubelet-client.key \
  --cacert /etc/kubernetes/pki/ca.crt \
  -H "Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Flagz" \
  https://localhost:6443/flagz | jq .

重要注意事项

Alpha 特性状态

结构化 z-page 响应在 Kubernetes 1.35 中仍是 Alpha 特性，这意味着：

• API 格式可能会在未来版本中发生变化
• 这些端点用于调试，而非生产自动化
• 在其达到 Beta 或稳定版之前，不应把它们作为关键监控工作流的依赖

安全与访问控制

z-pages 会公开组件内部信息，因此必须设置恰当的访问控制，重点注意以下安全事项：

鉴权：访问 z-page 端点仅限 system:monitoring 组成员， 遵循与 /healthz、/livez、/readyz 等调试端点相同的鉴权模型。 这样可确保只有获授权的用户和服务账号才能获取调试信息。 如果集群使用 RBAC，可以通过赋予该组适当权限来管理访问。

身份认证：这些端点的身份认证要求取决于集群配置。 除非集群启用了匿名身份认证，否则通常需要使用身份认证机制（如客户端证书）来访问这些端点。

信息披露：这些端点会泄露集群组件的配置细节，包括：

• 组件版本与构建信息
• 所有命令行参数及其取值（敏感值会被屏蔽）
• 可用的调试端点

务必仅向受信任的运维人员和调试工具授予访问权限， 避免对无关用户或不需要该访问级别的自动化系统开放这些端点。

未来演进

随着特性愈发成熟，Kubernetes SIG Instrumentation 计划：

• 引入 v1beta1 并最终提供 v1 版本的 API
• 收集社区对响应模式的反馈
• 根据用户需求，潜在新增更多 z-page 端点

动手试试

我们鼓励你在测试环境体验结构化 z-pages：

1. 在控制平面组件上启用 ComponentStatusz 与 ComponentFlagz 特性门控
2. 使用纯文本与结构化两种格式查询端点
3. 构建一个使用结构化数据的简单工具或脚本
4. 向社区分享你的反馈

了解更多

• z-pages 文档
• KEP-4827：Component Statusz
• KEP-4828：Component Flagz
• 加入 Kubernetes Slack 中的 #sig-instrumentation 频道参与讨论

参与其中

我们非常期待你的反馈！结构化 z-pages 旨在让 Kubernetes 调试和监控更轻松。 无论你是在构建内部工具、为开源项目做贡献，还是只是探索该特性， 你的意见都将帮助塑造 Kubernetes 可观测性的未来。

如果你有问题、建议或遇到问题，请联系 SIG Instrumentation。 你可以在 Slack 中找到我们，或参加常规的社区会议。

祝你调试愉快！

• ←上一页
• 下一页→