Merge pull request #3773 from Jefftree/oasv3-ga

KEP-2896: OpenAPI V3 to GA

Author: k8s-ci-robot

keps/prod-readiness/sig-api-machinery/2896.yaml

@@ -3,3 +3,5 @@ alpha:
   approver: "@deads2k"
 beta:
   approver: "@deads2k"
+stable:
+  approver: "@deads2k"

keps/sig-api-machinery/2896-openapi-v3/README.md

@@ -63,6 +63,7 @@ Architecture for cross-cutting KEPs). -->
 - [Proposal](#proposal)
   - [Notes/Constraints/Caveats (Optional)](#notesconstraintscaveats-optional)
     - [Future Work](#future-work)
+    - [OpenAPI V2 plan](#openapi-v2-plan)
   - [Risks and Mitigations](#risks-and-mitigations)
 - [Design Details](#design-details)
   - [Paths](#paths)
@@ -73,10 +74,12 @@ Architecture for cross-cutting KEPs). -->
   - [OpenAPI](#openapi)
   - [Version Skew](#version-skew)
   - [OpenAPI V3 Proto](#openapi-v3-proto)
+  - [Clients](#clients)
   - [Test Plan](#test-plan)
   - [Graduation Criteria](#graduation-criteria)
     - [Alpha](#alpha)
     - [Beta](#beta)
+    - [GA](#ga)
   - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
   - [Version Skew Strategy](#version-skew-strategy)
 - [Production Readiness Review Questionnaire](#production-readiness-review-questionnaire)
@@ -209,6 +212,17 @@ endpoints.
 After OpenAPI v3 is implemented, we can start working on updating clients to
 consume OpenAPI v3. A separate KEP will be published for that.
 
+#### OpenAPI V2 plan
+
+As OpenAPI V3 becomes more and more available and easily accessible,
+clients should move to OpenAPI V3 in favor of OpenAPI V2. This should
+result in a steady decline in the number of requests sent to the
+OpenAPI V2 endpoint. In the short term, we will make OpenAPI V2 make
+computations more lazily, deferring the aggregation and marshaling
+process to be on demand rather than at a set interval. This is not
+directly part of OpenAPI V3's GA plan, but is something we will be
+monitoring closely once OpenAPI V3 is GA.
+
 ### Risks and Mitigations
 
 Aggregation for OpenAPI v2 already consumes a non-negligible amount of
@@ -277,6 +291,12 @@ updates. If there is a race and the client passes in an outdated etag
 value, the server will send a 301 to redirect the client to the URL
 with the latest etag value.
 
+To ensure that the client cache does not grow in an unbounded manner,
+the client-go disk cache will be replaced with a cmopactable disk
+cache which performs occasional cleanup of old cached files. Refer to
+[PR](https://github.com/kubernetes/kubernetes/pull/109701) for more
+details.
+
 ### Controllers
 
 #### OpenAPI Builder
@@ -383,6 +403,16 @@ This solves the immediate protobuf issue but adds complexity to the OpenAPI sche
 
 The final alternative is to upgrade to OpenAPI 3.1 where the new JSON Schema version it is based off of supports fields alongside a `$ref`. However, OpenAPI does not follow semvar and 3.1 is a major upgrade over 3.0 and introduces various backwards incompatible changes. Furthermore, library support is currently lacking (gnostic) and doesn't fully support OpenAPI 3.1. One important backwards incompatible change is the removal of the nullable field and replacing it by changing the type field from a single string to an array of strings.
 
+### Clients
+
+Updating all OpenAPI V2 clients to use OpenAPI V3 is outside the scope
+of this KEP and part of future work. However, some key clients will be
+updated to use OpenAPI V3 as part of GA. One example is [OpenAPI V3
+for kubectl
+explain](https://github.com/kubernetes/enhancements/blob/master/keps/sig-cli/3515-kubectl-explain-openapiv3/README.md).
+Server Side Apply will also be updated to directly use the OpenAPI V3
+schema rather than OpenAPI V2. Finally, the query param verifier in
+kubectl will be updated to use OpenAPI V3.
 
 ### Test Plan
 
@@ -407,6 +437,8 @@ For alpha, unit tests will be included to ensure that v3 schemas are properly
 generated and published. A validator will also be used to ensure that the spec
 generated is valid OpenAPI v3.
 
+A fuzzer and performance benchmark tests will also be included.
+
 ### Graduation Criteria
 
 #### Alpha
@@ -420,13 +452,20 @@ generated is valid OpenAPI v3.
   - Incorrect OpenAPI polymorphic types (IntOrString, Quantity) are updated to use `anyOf` in OpenAPI V3
 - Definition names of native resources are updated to omit their package paths
 - Parameters are reused as components
-- `kubectl explain` to support using the OpenAPI v3 Schema
 - Aggregated API servers are queried for their v2 endpoint and converted to
   publish v3 if they do not directly publish v3
 - Heuristics are used for the OpenAPI v2 to v3 conversion to maximize
   correctness of published spec
 - Aggregation for OpenAPI v3 will serve as a proxy to downstream OpenAPI paths
 
+#### GA
+
+- OpenAPI V3 uses the optimized JSON marshaler for increased performance. See [link](https://github.com/kubernetes/kube-openapi/pull/319) for the benefits with OpenAPI V2.
+- [Updated OpenAPI V3 Client Interface](https://docs.google.com/document/d/1HmqJH-yyK8WyU8V1y5z-RyMLq9-Xe8JfTTuaNkm9GZ0)
+- Direct conversion from OpenAPI V3 to SMD schema for Server Side Apply
+- HTTP Disk Cache is replaced with Compactable Disk Cache
+- Conformance tests
+
 ### Upgrade / Downgrade Strategy
 
 <!-- If applicable, how will the component be upgraded and downgraded? Make sure

keps/sig-api-machinery/2896-openapi-v3/kep.yaml

@@ -1,4 +1,4 @@
-title: KEP Template
+title: OpenAPI V3
 kep-number: 2896
 authors:
   - "@jefftree"
@@ -14,17 +14,18 @@ approvers:
   - "@lavalamp"
 
 # The target maturity stage in the current dev cycle for this KEP.
-stage: beta
+stage: stable
 
 # The most recent milestone for which work toward delivery of this KEP has been
 # done. This can be the current (upcoming) milestone, if it is being actively
 # worked on.
-latest-milestone: "v1.24"
+latest-milestone: "v1.27"
 
 # The milestone at which this feature was, or is targeted to be, at each stage.
 milestone:
   alpha: "v1.23"
   beta: "v1.24"
+  stable: "v1.27"
 
 # The following PRR answers are required at alpha release
 # List the feature gate name and the components for which it must be enabled