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

Author: yongruilin

keps/sig-instrumentation/4827-component-statusz/README.md

@@ -158,15 +158,22 @@ 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 uses content negotiation via the `Accept` header to serve different response formats. The default response format is `text/plain`, which is intended for human consumption and backward compatibility.
+
+For programmatic access, a structured, versioned JSON response is available. Clients can request the structured format by specifying the appropriate `Accept` header:
+`Accept: application/json;v=v1`
+
+If the `Accept` header is omitted or set to `text/plain`, the endpoint will return the default plain text response. This approach allows for a stable, machine-readable API while preserving the simple text-based output.
 
 ### Authz and authn
 
@@ -189,14 +196,6 @@ rules:
 
 ### Endpoint Response Format
 
-#### Data format : text
-
-#### Request
-* Method: **GET** 
-* Endpoint: **/statusz**
-* Header: `Content-Type: text/plain`
-* 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
@@ -206,7 +205,17 @@ rules:
 * **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
+#### Data format: text (default)
+
+This format is the default and is intended for human readability and backward compatibility.
+
+##### Request
+* Method: **GET**
+* Endpoint: **/statusz**
+* Header: `Accept: text/plain` (or no Accept header)
+* Body: empty
+
+##### Sample response
 
 ```
 Started: Fri Sep  6 06:19:51 UTC 2024
@@ -225,6 +234,38 @@ metrics:/metrics
 readyz:/readyz
 sli metrics:/metrics/slis
 ```
+
+#### Data format: JSON (v1)
+
+This is the preferred format for programmatic access.
+
+##### Request
+* Method: **GET**
+* Endpoint: **/statusz**
+* Header: `Accept: application/json;v=v1`
+* Body: empty
+
+##### Sample Response
+
+```json
+{
+  "apiVersion": "v1",
+  "startTime": "2024-09-06T06:19:51Z",
+  "upTime": "30s",
+  "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"
+  }
+}
+```
 ### Test Plan
 
 [x] I/we understand the owners of the involved components may require updates to
@@ -233,34 +274,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;v=v1` returns a valid JSON object.
+  - The JSON response can be successfully unmarshalled.
+  - 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`).
+- Feature implemented for apiserver.
+- Initial implementation provides a plain text response.
+- Basic unit tests are in place.
 
 #### Beta
 
-- Gather feedback from developers
-- Feature implemented for other Kubernetes Components
+- Feature gate `ComponentStatusz` is enabled by default.
+- Structured, versioned JSON response format is implemented.
+- Plain text format is maintained for backward compatibility.
+- Feature is implemented for all core Kubernetes components (kube-apiserver, kube-controller-manager, kube-scheduler, kubelet, kube-proxy).
+- Integration and e2e tests are added for the JSON response format.
+- Gather feedback from users and developers on the structured format.
 
 #### GA
 
-- Several cycles of bake-time
+- The versioned JSON response is considered stable.
+- Several cycles of bake-time to ensure API stability and usefulness.
 
 #### Deprecation