diff --git a/keps/sig-cli/3515-kubectl-explain-openapiv3/README.md b/keps/sig-cli/3515-kubectl-explain-openapiv3/README.md index 82bd35924881..b807246e8a6b 100644 --- a/keps/sig-cli/3515-kubectl-explain-openapiv3/README.md +++ b/keps/sig-cli/3515-kubectl-explain-openapiv3/README.md @@ -624,8 +624,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 `KUBECTL_EXPLAIN_OPENAPIV3` which toggles validity of `--output` flag - (to be renamed to --output when feature is no longer experimental) + - Describe the mechanism: disablement via `--output plaintext-openapiv2` CLI argument for `explain` subcommand - Will enabling / disabling the feature require downtime of the control plane? No - Will enabling / disabling the feature require downtime or reprovisioning @@ -644,7 +643,7 @@ information populated. ###### Can the feature be disabled once it has been enabled (i.e. can we roll back the enablement)? -Until the feature is stable it will only be enabled when the environment variable is used. +Yes, providing `--output plaintext-openapiv2` will disable the feature. It has no persistent effect on data that is viewewd. ###### What happens if we reenable the feature if it was previously rolled back? @@ -674,15 +673,8 @@ This section must be completed when targeting beta to a release. ###### How can a rollout or rollback fail? Can it impact already running workloads? - +No, this is a user-interactive CLI feature. If users don't like it they can +use the old functionality by providing arguments `--output plaintext-openapiv2` ###### What specific metrics should inform a rollback? @@ -693,11 +685,8 @@ that might indicate a serious problem? ###### Were upgrade and rollback tested? Was the upgrade->downgrade->upgrade path tested? - +This feature has no state in the cluster. Using `explain` on a cluster cannot +affect other users. ###### Is the rollout accompanied by any deprecations and/or removals of features, APIs, fields of API types, flags, etc.? @@ -705,6 +694,8 @@ are missing a bunch of machinery and tooling and can't do that now. Even if applying deprecation policies, they may still surprise some users. --> +No. + ### Monitoring Requirements +There is no direct metrics of `explain` users, but operators can indirectly +guage usership by watching openapi v3 metrics. + ###### How can someone using this feature know that it is working for their instance? ```shell -kubectl explain pods --output openapiv3 +kubectl explain pods --output plaintext ``` User should see OpenAPI v3 JSON Schema for `pods` type printed to console. ###### What are the reasonable SLOs (Service Level Objectives) for the enhancement? +N/A + +N/A ### Dependencies +None ###### Does this feature depend on any specific services running in the cluster? @@ -791,7 +789,7 @@ and creating new ones, as well as about cluster-level services (e.g. DNS): --> To reap the benefits of this feature, OpenAPI v3 is required, however OpenAPI v2 -data can be used as a fallback. +data can be used as a fallback. OpenAPI V3 is GA as of Kubernetes 1.27. ### Scalability @@ -815,7 +813,8 @@ not changed the server incurs a cheap, almost negligible cost to serving the req The document returned by calls to `/openapi/v3/...` is expected to be far smaller than the megabytes-scale openapi v2 document, since it only includes information -for a single group-version. +for a single group-version. Additionally, this new mechanism is far more cache-friendly +so the expectation is that far less data will need to be transferred.