kubernetes / kubernetes/website
feat: include kyaml for pages in k8s.io
- Dominant language
- HTML
- Stars
- 5.4k
- Forks
- 15.7k
- Avg merge
- 4d 18h
- Merged PRs (30d)
- 204
Description
Given [KYAML](https://www.kubernetes.dev/resources/keps/5295/) becomes stable in k8s 1.37, we'll like to include **some** examples of the k8s.io website to give users the possibility to display code examples in both KYAML and YAML.
We could start with pages like Pods, ConfigMaps, Secrets, Volumes, Services, and progressively have coverage of the rest of the website with upcoming releases.
### Goals:
- Have some examples by the release of 1.37
- Users could choose if they would like to see those examples in YAML and KYAML
- Automate the process so maintainers don't have to maintain code examples in two dialects manually
### Non-goals:
- Replace all YAML examples with KYAML
- Have all examples with both dialects by the release of 1.37
- Adding a third dialect (like JSON)
### Plan
Keeping the current examples (in YAML) under `content//examples`.
1. Create a script like `scripts/kyaml.sh generate` to render the YAML manifests as KYAML into a destination `content//examples-kyaml` using `yamlfmt -o kyaml` (noting this would not preserve comments).
2. Create a file named `data/kyaml_examples.yaml` which tracks which examples/manifests we would like to support for both dialects.
3. Have a guardrail on CI like `scripts/kyaml.sh verify` to catch when a contributor forgot to run the `kyaml generate` script and make sure the page when building for production is including the required manifests before build.
#### Limitations
- Snippets that embed a file in a block scalar (|, >) can't render on KYAML rendering with the implementation described before.
- We can't preserve comments from YAML manifests by rendering them using `yamlfmt -o kyaml`
Refs #56811.
Contributor guide
Research direction
Start with the YAML manifests under content//examples and inspect the proposed scripts/kyaml.sh generate and verify entry points, data/kyaml_examples.yaml, and the existing production build workflow. Use yamlfmt -o kyaml for selected examples such as Pods, ConfigMaps, Secrets, Volumes, and Services; done means generated files, tracking data, and CI verification include the supported examples without replacing YAML or breaking the production build.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- shell, yaml
- Domain
- build-system, ci-cd, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100