元鉴
返回中文阅读流

Kubernetes Blog

Kubernetes 1.35：通过版本化 z-pages API 增强调试能力

Kubernetes 1.35 为 z-pages 调试端点加入结构化、机器可解析响应，便于构建工具并自动化排障。

中文内容

已翻译official company source英文原文2025-12-31

Kubernetes 1.35：通过版本化 z-pages API 增强调试能力

By Richa Banker, Han Kang | Wednesday, December 31, 2025

调试 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 端点：

/statuszDisplays high-level component information including version information, start time, uptime, and available debug paths/flagzShows all command-line arguments and their values used to start the component (with confidential values redacted for security)

这些端点对于需要快速检查组件状态的人类操作员很有价值，但到目前为止，它们只返回纯文本输出，难以通过程序解析。

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. 更好的调试工具

开发者可以构建更复杂的调试工具，用于比较多个组件之间的配置，或跟踪配置随时间发生的漂移。结构化格式使配置差异比对或验证组件是否以预期设置运行变得非常简单。

3. API 版本化与稳定性

通过引入版本化 API（从 v1alpha1 开始），我们提供了一条清晰的稳定化路径。随着该特性逐渐成熟，我们将引入 v1beta1，并最终引入 v1，让你有信心自己的工具不会因未来的 Kubernetes 版本而中断。

如何使用结构化 z-pages

先决条件

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

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

示例：获取结构化响应

以下示例使用 curl 从 kube-apiserver 获取结构化 JSON 响应：

# Get 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 .

# Get 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 .

注意：

The examples above use client certificate authentication and verify the server's certificate using --cacert. If you need to bypass certificate verification in a test environment, you can use --insecure (or -k), but this should never be done in production as it makes you vulnerable to man-in-the-middle attacks.

重要注意事项

Alpha 特性状态

结构化 z-page 响应是 Kubernetes 1.35 中的 alpha 特性。这意味着：

  • API 格式可能会在未来版本中发生变化
  • 这些端点用于调试，而非生产自动化
  • 在它们达到 beta 或 stable 状态之前，你应避免在关键监控流程中依赖它们

安全与访问控制

z-pages 会暴露内部组件信息，并需要适当的访问控制。以下是关键安全注意事项：

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

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

信息披露：这些端点会揭示有关集群组件的配置详情，包括：

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

仅向可信操作员和调试工具授予访问权限。避免将这些端点暴露给未授权用户，或不需要此级别访问权限的自动化系统。

未来演进

随着该特性成熟，我们（Kubernetes SIG Instrumentation）预计将：

  • 引入 v1beta1，并最终引入该 API 的 v1 版本
  • 收集社区对响应模式的反馈
  • 根据用户需求，可能增加更多 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 上或我们的定期社区会议中找到我们。

祝调试顺利！

  • ← 上一篇
  • 下一篇 →
Last modified January 03, 2026 at 3:42 PM PST: Reorganize 2025 blog content (0979e97a89)

原文标题

Kubernetes 1.35: Enhanced Debugging with Versioned z-pages APIs