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

@@ -89,8 +89,6 @@ tags, and then generate with `hack/update-toc.sh`.
   - [Built-in Template Options](#built-in-template-options)
     - [Plaintext](#plaintext)
     - [OpenAPIV3 (raw json)](#openapiv3-raw-json)
-    - [HTML](#html)
-    - [Markdown](#markdown)
   - [Risks and Mitigations](#risks-and-mitigations)
     - [OpenAPI V3 Not Available](#openapi-v3-not-available)
       - [Risk](#risk)
@@ -109,7 +107,6 @@ tags, and then generate with `hack/update-toc.sh`.
       - [e2e tests](#e2e-tests)
   - [Graduation Criteria](#graduation-criteria)
     - [Alpha 1](#alpha-1)
-    - [Alpha 2](#alpha-2)
     - [Beta](#beta)
     - [GA](#ga)
   - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
@@ -126,6 +123,7 @@ tags, and then generate with `hack/update-toc.sh`.
 - [Alternatives](#alternatives)
   - [Implement proto.Models for OpenAPI V3 data](#implement-protomodels-for-openapi-v3-data)
   - [Custom User Templates](#custom-user-templates)
+  - [Other template outputs](#other-template-outputs)
 <!-- /toc -->
 
 ## Release Signoff Checklist
@@ -222,7 +220,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 +283,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 +454,23 @@ 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
 - 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.
+In Kubectl for release 1.25, all k8s versions within support window will be able to have OpenAPIV3 enabled.
+However, the fallback is kept around since it may not always be enabled.
+
 - `--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.
 
 #### 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
+- OpenAPIV3 should be stable for all k8s versions within skew.
 - 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.*
@@ -676,7 +625,7 @@ well as the [existing list] of feature gates.
   - Feature gate name:
   - Components depending on the feature gate:
 - [x] Other
-  - Describe the mechanism: Environment variable `ENABLE_EXPLAIN_OPENAPIV3` which toggles validity of `--output` flag
+  - Describe the mechanism: Environment variable `KUBECTL_EXPLAIN_OPENAPIV3` which toggles validity of `--output` flag
     (to be renamed to --output when feature is no longer experimental)
   - Will enabling / disabling the feature require downtime of the control
     plane? No
@@ -990,3 +939,21 @@ Since the API surface for this sort of feature remains very unclear and will lik
 be very unstable, this sort of feature should be delayed until the internal
 templates have proven the API surface to be used. To do otherwise would risk
 breaking user's templates.
+
+### Other template outputs
+
+We considered an `md` and `html` template for this KEP, possibly with the following
+requirements:
+
+ - `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.
+
+This was removed from scope for the KEP to focus only on the feature users rely
+on which is the plaintext explain. These templates may be added in the future.

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