KEP-4827: Update Beta criteria to include versioned JSON response format #5560
Conversation
k8s-ci-robot
added
cncf-cla: yes
k8s-ci-robot
added
the
size/M
yongruilin
force-pushed
the
statusz-structure
branch
from
8aebf6d to
819a31b
Compare
k8s-ci-robot
added
size/L
|
/assign @richabanker |
| 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. |
There was a problem hiding this comment.
I think we would want to make a structured, versioned format the default for the z-pages endpoints. Defaulting to an unversioned plain text response has the possibility of inadvertently breaking clients that may (despite our warning headers) parse it as the schema evolves.
There was a problem hiding this comment.
Also, if we were to make a versioned endpoint as the default, then we might want to also put in place a deprecation policy for this endpoint. We could do something similar to what we do for Kubernetes APIs/metrics today. For example, when we decide to deprecate an old version of the JSON response (e.g., v1) after a new one (v2) is introduced, we could:
- Announce Deprecation: Mark v1 as deprecated in the release notes and have the endpoint return a Warning header for any v1 requests
- Deprecation Window: Keep the v1 endpoint functional for at least 3 releases to give consumers ample time to migrate
- Removal: After the deprecation window, make v2 the default and maybe consider removing v1?
There was a problem hiding this comment.
I see, I updated to default return JSON and the deprecation policy, following the similar pattern as https://kubernetes.io/docs/reference/using-api/api-concepts/ and https://kubernetes.io/docs/reference/using-api/deprecation-policy/
| "emulationVersion": "1.31.0-beta.0.981", | ||
| "minimumCompatibilityVersion": "1.30.0", | ||
| "usefulLinks": { | ||
| "configz": "/configz", |
There was a problem hiding this comment.
having this as a key-value map seems redundant... The current implementation returns a list of available paths as described in this PR description, maybe just having this as an array of strings is ok?
| "binaryVersion": "1.31.0-beta.0.981+c6be932655a03b-dirty", | ||
| "emulationVersion": "1.31.0-beta.0.981", | ||
| "minimumCompatibilityVersion": "1.30.0", | ||
| "usefulLinks": { |
There was a problem hiding this comment.
Nit: this is implemented to return Paths (instead of useful_links) currently.
yongruilin
force-pushed
the
statusz-structure
branch
from
819a31b to
d433b09
Compare
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: yongruilin The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
| metrics:/metrics | ||
| readyz:/readyz | ||
| sli metrics:/metrics/slis | ||
| configz: /configz |
There was a problem hiding this comment.
This doesnt match with the JSON formatted response. Remove the keys from here too?
There was a problem hiding this comment.
It is what current KEP has. I've updated to match what we implemented.
This PR adds Beta criteria of statusz with versioned structured response.