Skip to content

Commit 63cc27b

Browse files
richabankerliggitt
richabanker
and
liggitt
committed
zpages structured response
Co-authored-by: Qiming Teng <[email protected]> Co-authored-by: Dipesh Rawat <[email protected]> Co-authored-by: Jordan Liggitt <[email protected]>
1 parent 0c94ca5 commit 63cc27b

File tree

1 file changed

+152
-6
lines changed
  • content/en/docs/reference/instrumentation

1 file changed

+152
-6
lines changed

‎content/en/docs/reference/instrumentation/zpages.md‎

Lines changed: 152 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -29,15 +29,17 @@ information about running components. For Kubernetes {{< skew currentVersion >}}
2929
serve the following endpoints (when enabled):
3030

3131
- [z-pages](#z-pages)
32-
- [statusz](#statusz)
33-
- [flagz](#flagz)
32+
- [statusz](#statusz)
33+
- [statusz (structured)](#statusz-structured)
34+
- [flagz](#flagz)
35+
- [flagz (structured)](#flagz-structured)
3436

3537
### statusz
3638

37-
Enabled using the `ComponentStatusz` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/),
39+
Enabled using the `ComponentStatusz` [feature gate](/docs/reference/command-line-tools-reference/feature-gates#ComponentStatusz),
3840
the `/statusz` endpoint displays high level information about the component such as its Kubernetes version, emulation version, start time and more.
3941

40-
The `/statusz` response from the API server is similar to:
42+
The `/statusz` plain text response from the API server is similar to:
4143

4244
```
4345
kube-apiserver statusz
@@ -48,13 +50,93 @@ Up: 0 hr 00 min 16 sec
4850
Go version: go1.23.2
4951
Binary version: 1.32.0-alpha.0.1484&#43;5eeac4f21a491b-dirty
5052
Emulation version: 1.32.0-alpha.0.1484
53+
Paths: /healthz /livez /metrics /readyz /statusz /version
54+
```
55+
56+
#### statusz (structured)
57+
58+
{{< feature-state feature_gate_name="ComponentStatusz" >}}
59+
60+
Starting with Kubernetes v1.35, the `/statusz` endpoint supports a structured,
61+
versioned response format when requested with the appropriate `Accept` header.
62+
Without an `Accept` header, the endpoint returns the plain text response format by default.
63+
64+
To request the structured response, use:
65+
```
66+
Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Statusz
67+
```
68+
69+
{{< note >}}
70+
If you request `application/json` without specifying all required parameters (`g`, `v`, and `as`),
71+
the server will respond with `406 Not Acceptable`.
72+
{{< /note >}}
73+
74+
Example structured response:
75+
```json
76+
{
77+
"kind": "Statusz",
78+
"apiVersion": "config.k8s.io/v1alpha1",
79+
"metadata": {
80+
"name": "kube-apiserver"
81+
},
82+
"startTime": "2025-10-29T00:30:01Z",
83+
"uptimeSeconds": 856,
84+
"goVersion": "go1.23.2",
85+
"binaryVersion": "1.35.0",
86+
"emulationVersion": "1.35",
87+
"paths": [
88+
"/healthz",
89+
"/livez",
90+
"/metrics",
91+
"/readyz",
92+
"/statusz",
93+
"/version"
94+
]
95+
}
96+
```
97+
98+
The `config.k8s.io/v1alpha1` schema for the structured `/statusz` response is as follows:
99+
100+
```go
101+
// Statusz is the config.k8s.io/v1alpha1 schema for the /statusz endpoint.
102+
type Statusz struct {
103+
// Kind is "Statusz".
104+
Kind string `json:"kind"`
105+
// APIVersion is the version of the object, e.g., "config.k8s.io/v1alpha1".
106+
APIVersion string `json:"apiVersion"`
107+
// Standard object's metadata.
108+
// +optional
109+
Metadata metav1.ObjectMeta `json:"metadata,omitempty"`
110+
// StartTime is the time the component process was initiated.
111+
StartTime metav1.Time `json:"startTime"`
112+
// UptimeSeconds is the duration in seconds for which the component has been running continuously.
113+
UptimeSeconds int64 `json:"uptimeSeconds"`
114+
// GoVersion is the version of the Go programming language used to build the binary.
115+
// The format is not guaranteed to be consistent across different Go builds.
116+
// +optional
117+
GoVersion string `json:"goVersion,omitempty"`
118+
// BinaryVersion is the version of the component's binary.
119+
// The format is not guaranteed to be semantic versioning and may be an arbitrary string.
120+
BinaryVersion string `json:"binaryVersion"`
121+
// EmulationVersion is the Kubernetes API version which this component is emulating.
122+
// if present, formatted as "<major>.<minor>"
123+
// +optional
124+
EmulationVersion string `json:"emulationVersion,omitempty"`
125+
// MinimumCompatibilityVersion is the minimum Kubernetes API version with which the component is designed to work.
126+
// if present, formatted as "<major>.<minor>"
127+
// +optional
128+
MinimumCompatibilityVersion string `json:"minimumCompatibilityVersion,omitempty"`
129+
// Paths contains relative URLs to other essential read-only endpoints for debugging and troubleshooting.
130+
// +optional
131+
Paths []string `json:"paths,omitempty"`
132+
}
51133
```
52134

53135
### flagz
54136

55-
Enabled using the `ComponentFlagz` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/), the `/flagz` endpoint shows you the command line arguments that were used to start a component.
137+
Enabled using the `ComponentFlagz` [feature gate](/docs/reference/command-line-tools-reference/feature-gates#ComponentFlagz), the `/flagz` endpoint shows you the command line arguments that were used to start a component.
56138

57-
The `/flagz` data for the API server looks something like:
139+
The `/flagz` plain text response from the API server looks something like:
58140

59141
```
60142
kube-apiserver flags
@@ -70,3 +152,67 @@ authorization-webhook-cache-unauthorized-ttl=30s
70152
authorization-webhook-version=v1beta1
71153
default-watch-cache-size=100
72154
```
155+
156+
#### flagz (structured)
157+
158+
{{< feature-state feature_gate_name="ComponentFlagz" >}}
159+
160+
Starting with Kubernetes v1.35, the `/flagz` endpoint supports a structured,
161+
versioned response format when requested with the appropriate `Accept` header.
162+
Without an `Accept` header, the endpoint returns the plain text response format by default.
163+
164+
To request the structured response, use:
165+
```
166+
Accept: application/json;v=v1alpha1;g=config.k8s.io;as=Flagz
167+
```
168+
169+
{{< note >}}
170+
If you request `application/json` without specifying all required parameters (`g`, `v`, and `as`),
171+
the server will respond with `406 Not Acceptable`.
172+
{{< /note >}}
173+
174+
Example structured response:
175+
```json
176+
{
177+
"kind": "Flagz",
178+
"apiVersion": "config.k8s.io/v1alpha1",
179+
"metadata": {
180+
"name": "kube-apiserver"
181+
},
182+
"flags": {
183+
"advertise-address": "192.168.8.4",
184+
"allow-privileged": "true",
185+
"anonymous-auth": "true",
186+
"authorization-mode": "[Node,RBAC]",
187+
"enable-priority-and-fairness": "true",
188+
"profiling": "true",
189+
"default-watch-cache-size": "100"
190+
}
191+
}
192+
```
193+
194+
The `config.k8s.io/v1alpha1` schema for the structured `/flagz` response is as follows:
195+
196+
```go
197+
// Flagz is the config.k8s.io/v1alpha1 schema for the /flagz endpoint.
198+
type Flagz struct {
199+
// Kind is "Flagz".
200+
Kind string `json:"kind"`
201+
// APIVersion is the version of the object, e.g., "config.k8s.io/v1alpha1".
202+
APIVersion string `json:"apiVersion"`
203+
// Standard object's metadata.
204+
// +optional
205+
Metadata metav1.ObjectMeta `json:"metadata,omitempty"`
206+
// Flags contains the command-line flags and their values.
207+
// The keys are the flag names and the values are the flag values,
208+
// possibly with confidential values redacted.
209+
// +optional
210+
Flags map[string]string `json:"flags,omitempty"`
211+
}
212+
```
213+
214+
{{< note >}}
215+
The structured responses for both `/statusz` and `/flagz` are alpha features in v1.35
216+
and are subject to change in future releases.
217+
They are intended to provide machine-parseable output for debugging and introspection tools.
218+
{{< /note >}}

0 commit comments

Comments
 (0)