From d489f8821b474c0dc5a0864424806cda0f635b82 Mon Sep 17 00:00:00 2001 From: Alexander Zielenski <351783+alexzielenski@users.noreply.github.com> Date: Tue, 17 Jan 2023 11:21:09 -0800 Subject: [PATCH] openapiv3 for kubectl explain to beta --- keps/prod-readiness/sig-cli/3515.yaml | 2 + .../3515-kubectl-explain-openapiv3/README.md | 60 +++---------------- .../3515-kubectl-explain-openapiv3/kep.yaml | 8 +-- 3 files changed, 15 insertions(+), 55 deletions(-) diff --git a/keps/prod-readiness/sig-cli/3515.yaml b/keps/prod-readiness/sig-cli/3515.yaml index b2bb14812b07..189166feb8fd 100644 --- a/keps/prod-readiness/sig-cli/3515.yaml +++ b/keps/prod-readiness/sig-cli/3515.yaml @@ -1,3 +1,5 @@ kep-number: 3515 alpha: approver: "@johnbelamaric" +beta: + approver: "@johnbelamaric" diff --git a/keps/sig-cli/3515-kubectl-explain-openapiv3/README.md b/keps/sig-cli/3515-kubectl-explain-openapiv3/README.md index 63532363c3f1..bf5f68492d1b 100644 --- a/keps/sig-cli/3515-kubectl-explain-openapiv3/README.md +++ b/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,29 +456,22 @@ 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 @@ -521,7 +479,7 @@ As of Kubernetes 1.24 OpenAPIV3 entered beta and become enabled by default, ther 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.