From cac07f50bb1e6771d293635b96b9447481213b89 Mon Sep 17 00:00:00 2001
From: Jefftree <jeffrey.ying86@live.com>
Date: Wed, 8 Sep 2021 08:54:07 -0700
Subject: [PATCH] deads2k comment

---
 .../sig-api-machinery/2896-openapi-v3/README.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/keps/sig-api-machinery/2896-openapi-v3/README.md b/keps/sig-api-machinery/2896-openapi-v3/README.md
index 2a1b5440e5a6..b3f9d1d4b6ee 100644
--- a/keps/sig-api-machinery/2896-openapi-v3/README.md
+++ b/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