kubernetes / kubernetes/website

feat: include kyaml for pages in k8s.io

Open
#57,030 7 comments 0 reactions 0 assignees View on GitHub
language/en needs-triage sig/architecture sig/docs
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.