Kubernetes 1.35：增强的调试与带版本的 z-pages API

Source: Kubernetes Blog

什么是 z‑pages？

z‑pages 是由 Kubernetes 控制平面组件公开的特殊调试端点。它们在 Kubernetes 1.32 中作为 alpha 特性 引入，这些端点为以下组件提供运行时诊断：

• kube-apiserver
• kube-controller-manager
• kube-scheduler
• kubelet
• kube-proxy

名称 “z‑pages” 来自于调试端点使用 /*z 路径的约定。

当前的 z‑page 端点

这些端点对需要快速检查组件状态的人工操作员非常有价值，但截至目前，它们仅返回 纯文本 输出，难以进行程序化解析。

Source:

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

示例 /statusz 响应

{
  "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. 更好的调试工具 – 开发者可以对比组件之间的配置，随时间跟踪漂移，并构建复杂的诊断工具。
3. API 版本化与稳定性 – 引入版本化 API（v1alpha1）提供了明确的迁移路径（未来的 v1beta1，随后是 v1），使工具在各版本发布中保持稳定。

如何使用结构化 z‑pages

先决条件

两个端点都需要相应的 feature gates 已启用：

示例：使用 curl 获取结构化响应

# Structured statusz response
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 .

# Structured flagz response
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 .

注意

• 示例使用 客户端证书认证，并通过 --cacert 验证服务器证书。
• 在测试环境中可以使用 --insecure（或 -k）跳过验证，但 绝不要 在生产环境中这样做——这会使你面临中间人攻击的风险。

重要考虑事项

Alpha 功能状态

• 结构化 z‑page 响应在 Kubernetes 1.35 中为 alpha。
• API 格式 可能在未来的发布中更改。
• 这些端点旨在用于 调试，而非生产关键自动化。
• 在其达到 beta 或 stable 状态之前，避免将其用于关键监控。

安全性与访问控制

z‑pages 会暴露内部组件信息，因此必须实施适当的访问控制：

• 将访问限制在受信任的用户或服务账户上。
• 使用网络策略、RBAC 和 TLS 客户端认证来限制暴露范围。
• 定期审计谁可以访问 /*z 端点。

TL;DR

• Kubernetes 1.35 为 /statusz 和 /flagz 添加了 可选的 JSON 输出。
• 使用 Accept: application/json;v=v1alpha1;g=config.k8s.io;as=… 头部请求 JSON。
• 必须启用功能门 ComponentStatusz 和 ComponentFlagz。
• 将结构化数据用于自动化检查、更丰富的调试工具以及面向未来的集成——同时记住该功能仍处于 alpha 阶段，需通过严格的访问控制进行保护。

访问 z‑page 端点

对 z‑page 端点的访问仅限于 system:monitoring 组的成员，该组的授权模型与其他调试端点（如 /healthz、/livez 和 /readyz）相同。这确保只有经过授权的用户和服务账户能够访问调试信息。

• 如果你的集群使用 RBAC，请通过为该组授予相应权限来管理访问。

认证

这些端点的认证要求取决于你的集群配置。

• 除非启用了 匿名认证，否则通常需要使用认证机制（例如客户端证书）来访问这些端点。

信息泄露

这些端点会显示集群组件的配置信息，包括：

• 组件版本和构建信息
• 所有命令行参数及其取值（机密值已被编辑）
• 可用的调试端点

建议： 仅向受信任的运维人员和调试工具授予访问权限。避免向未经授权的用户或不需要此级别访问的自动化系统公开这些端点。

未来演进

随着功能的成熟，Kubernetes SIG Instrumentation 团队预计将：

1. 引入 v1beta1 并最终推出 v1 版本的 API。
2. 收集社区对响应模式的反馈。
3. 根据用户需求，可能会添加额外的 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 可观测性的未来。

• 有问题、建议或 issue 吗？ 请在 Slack 上联系 SIG Instrumentation 或参加我们的定期社区会议。

祝调试愉快！