Add stub reference for KYAML

[rxinui]

Description

As requested here by @lmktfy - this PR serves as a placeholder and aims to provide KYAML supports reference.

Issue

Linked to #52523 (review)

[netlify]

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Name	Link
🔨 Latest commit	0eced77
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-vnext-staging/deploys/690ccaeec0f9120008c1df33

[netlify]

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	0eced77
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/690ccaee08b0350008b16019
😎 Deploy Preview	https://deploy-preview-52583--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[rxinui]

cc: @lmktfy @soltysh

[lmktfy]

/retitle [WIP] KYAML reference placeholder

[lmktfy]

/milestone 1.35

[rxinui]

CC: @thockin

[soltysh]

A few comments

[soltysh]

@rxinui is it still WIP, or this is ready for finalization?

[rxinui]

It is now ready @soltysh @lmktfy

No longer WIP.

[lmktfy]

Some feedback

[lmktfy]

The required follow-on work includes checking each of the examples (either with a linter program, or manually) to make sure it really is idiomatic, pretty printed, valid KYAML.

[rxinui]

I'm happy to see it go in, so long as there's enough of a commitment from other contributors (or from you, @rxinui, if you'd like to do more work).

No problem, will be happy to continue and help!

The required follow-on work includes checking each of the examples (either with a linter program, or manually) to make sure it really is idiomatic, pretty printed, valid KYAML.

I have updated the examples to provide working examples. All KYAML manifests have been tested using kubectl apply to ensure kube-apiserver validates them.

[lmktfy]

I'm happy to see it go in, so long as there's enough of a commitment from other contributors (or from you, @rxinui, if you'd like to do more work).

No problem, will be happy to continue and help!

The required follow-on work includes checking each of the examples (either with a linter program, or manually) to make sure it really is idiomatic, pretty printed, valid KYAML.

I have updated the examples to provide working examples. All KYAML manifests have been tested using kubectl apply to ensure kube-apiserver validates them.

kubectl accepts any valid YAML. We need to check that they're KYAML. Have a look at the KEP to see what's actually required.

[lmktfy]

In kubernetes/enhancements#5295 (comment) @thockin mentioned yamlfmt.

The test I want to use is: are our examples of KYAML correct enough that people will look at them and not feel misled?

(a later PR might want to hint at KYAML as an output format, which as a user you can always consider "correct"; versus KYAML as something that you might want to recommend in code style guidelines etc)

If a tool like Helm rendered to KYAML, we don't and I think won't have a conformance test that Helm needs to pass. Except, of course, that the YAML does have to be valid YAML.

[lmktfy]

I am happy to give this another LGTM unless it has substantial changes since I approved it.

[soltysh]

/label tide/merge-method-squash

[soltysh]

Two nits regarding the links, otherwise this lgtm from sig-cli pov

[rxinui]

@soltysh @lmktfy I have now applied all the fixes requested.

Please review or/and approve if everything is in order!

[soltysh]

/lgtm

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: lmktfy, soltysh

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:

• content/en/docs/OWNERS [lmktfy]

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

[lmktfy]

@rxinui I would like to merge this, but even as a stub, I think accepting it would not make the docs better. I am sorry that I need to cancel the LGTM on this PR but it just doesn't seem correct.

A stub reference page should not materially mislead readers, and this would. Someone looking for a KYAML reference who came across this page as drafted could well build a mental model of KYAML that ends up annoyingly wrong. The accuracy bar is high, I'm afraid (we are fine with incomplete, but we are going to insist on accurate).

You must, must read https://github.com/kubernetes/enhancements/blob/master/keps/sig-cli/5295-kyaml/README.md and make sure that you understand it enough to document the format.

If the KEP is wrong – which can happen – we need to point that out to reviewers. If the KEP is correct, what we document must materially match the KEP.

There are some places where the PR doesn't align with the documentation style guide, and I hope you'll fix those too, but if there were only some style issues, I would have approved the PR.

We can still fix it. I hope you will look at the KEP and at example KYAML outputs and at this draft document and work out which of those three is wrong. It does seem to me that at least one of them is.

/lgtm cancel
/retitle Add stub reference for KYAML

[rxinui]

You must, must read https://github.com/kubernetes/enhancements/blob/master/keps/sig-cli/5295-kyaml/README.md and make sure that you understand it enough to document the format.

@lmktfy give me more time to re-read and correct the kyaml example.

For my information, how would you approve whether or not the example given matches KYAML format (more than my current example?)

[lmktfy]

(I helped out a bit with the design of KYAML, so drawing on what I remember I can glance at an example and see if it looks right - but that probably won't help you).