KEP-3515: add new kep kubectl explain openapi v3 upgrade

[alexzielenski]

• One-line PR description: adding new draft KEP

• Issue link: OpenAPI v3 for kubectl explain #3515

• Other comments:

[apelisse]

I think considering the number of requests that kubectl can make on an invocation (especially including discovery), an extra request after a 404 is perfectly fine.

[alexzielenski]

Right but 404 is a positive HTTP server response. i.e. it is able to respond you with an error. If there is no response from the server due to gateway issues or it being too busy you need to timeout the request from the client-side

[KnVerey]

Not saying this should be in scope for this KEP, but I think there's an interesting tie-in here to the ideas in kubernetes/kubectl#914. That issue proposes embedding templates that can be used to generate sample resources directly in the openAPI, so that instead of bespoke (and therefore unmaintainable) kubectl create commands, we could have fully extensible kubectl generate commands driven by this data. If kubectl explain is used to drive documentation in an even richer way thanks to this KEP, it would be pretty awesome if it could include generated examples in its output, perhaps through that mechanism.

[alexzielenski]

/assign @johnbelamaric

for prr review

[alexzielenski]

/label tide/merge-method-squash

[KnVerey]

After the recent change to the planned flag and having reflected more on the html/md options, I wanted to revisit this to make sure the flag set we've chosen isn't going to paint us into a corner. Even if we do add a default markdown implementation, it's easy to imagine that some users will prefer things to be displayed differently than we've chosen, leading to demand for this feature.

So, the new thought that has occurred to me is that it will technically be necessary for the user to be able to tell us which version of openAPI their template expects, similar to the problem we had with the long-term strategy around "raw". What would that look like? --output=openapiv3 --template /path/to/template.tmpl doesn't quite feel right... Our other commands that support file-based templating use --output=go-template-file --template=/path/to/template, so I think we'd want that for consistency. But it isn't sufficient, since as I was saying, the schema version isn't already inherent in the command, unlike in every case that currently exists.

So, maybe we need (at least) two flags after all, but not the ones we had this morning? I feel like I've talked myself in a circle. 😅

• --output=plaintext|openapi-json|md|html|go-template-file --> during alpha and beta, requires a compatibility check with the openapi version flag; "plaintext" would be compatible with v2 or v3, all others require v3. But the next migration to the theoretical v4 wouldn't require that, since all templates would be required to support it.
• --openapi-version=v2|v3--> This could be used to provide an opt-out via a "v2" value during the beta rollout period. At GA it becomes useless, so could be removed after deprecation (then re-introduced if we eventually need it again).
• And if we do add templating: --template=/path/to/template.tmpl

(all would presumably need the experimental prefix during alpha)

[alexzielenski]

I think our built-in templates can hardcode their supported openapi versions. If in the future we add custom templates and --template, then I think it would be appropriate to think about how associated metadata is included, and possibly then add the --openapi-version flag. I think the current proposal does not preclude that possibility.

[KnVerey]

What would it look like to hard code supported API versions? Do you mean in some convention surrounding how kubectl accesses them (not viable for custom templates), or within the template proper? I would think we couldn't embed the version in the template itself, since we'd need to parse the template to access it, which we couldn't do without knowing the version.

The implication I was seeing for the currently planned part of this proposal (sorry, it's kinda buried within the comment) is the value for the "raw" output format, because --output=openapiv3 --openapi-version=[whatever] seems problematic. If we change to something like --output=openapi-json then we end up requiring the separate flag to handle a version upgrade, but this thread supposes we may already have that requirement for other reasons.

[apelisse]

We already have the following in kubectl:

  -o, --output='': Output format. One of:
json|yaml|wide|name|custom-columns=...|custom-columns-file=...|go-template=...|go-template-file=...|jsonpath=...|jsonpath-file=...
See custom columns [http://kubernetes.io/docs/user-guide/kubectl-overview/#custom-columns], golang template
[http://golang.org/pkg/text/template/#pkg-overview] and jsonpath template
[http://kubernetes.io/docs/user-guide/jsonpath].

How about:

kubectl explain pods -o v3-template=/path/to/template.tmpl

[alexzielenski]

What would it look like to hard code supported API versions? Do you mean in some convention surrounding how kubectl accesses them (not viable for custom templates), or within the template proper?

It could be a map in the Go code that uses them. Or a naming convention from filename. Or a yaml that lives next to the templates with metadata. I am not attached to a specified idea. But the idea is that it is internal and does not need to extend to custom templates, as long as it possible to change in the future to allow custom templates.

How about:

kubectl explain pods -o v3-template=/path/to/template.tmpl

If we were ever to add templates in the future, I like this option since it is consistent with the existing -o flag as you pointed out.

[alexzielenski]

@KnVerey does your initial concern about leaving door open for future version-pinned templates still stand after hearing the above? Personally I am satisfied that we have not backed ourselves into a corner in terms of implementation or interface on this issue

[KnVerey]

Ah, you're right: I missed that the filepath could also be specified inline. I'm not sold on the specific option name because v3 refers to an openapi version, and openapi isn't anywhere in the command, so it sounds like it might instead refer to v3 of a templating system, or maybe of pod. Although part of me feels like we're mashing two concepts into one option, the main practical drawback of fully specifying --output=openapiv3-go-template= is verbosity. In any case, I won't block on this. The KEP as it stands now is simpler for the features certainly planned. Plus we have an opportunity to revisit naming if need be when we promote the flag out of experimental, at which point we should have a more solid stance on the custom template possibility.

[apelisse]

Thanks, I wasn't trying to find the best name, but I think the mechanism leaves the door open for the future. Thanks!

[KnVerey]

What would it look like to hard code supported API versions? Do you mean in some convention surrounding how kubectl accesses them (not viable for custom templates), or within the template proper? I would think we couldn't embed the version in the template itself, since we'd need to parse the template to access it, which we couldn't do without knowing the version.

The implication I was seeing for the currently planned part of this proposal (sorry, it's kinda buried within the comment) is the value for the "raw" output format, because --output=openapiv3 --openapi-version=[whatever] seems problematic. If we change to something like --output=openapi-json then we end up requiring the separate flag to handle a version upgrade, but this thread supposes we may already have that requirement for other reasons.

[KnVerey]

/lgtm
/approve

[alexzielenski]

/assign @johnbelamaric

[cici37]

If I remember correctly, OpenAPIV3 is Beta in 1.24 and has been on by default

[johnbelamaric]

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: alexzielenski, johnbelamaric, KnVerey, seans3

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• keps/prod-readiness/OWNERS [johnbelamaric]
• keps/sig-cli/OWNERS [KnVerey,johnbelamaric,seans3]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[seans3]

/lgtm

[tscswcn]

view