Skip to content

Commit

Permalink
fill in beta prr sections
Browse files Browse the repository at this point in the history
whoops did not realize about these
  • Loading branch information
alexzielenski committed Feb 2, 2023
1 parent 05a548d commit 13aed07
Showing 1 changed file with 20 additions and 21 deletions.
41 changes: 20 additions & 21 deletions keps/sig-cli/3515-kubectl-explain-openapiv3/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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?
Expand Down Expand Up @@ -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?

<!--
Try to be as paranoid as possible - e.g., what if some components will restart
mid-rollout?
Be sure to consider highly-available clusters, where, for example,
feature flags will be enabled on some API servers and not others during the
rollout. Similarly, consider large clusters and how enablement/disablement
will rollout across nodes.
-->
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?

Expand All @@ -693,18 +685,17 @@ that might indicate a serious problem?

###### Were upgrade and rollback tested? Was the upgrade->downgrade->upgrade path tested?

<!--
Describe manual testing that was done and the outcomes.
Longer term, we may want to require automated upgrade/rollback tests, but we
are missing a bunch of machinery and tooling and can't do that now.
-->
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.?

<!--
Even if applying deprecation policies, they may still surprise some users.
-->

No.

### Monitoring Requirements

<!--
Expand All @@ -722,16 +713,21 @@ checking if there are objects with field X set) may be a last resort. Avoid
logs or events for this purpose.
-->

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

<!--
This is your opportunity to define what "normal" quality of service looks like
for a feature.
Expand All @@ -758,20 +754,22 @@ Pick one more of these and delete the rest.
- [Optional] Aggregation method:
- Components exposing the metric:
- [ ] Other (treat as last resort)
- Details:
- Details: N/A for user-interactive CLI feature

###### Are there any missing metrics that would be useful to have to improve observability of this feature?

<!--
Describe the metrics themselves and the reasons why they weren't added (e.g., cost,
implementation difficulties, etc.).
-->
N/A

### Dependencies

<!--
This section must be completed when targeting beta to a release.
-->
None

###### Does this feature depend on any specific services running in the cluster?

Expand All @@ -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

Expand All @@ -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.

<!--
Describe them, providing:
Expand Down

0 comments on commit 13aed07

Please sign in to comment.