diff --git a/keps/sig-instrumentation/4827-component-statusz/README.md b/keps/sig-instrumentation/4827-component-statusz/README.md index 603ee7cbbc0..f55a625b97e 100644 --- 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: ComponentStatus 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. + +For programmatic access, a structured, versioned JSON format is available with an initial alpha version of `v1alpha1`. This version is not stable and is intended for feedback and iteration during the Alpha phase. + +- **Group**: `config.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=config.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 in Alpha for programmatic access and must be explicitly requested. It is considered an alpha-level format. + +##### Request +* Method: **GET** +* Endpoint: **/statusz** +* Header: `Accept: application/json;as=ComponentStatus;v=v1alpha1;g=config.k8s.io` +* Body: empty + +##### Response Body: `ComponentStatus` object + +The response is a `ComponentStatus` object with the following structure: + +```json +{ + "kind": "ComponentStatus", + "apiVersion": "config.k8s.io/v1alpha1", + "metadata": { + "name": "", + "creationTimestamp": "" + }, + "startTime": "", + "upTime": "", + "buildInformation": { + "goVersion": "", + "binaryVersion": "", + "emulationVersion": "", + "minimumCompatibilityVersion": "" + }, + "usefulLinks": { + "configz": "/configz", + "healthz": "/healthz", + "livez": "/livez", + "metrics": "/metrics", + "readyz": "/readyz", + "sli_metrics": "/metrics/slis" + } +} +``` + +##### Sample Response + +```json +{ + "kind": "ComponentStatus", + "apiVersion": "config.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,45 @@ 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=config.k8s.io` returns a valid `ComponentStatus` 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 gate `ComponentStatusz` is disabled by default. +- A structured JSON response (`config.k8s.io/v1alpha1`) is introduced for feedback, alongside the default `text/plain` format. +- The `v1alpha1` JSON format is explicitly marked as alpha-quality and subject to change. +- Feature is implemented for at least one component (e.g., kube-apiserver). +- E2E tests are added for both plain text and the new JSON response format. +- Gather feedback from users and developers on the structured format. #### Beta -- Gather feedback from developers -- Feature implemented for other Kubernetes Components +- Feature gate `ComponentStatusz` is enabled by default. +- The JSON response API is promoted to `v1beta1` or `v1` based on feedback and is considered stable. +- Feature is implemented for all core Kubernetes components. #### GA -- Several cycles of bake-time +- The JSON response API is promoted to a stable `v1` version after bake-in. +- Conformance tests are in place for the endpoint. #### Deprecation diff --git a/keps/sig-instrumentation/4827-component-statusz/kep.yaml b/keps/sig-instrumentation/4827-component-statusz/kep.yaml index 7ff65dbbcd1..e23bfc82b45 100644 --- a/keps/sig-instrumentation/4827-component-statusz/kep.yaml +++ b/keps/sig-instrumentation/4827-component-statusz/kep.yaml @@ -2,6 +2,7 @@ title: Component Statusz kep-number: 4827 authors: - "@richabanker" + - "@yongruilin" owning-sig: sig-instrumentation participating-sigs: - sig-instrumentation