From 9814f9273d28ef5b7a1f5f9a31ffe3b627a270a3 Mon Sep 17 00:00:00 2001 From: Antoine Pelisse Date: Wed, 6 Apr 2022 15:09:25 -0700 Subject: [PATCH 1/5] Add documentation for OpenAPI v3 Beta --- .../docs/concepts/overview/kubernetes-api.md | 43 ++++++++++++++----- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/content/en/docs/concepts/overview/kubernetes-api.md b/content/en/docs/concepts/overview/kubernetes-api.md index ed873bf352..47b31ef509 100644 --- a/content/en/docs/concepts/overview/kubernetes-api.md +++ b/content/en/docs/concepts/overview/kubernetes-api.md @@ -82,18 +82,42 @@ packages that define the API objects. ### OpenAPI V3 -{{< feature-state state="alpha" for_k8s_version="v1.23" >}} +{{< feature-state state="beta" for_k8s_version="v1.24" >}} -Kubernetes v1.23 offers initial support for publishing its APIs as OpenAPI v3; this is an -alpha feature that is disabled by default. -You can enable the alpha feature by turning on the +Kubernetes v1.24 offers beta support for publishing its APIs as OpenAPI v3; this is a +beta feature that is enabled by default. +You can disable the beta feature by turning off the [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) named `OpenAPIV3` for the kube-apiserver component. -With the feature enabled, the Kubernetes API server serves an -aggregated OpenAPI v3 spec per Kubernetes group version at the -`/openapi/v3/apis//` endpoint. Please refer to the -table below for accepted request headers. +A discovery endpoint `/openapi/v3` is provided to see a list of all +group/versions available. This endpoint only returns JSON. These group/versions +are provided in the following format: +```json +{ + "paths": { + ... + "api/v1": { + "serverRelativeURL": "/openapi/v3/api/v1?hash=CC0E9BFD992D8C59AEC98A1E2336F899E8318D3CF4C68944C3DEC640AF5AB52D864AC50DAA8D145B3494F75FA3CFF939FCBDDA431DAD3CA79738B297795818CF" + }, + "apis/admissionregistration.k8s.io/v1": { + "serverRelativeURL": "/openapi/v3/apis/admissionregistration.k8s.io/v1?hash=E19CC93A116982CE5422FC42B590A8AFAD92CDE9AE4D59B5CAAD568F083AD07946E6CB5817531680BCE6E215C16973CD39003B0425F3477CFD854E89A9DB6597" + }, + ... +} +``` + +The relative URLs are pointing to immutable OpenAPI descriptions, in +order to improve client-side caching. The proper HTTP caching headers +are also set by the apiserver for that purpose (`Expire` to 1 year in +the future, and `Cache-Control` to `immutable`). When an obsolete URL is +used, the apiserver will return a redirect to the newest URL. + +The Kubernetes API server proxies an OpenAPI v3 spec per Kubernetes +group version at the `/openapi/v3/apis//?hash=` +endpoint. + +Please refer to the table below for accepted request headers. @@ -126,9 +150,6 @@ table below for accepted request headers.
Valid request header values for OpenAPI v3 queries
-A discovery endpoint `/openapi/v3` is provided to see a list of all -group/versions available. This endpoint only returns JSON. - ## Persistence Kubernetes stores the serialized state of objects by writing them into From ca0a2df7b75c60c1e68354e4d2f9f053e7307895 Mon Sep 17 00:00:00 2001 From: Jefftree Date: Mon, 11 Apr 2022 16:51:24 -0700 Subject: [PATCH 2/5] Address comments --- content/en/docs/concepts/overview/kubernetes-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/concepts/overview/kubernetes-api.md b/content/en/docs/concepts/overview/kubernetes-api.md index 47b31ef509..0ba09e8943 100644 --- a/content/en/docs/concepts/overview/kubernetes-api.md +++ b/content/en/docs/concepts/overview/kubernetes-api.md @@ -109,11 +109,11 @@ are provided in the following format: The relative URLs are pointing to immutable OpenAPI descriptions, in order to improve client-side caching. The proper HTTP caching headers -are also set by the apiserver for that purpose (`Expire` to 1 year in +are also set by the API server for that purpose (`Expires` to 1 year in the future, and `Cache-Control` to `immutable`). When an obsolete URL is -used, the apiserver will return a redirect to the newest URL. +used, the API server will return a redirect to the newest URL. -The Kubernetes API server proxies an OpenAPI v3 spec per Kubernetes +The Kubernetes API server publishes an OpenAPI v3 spec per Kubernetes group version at the `/openapi/v3/apis//?hash=` endpoint. From 047a0f47040100ac8f8142fc4b92f2547bc36cd7 Mon Sep 17 00:00:00 2001 From: Antoine Pelisse Date: Tue, 12 Apr 2022 08:48:34 -0700 Subject: [PATCH 3/5] Add OpenAPIv3 as enabled by defaulted, and released beta in v1.24 --- .../docs/reference/command-line-tools-reference/feature-gates.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index 29ffd79bb8..e0f5552125 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates.md @@ -159,6 +159,7 @@ different Kubernetes components. | `OpenAPIEnums` | `false` | Alpha | 1.23 | 1.23 | | `OpenAPIEnums` | `false` | Beta | 1.24 | | | `OpenAPIV3` | `false` | Alpha | 1.23 | | +| `OpenAPIV3` | `true` | Beta | 1.24 | | | `PodAndContainerStatsFromCRI` | `false` | Alpha | 1.23 | | | `PodDeletionCost` | `false` | Alpha | 1.21 | 1.21 | | `PodDeletionCost` | `true` | Beta | 1.22 | | From cfa004ae6ae34ed6d767f2f6fccb485722918c25 Mon Sep 17 00:00:00 2001 From: Antoine Pelisse Date: Tue, 12 Apr 2022 08:54:35 -0700 Subject: [PATCH 4/5] Address more feedback --- content/en/docs/concepts/overview/kubernetes-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/concepts/overview/kubernetes-api.md b/content/en/docs/concepts/overview/kubernetes-api.md index 0ba09e8943..b7ed2e02e4 100644 --- a/content/en/docs/concepts/overview/kubernetes-api.md +++ b/content/en/docs/concepts/overview/kubernetes-api.md @@ -111,13 +111,13 @@ The relative URLs are pointing to immutable OpenAPI descriptions, in order to improve client-side caching. The proper HTTP caching headers are also set by the API server for that purpose (`Expires` to 1 year in the future, and `Cache-Control` to `immutable`). When an obsolete URL is -used, the API server will return a redirect to the newest URL. +used, the API server returns a redirect to the newest URL. The Kubernetes API server publishes an OpenAPI v3 spec per Kubernetes group version at the `/openapi/v3/apis//?hash=` endpoint. -Please refer to the table below for accepted request headers. +Refer to the table below for accepted request headers. From 11333a4851785eb33d738af6f0f0cc889a126681 Mon Sep 17 00:00:00 2001 From: Antoine Pelisse Date: Tue, 12 Apr 2022 10:33:30 -0700 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Tim Bannister --- content/en/docs/concepts/overview/kubernetes-api.md | 2 +- .../reference/command-line-tools-reference/feature-gates.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/concepts/overview/kubernetes-api.md b/content/en/docs/concepts/overview/kubernetes-api.md index b7ed2e02e4..3c0bba3adb 100644 --- a/content/en/docs/concepts/overview/kubernetes-api.md +++ b/content/en/docs/concepts/overview/kubernetes-api.md @@ -84,7 +84,7 @@ packages that define the API objects. {{< feature-state state="beta" for_k8s_version="v1.24" >}} -Kubernetes v1.24 offers beta support for publishing its APIs as OpenAPI v3; this is a +Kubernetes {{< param "version" >}} offers beta support for publishing its APIs as OpenAPI v3; this is a beta feature that is enabled by default. You can disable the beta feature by turning off the [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) named `OpenAPIV3` diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index e0f5552125..8046d2c120 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates.md @@ -158,7 +158,7 @@ different Kubernetes components. | `NodeOutOfServiceVolumeDetach` | `false` | Alpha | 1.24 | | | `OpenAPIEnums` | `false` | Alpha | 1.23 | 1.23 | | `OpenAPIEnums` | `false` | Beta | 1.24 | | -| `OpenAPIV3` | `false` | Alpha | 1.23 | | +| `OpenAPIV3` | `false` | Alpha | 1.23 | 1.23 | | `OpenAPIV3` | `true` | Beta | 1.24 | | | `PodAndContainerStatsFromCRI` | `false` | Alpha | 1.23 | | | `PodDeletionCost` | `false` | Alpha | 1.21 | 1.21 |
Valid request header values for OpenAPI v3 queries