openapiv3 for kubectl explain to beta

keps/prod-readiness/sig-cli/3515.yaml

@@ -1,3 +1,5 @@
 kep-number: 3515
 alpha:
   approver: "@johnbelamaric"
+beta:
+  approver: "@johnbelamaric"

keps/sig-cli/3515-kubectl-explain-openapiv3/README.md

@@ -222,7 +222,6 @@ wiping nullable fields.
 3. Fallback to old `explain` implementation if cluster does not expose OpenAPI v3 data.
 4. Provide multiple new output formats for kubectl explain:
     * human-readable plaintext
-    * markdown
     * maybe others
 5. (Optional?) Allow users to specify their own templates for use with kubectl
   explain (there may be interesting use cases for this)
@@ -286,40 +285,6 @@ This command is useful not only for its convenience, but also other visualizatio
 may be built upon the raw output if we opt not to support a first-class custom
 template solution in the future.
 
-#### HTML
-
-> PROVISIONAL SECTION
-
-```shell
-kubectl explain pods --output html
-```
-
-Similarly to [godoc](https://pkg.go.dev), we suggest to provide a searchable,
-navigable, generated webpage for the kubernetes types of whatever cluster kubectl
-is talking to.
-
-Only the fields selected in the command line (and their subfields' types, etc) 
-will be included in the resultant page.
-
-Possible idea: If user types `kubectl explain --output html` with no specific target, 
-then all types in the cluster are included.
-
-#### Markdown
-> PROVISIONAL SECTION
-
-```shell
-kubectl explain pods --output md
-```
-
-When using the `md` template, a markdown document is printed to stdout, so it
-might be saved and used for a documentation website, for example.
-
-Similarly to `html` output, only the fields selected in the command line 
-(and their subfields' types, etc) will be included in the resultant page.
-
-Possible idea: If user types `kubectl explain --output md` with no specific target,
-then all types in the cluster are included.
-
 ### Risks and Mitigations
 
 #### OpenAPI V3 Not Available
@@ -491,37 +456,30 @@ Defined using feature gate
 - Plaintext output roughly matches explain output
 - OpenAPIV3 (raw json) output implemented
 
-#### Alpha 2
-
-If we decide to move ahead with the `md` and `html` outputs, an Alpha 2 may
-be required.
-
-- `md` output implemented (or dropped from design due to continued debate)
-  - Table of contents all GVKs grouped by Group then Version.
-  - Section for each individual GVK
-  - All types hyperlink to specific section
--  basic `html` output  (or dropped from design due to continued debate)
-  - Table of contents all GVKs grouped by Group then Version.
-  - Page for each individual GVK.
-  - All types hyperlink to their specific page
-  - Searchable by name, description, field name.
-
 #### Beta
 
 - kube-openAPI v3 JSON deserialization is optimized to take less than 150ms on
   most machines
+    - No longer a goal for beta - we don't use kube-openapi types in this 
+      implementation. However a benchmark should still be written to measure
+      deserialization into the type used `map[string]any`
+
 - OpenAPI V3 is enabled by default on at least one version within kubectl's support window.
 As of Kubernetes 1.24 OpenAPIV3 entered beta and become enabled by default, therefore meeting this requirement.
+  - OpenAPI V3 has been Beta enabled by default since 1.24. Kubectl support window is +- 1 version. All clusters in kubectl's
+    support window have OpenAPI V3 enabled by default.
+
 - `--output plaintext` is on-by-default and environment variable is removed/on by default
 - `--output plaintext-openapiv2` added as a name for the old `explain` implementation, so the feature may be positively disabled.
+  - []TODO: Alias old implementation to plaintext-openapiv2
 
 #### GA
 
 - OpenAPIV3 is GA and has been since at least the minimum supported apiserver version
 by kubectl.
 - All kube-apiserver releases within version skew of kubectl should have OpenAPIV3 on by default. This is true as of kubectl for Kubernetes 1.25
 - Old `kubectl explain` implementation is removed, as is support for OpenAPIV2-backed `kubectl explain`
-- `--output plaintext-openapiv2` has been deprecated for at least one release
+- `--output plaintext-openapiv2` is deprecated.
 
 <!--
 **Note:** *Not required until targeted at a release.*

keps/sig-cli/3515-kubectl-explain-openapiv3/kep.yaml

@@ -13,13 +13,13 @@ approvers:
   - "@KnVerey"
   - "@seans3"
 creation-date: "2022-09-14"
-last-updated: v1.26
+last-updated: v1.27
 status: implementable
-stage: alpha
-latest-milestone: "1.26"
+stage: beta
+latest-milestone: "1.27"
 milestone:
     alpha: "1.26"
-    beta: "1.28"
+    beta: "1.27"
     stable: "1.29"
 feature-gates: []
 disable-supported: true