Address comments

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

@@ -60,68 +60,41 @@ SIG Architecture for cross-cutting KEPs).
 -->
 # KEP-2896: OpenAPI V3
 
-<!--
-This is the title of your KEP. Keep it short, simple, and descriptive. A good
-title can help communicate what the KEP is and should be considered as part of
-any review.
--->
-
-<!--
-A table of contents is helpful for quickly jumping to sections of a KEP and for
-highlighting any additional information provided beyond the standard KEP
-template.
-
-Ensure the TOC is wrapped with
-  <code>&lt;!-- toc --&rt;&lt;!-- /toc --&rt;</code>
-tags, and then generate with `hack/update-toc.sh`.
--->
-
 <!-- toc -->
 - [Release Signoff Checklist](#release-signoff-checklist)
 - [Summary](#summary)
 - [Motivation](#motivation)
   - [Goals](#goals)
+    - [Transparency in the OpenAPI](#transparency-in-the-openapi)
   - [Non-Goals](#non-goals)
 - [Proposal](#proposal)
-  - [User Stories (Optional)](#user-stories-optional)
-    - [Story 1](#story-1)
-    - [Story 2](#story-2)
   - [Notes/Constraints/Caveats (Optional)](#notesconstraintscaveats-optional)
+    - [Future Work](#future-work)
   - [Risks and Mitigations](#risks-and-mitigations)
 - [Design Details](#design-details)
+  - [Paths](#paths)
+  - [Controllers](#controllers)
+    - [OpenAPI Builder](#openapi-builder)
+    - [Proto Models &amp; ETags](#proto-models--etags)
+    - [Aggregator](#aggregator)
+  - [OpenAPI](#openapi)
+  - [Version Skew](#version-skew)
   - [Test Plan](#test-plan)
   - [Graduation Criteria](#graduation-criteria)
+    - [Alpha](#alpha)
+    - [Beta](#beta)
   - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
   - [Version Skew Strategy](#version-skew-strategy)
 - [Production Readiness Review Questionnaire](#production-readiness-review-questionnaire)
   - [Feature Enablement and Rollback](#feature-enablement-and-rollback)
-  - [Rollout, Upgrade and Rollback Planning](#rollout-upgrade-and-rollback-planning)
-  - [Monitoring Requirements](#monitoring-requirements)
-  - [Dependencies](#dependencies)
   - [Scalability](#scalability)
-  - [Troubleshooting](#troubleshooting)
 - [Implementation History](#implementation-history)
 - [Drawbacks](#drawbacks)
 - [Alternatives](#alternatives)
-- [Infrastructure Needed (Optional)](#infrastructure-needed-optional)
 <!-- /toc -->
 
 ## Release Signoff Checklist
 
-<!--
-**ACTION REQUIRED:** In order to merge code into a release, there must be an
-issue in [kubernetes/enhancements] referencing this KEP and targeting a release
-milestone **before the [Enhancement Freeze](https://git.k8s.io/sig-release/releases)
-of the targeted release**.
-
-For enhancements that make changes to code or processes/procedures in core
-Kubernetes—i.e., [kubernetes/kubernetes], we require the following Release
-Signoff checklist to be completed.
-
-Check these off as they are completed for the Release Team to track. These
-checklist items _must_ be updated for the enhancement to be released.
--->
-
 Items marked with (R) are required *prior to targeting to a milestone / release*.
 
 - [ ] (R) Enhancement issue in release milestone, which links to KEP dir in [kubernetes/enhancements] (not the initial KEP PR)
@@ -150,48 +123,16 @@ Items marked with (R) are required *prior to targeting to a milestone / release*
 
 ## Summary
 
-<!--
-This section is incredibly important for producing high-quality, user-focused
-documentation such as release notes or a development roadmap. It should be
-possible to collect this information before implementation begins, in order to
-avoid requiring implementors to split their attention between writing release
-notes and implementing the feature itself. KEP editors and SIG Docs
-should help to ensure that the tone and content of the `Summary` section is
-useful for a wide audience.
-
-A good summary is probably at least a paragraph in length.
-
-Both in this section and below, follow the guidelines of the [documentation
-style guide]. In particular, wrap lines to a reasonable length, to make it
-easier for reviewers to cite specific portions, and to minimize diff churn on
-updates.
-
-[documentation style guide]: https://github.com/kubernetes/community/blob/master/contributors/guide/style-guide.md
--->
-
 This KEP proposes a new endpoint to publish the [OpenAPI v3 specification](https://swagger.io/specification/) for Kubernetes types. This solves our problem of stripping fields when publishing the OpenAPI v2 and improves the transparency and accuracy of the published OpenAPI.
 
 
 ## Motivation
 
-<!--
-This section is for explicitly listing the motivation, goals, and non-goals of
-this KEP.  Describe why the change is important and the benefits to users. The
-motivation section can optionally provide links to [experience reports] to
-demonstrate the interest in a KEP within the wider Kubernetes community.
-
-[experience reports]: https://github.com/golang/go/wiki/ExperienceReports
--->
-
 Kubernetes resources and types can be described through their OpenAPI definitions, currently served as OpenAPI v2 at the $cluster/openapi/v2 cluster endpoint. With the introduction of CRDs, users provide an OpenAPI v3 spec to describe the resource. Since kubernetes only publishes OpenAPI v2, these definitions are converted into an OpenAPI v2 definition before being aggregated and served at the /openapi/v2 endpoint. OpenAPI v3 is more expressive than v2, and the conversion results in the loss of some information. Some of the type definitions are just transformed into “accept anything” definitions because of our lack of ability to perform a better conversion and limitations in kubectl. Some efforts at improving the OpenAPI (eg: enum support) are targeted to bo bundled with OpenAPI v3.
 
 Additionally, since kubernetes aggregate the OpenAPI v2 spec for all specs into one endpoint, whenever a spec is modified the entire spec is updated and all clients will need to redownload the spec. Depending on the size and number of CRDs, this is not an inexpensive operation.
 
 ### Goals
-<!--
-List the specific goals of the KEP. What is it trying to achieve? How will we
-know that this has succeeded?
--->
 
 - Support publishing and aggregating OpenAPI v3 for all kubernetes types
 - Published v3 spec should be a lossless representation of the data and no fields should be stripped for both built-in types and CRDs
@@ -265,7 +206,7 @@ The overarching `/openapi/v3` endpoint will contain the list of paths (groups) a
 }
 ```
 
-Based on the provided group, clients can then request `openapi/v3/apis/apps`, `/openapi/v3/apis/networking.k8s.io` and etc. These leaf node specs are self contained OpenAPI v3 specs and include all referenced types.
+Based on the provided group, clients can then request `openapi/v3/apis/apps/v1`, `/openapi/v3/apis/networking.k8s.io/v1` and etc. These leaf node specs are self contained OpenAPI v3 specs and include all referenced types.
 
 ### Controllers
 
@@ -311,6 +252,10 @@ type OpenAPIv3 struct {
 
 There is a potential version skew between old aggregated apiservers and a new kube-apiserver. All new aggregated apiservers will publish v3 which will be discovered and published by the aggregator for v3. Old aggregated apiservers will not publish v3, and the aggregator cannot discover the v3 schema for the corresponding aggregated apiservers. The v3 schema for the old apiservers will not be published by the aggregator until they are upgraded to support v3. Regardless of version skew, v2 aggregation will continue for all aggregated apiservers.
 
+It is technically possible for the aggregator handling OpenAPI v3 to download from the OpenAPI v2 schema, but there are a few tradeoffs that I believe make this not worthwhile. The OpenAPI v3 aggregator must publish OpenAPI v3, and OpenAPI v2 will need to be converted if it is intended to be used. The v3 schema is designed to be a lossless representation of a user's spec, but by going through OpenAPI v2, critical information may have already been lost. Publishing an inaccurate v3 schema is not desirable and is not in line with the primary goal of this KEP. Converting from OpenAPI v2 to v3 via the Swagger/OpenAPI structs after publishing is also much more complicated than modifying the OpenAPI generation before publishing.
+
+By not publishing the v3 spec for old aggregated apiservers, the v3 spec is not a full representation of all the resources and endpoints available within the cluster. However, the scope of this is limited to select group-versions claimed by the select aggregated apiservers. A group-version in v3 will either have a fully lossless OpenAPI v3 or be non-existent (old aggregated apiserver), preventing a partial lossy spec from being published. This should also serve as a good incentive for users to upgrade their aggregated apiservers to the latest version and publish OpenAPI v3.
+
 ### Test Plan
 
 <!--
@@ -331,7 +276,7 @@ when drafting this test plan.
 [testing-guidelines]: https://git.k8s.io/community/contributors/devel/sig-testing/testing.md
 -->
 
-For alpha, unit tests will be included to ensure that v3 schemas are properly generated and published.
+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.
 
 ### Graduation Criteria
 
@@ -343,7 +288,8 @@ For alpha, unit tests will be included to ensure that v3 schemas are properly ge
 #### Beta
 
 - Native types are updated to capture capabilities introduced with v3
-
+- Definition names of native resources are updated to omit their package paths
+- Parameters are reused as components
 
 ### Upgrade / Downgrade Strategy