KEP-4827: Update Beta criteria to include versioned JSON response format

yongruilin · yongruilin · commit 4979cb1ac73e · 2025-10-02T21:29:42.000Z
diff --git a/keps/sig-instrumentation/4827-component-statusz/README.md b/keps/sig-instrumentation/4827-component-statusz/README.md
@@ -26,10 +26,14 @@ tags, and then generate with `hack/update-toc.sh`.
   - [Data Format and versioning](#data-format-and-versioning)
   - [Authz and authn](#authz-and-authn)
   - [Endpoint Response Format](#endpoint-response-format)
-    - [Data format : text](#data-format--text)
-    - [Request](#request)
-    - [Response fields](#response-fields)
-    - [Sample response](#sample-response)
+    - [Data format: text](#data-format-text)
+      - [Request](#request)
+      - [Sample response](#sample-response)
+    - [Data format: JSON (v1alpha1)](#data-format-json-v1alpha1)
+      - [Request](#request-1)
+      - [Response Body: <code>ComponentStatus</code> object](#response-body-componentstatus-object)
+      - [Sample Response](#sample-response-1)
+  - [API Versioning and Deprecation Policy](#api-versioning-and-deprecation-policy)
   - [Test Plan](#test-plan)
       - [Prerequisite testing updates](#prerequisite-testing-updates)
       - [Unit tests](#unit-tests)
@@ -158,15 +162,32 @@ We are proposing to add a new endpoint, /statusz on all core Kubernetes componen
     
   We will prioritize inclusion of only essential diagnostic and monitoring data that aligns with the intended purpose of the z-page.
 
-3. **Premature Dependency on Unstable Format**
+3. **API Stability and Evolution**
 
-  The alpha release will explicitly support plain text format only, making it clear that the output is not intended for parsing or automated monitoring. The feature will be secured behind a feature gate that is disabled by default, ensuring users opt-in consciously. Also, the endpoint will support specifying a version as a query parameter to facilitate future transitions to structured schema changes without breaking existing integrations, once the usage patterns and requirements are better understood
+  The alpha release will explicitly support plain text format only, making it clear that the output is not intended for parsing or automated monitoring. The feature will be secured behind a feature gate that is disabled by default, ensuring users opt-in consciously.
+
+  For Beta, to provide a stable contract for consumers, we are introducing a versioned JSON response available via content negotiation (`Accept: application/json;v=v1`). The plain text format remains the default for human consumption and backward compatibility.
 
 ## Design Details
 
 ### Data Format and versioning
 
-Initially, the statusz page will exclusively support a plain text format for responses. In future, when we have established a structured schema for the response, we can support specifying a version param, like /statusz?version=2, to ensure future compatibility. Through this, we can evolve the endpoint and introduce changes to the response schema without impacting clients relying on previous versions, ensuring backward compatibility.
+The `/statusz` endpoint defaults to a `text/plain` response format, which is intended for human consumption and should not be parsed by automated tools.
+
+Beginning in Beta, a structured, versioned JSON format is available for programmatic access. This will follow the standard Kubernetes content negotiation mechanism, requiring a group, version, and kind.
+
+- **Group**: `component.k8s.io`
+- **Version**: `v1alpha1` (initial version, subject to change)
+- **Kind**: `ComponentStatus`
+
+To receive the structured JSON response, a client **must** explicitly request it using an `Accept` header specifying these parameters. For example:
+
+```
+GET /statusz
+Accept: application/json;as=ComponentStatus;v=v1alpha1;g=component.k8s.io
+```
+
+This negotiation mechanism ensures clients are explicit about the exact API they want, preventing accidental dependencies on unstable or incorrect formats. If a client requests `application/json` without the required parameters, the server will respond with a `406 Not Acceptable` error.
 
 ### Authz and authn
 
@@ -189,24 +210,19 @@ rules:
 
 ### Endpoint Response Format
 
-#### Data format : text
+The `/statusz` endpoint supports both plain text and structured JSON formats. The default format is `text/plain`.
+
+#### Data format: text
+
+This format is the default and is intended for human readability.
 
-#### Request
-* Method: **GET** 
+##### Request
+* Method: **GET**
 * Endpoint: **/statusz**
-* Header: `Content-Type: text/plain`
+* Header: `Accept: text/plain` (or no Accept header)
 * Body: empty
 
-#### Response fields
-* **Start Time**: The exact date and time when the component process was initiated
-* **Uptime**: The duration for which the component has been running continuously
-* **Go Version**: The specific version of the Go programming language used to build the component's binary
-* **Binary Version**: The version of the component's binary, helpful for compatibility checks and troubleshooting
-* **Emulation Version**: The Kubernetes API version which this component is emulating as
-* **Minimum Compatibility Version**: The minimum Kubernetes API version with which the component is designed to work seamlessly
-* **Useful Links**: Relative URLs to other essential endpoints, such as /healthz, /livez, /readyz, and /metrics, for deeper insights into the component's health, readiness, and performance metrics
-
-#### Sample response
+##### Sample response
 
 ```
 Started: Fri Sep  6 06:19:51 UTC 2024
@@ -225,6 +241,88 @@ metrics:/metrics
 readyz:/readyz
 sli metrics:/metrics/slis
 ```
+
+#### Data format: JSON (v1alpha1)
+
+This format is available starting in Beta for programmatic access and must be explicitly requested. It is considered an alpha-level format and is subject to change.
+
+##### Request
+* Method: **GET**
+* Endpoint: **/statusz**
+* Header: `Accept: application/json;as=ComponentStatus;v=v1alpha1;g=component.k8s.io`
+* Body: empty
+
+##### Response Body: `ComponentStatus` object
+
+The response is a `ComponentStatus` object with the following structure:
+
+```json
+{
+  "kind": "ComponentStatus",
+  "apiVersion": "component.k8s.io/v1alpha1",
+  "metadata": {
+    "name": "<component-name>",
+    "creationTimestamp": "<start-time>"
+  },
+  "startTime": "<start-time>",
+  "upTime": "<uptime-duration>",
+  "buildInformation": {
+    "goVersion": "<go-version>",
+    "binaryVersion": "<binary-version>",
+    "emulationVersion": "<emulation-version>",
+    "minimumCompatibilityVersion": "<min-compatibility-version>"
+  },
+  "usefulLinks": {
+    "configz": "/configz",
+    "healthz": "/healthz",
+    "livez": "/livez",
+    "metrics": "/metrics",
+    "readyz": "/readyz",
+    "sli_metrics": "/metrics/slis"
+  }
+}
+```
+
+##### Sample Response
+
+```json
+{
+  "kind": "ComponentStatus",
+  "apiVersion": "component.k8s.io/v1alpha1",
+  "metadata": {
+    "name": "kube-apiserver",
+    "creationTimestamp": "2024-09-06T06:19:51Z"
+  },
+  "startTime": "2024-09-06T06:19:51Z",
+  "upTime": "30s",
+  "buildInformation": {
+    "goVersion": "go1.23.0",
+    "binaryVersion": "1.31.0-beta.0.981+c6be932655a03b-dirty",
+    "emulationVersion": "1.31.0-beta.0.981",
+    "minimumCompatibilityVersion": "1.30.0"
+  },
+  "usefulLinks": {
+    "configz": "/configz",
+    "healthz": "/healthz",
+    "livez": "/livez",
+    "metrics": "/metrics",
+    "readyz": "/readyz",
+    "sli_metrics": "/metrics/slis"
+  }
+}
+```
+### API Versioning and Deprecation Policy
+
+The versioned `/statusz` endpoint will follow a deprecation policy to ensure a predictable lifecycle for consumers as the API evolves.
+
+The deprecation policy for a given API version (e.g., `v1`) is as follows:
+- A deprecated API version must continue to be served for no less than **12 months or 3 releases** (whichever is longer) after the deprecation is announced.
+
+The deprecation process will be as follows:
+1.  **Announce Deprecation**: When a new API version is introduced (e.g., `v2`), the older version (e.g., `v1`) will be marked as deprecated. This will be communicated in the official release notes, and requests to the deprecated API version will return a `Warning` header.
+2.  **Deprecation Window**: The deprecated API version will be supported for the duration of the deprecation window (at least 12 months or 3 releases).
+3.  **Removal**: After the deprecation window has passed, the deprecated API version may be removed in a future Kubernetes release.
+
 ### Test Plan
 
 [x] I/we understand the owners of the involved components may require updates to
@@ -233,34 +331,46 @@ to implement this enhancement.
 
 ##### Prerequisite testing updates
 
+N/A
+
 ##### Unit tests
 
-- There will addition of new tests in the following packages
-  - `staging/src/k8s.io/component-base/zpages/statusz`: `2024-10-08` - `100%`
+- `staging/src/k8s.io/component-base/zpages/statusz`: Unit tests will be added to cover both the plain text and structured JSON output, including serialization and content negotiation logic.
 
 ##### Integration tests
 
+- Integration tests will be added for each component to verify that the `/statusz` endpoint is correctly registered and serves both `text/plain` and the versioned `application/json` content types.
 
 ##### e2e tests
 
-- Ensure existence of the /statusz endpoint
+- E2E tests will be added to query the `/statusz` endpoint for each core component and validate the following:
+  - The endpoint is reachable and returns a `200 OK` status.
+  - Requesting with the `Accept` header for `application/json;as=ComponentStatus;v=v1alpha1;g=component.k8s.io` returns a valid `ComponentStatus` JSON object.
+  - The JSON response can be successfully unmarshalled into the `ComponentStatus` struct.
+  - Requesting with `text/plain` or no `Accept` header returns the non-empty plain text format.
 
 ### Graduation Criteria
 
 #### Alpha
 
-- Feature implemented behind a feature flag
-- Feature implemented for apiserver
-- Ensure proper tests are in place.
+- Feature implemented behind a feature flag (`ComponentStatusz`), disabled by default.
+- Feature implemented for at least one component (e.g., kube-apiserver).
+- The endpoint provides a `text/plain` response only.
+- Unit and integration tests are in place for the plain text format.
 
 #### Beta
 
-- Gather feedback from developers
-- Feature implemented for other Kubernetes Components
+- Feature gate `ComponentStatusz` is enabled by default.
+- A structured JSON response (`component.k8s.io/v1alpha1`) is introduced for feedback.
+- The `v1alpha1` JSON format is explicitly marked as alpha-quality and subject to change.
+- Feature is implemented for all core Kubernetes components (kube-apiserver, kube-controller-manager, kube-scheduler, kubelet, kube-proxy).
+- E2E tests are added for both plain text and the new JSON response format.
+- Gather feedback from users and developers on the structured format.
 
 #### GA
 
-- Several cycles of bake-time
+- The JSON response API is promoted to `component.k8s.io/v1` and is considered stable after bake-in.
+- Conformance tests are in place for the endpoint.
 
 #### Deprecation
 
