deads2k comment

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

@@ -312,6 +312,20 @@ type OpenAPIv3 struct {
 
 ### Version Skew
 
+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. To make the v2 to v3 transition process
+smoother when a version skew exists, the aggregator will download the v2 schema
+from aggregated apiservers if they have not upgraded to v3. This will provide
+clients with an option to only use the v3 endpoint and they can immediately drop
+support for v2. The drawback is that v2 is lossy and converting it to
+v3 will provide a lossy v3 schema. This problem will be fixed when aggregated
+apiservers upgrade to publishing v3.
+
+<!--
+TODO|jefftree: remove this section if the above is adopted
 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
@@ -347,6 +361,7 @@ serve as an incentive for clients to support v3. When clients fall back to v2
 due to an old aggregated apiserver, the operation will take much longer and
 operate on a lossy schema. To mitigate this, developers and operators should
 upgrade their aggregated apiservers.
+-->
 
 ### Test Plan
 
@@ -384,6 +399,8 @@ generated is valid 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 (with fallback to V2)
+- Aggregated API servers are queried for their V2 endpoint and converted to
+  publish V3 if they do not directly publish V3
 
 ### Upgrade / Downgrade Strategy