KYAML

Table of Contents

Today I learned, in Kubernetes v1.34, kubectl will also support a new strict subset of YAML called KYAML.

Resources

Shell Script

I coded a simple script to convert all Kubernetes manifests in a directory from YAML to KYAML.

Initially, I wanted to code my own converter, but then found out that the upstream Kubernetes project already has a new yamlfmt tool (different from google/yamlfmt).

#!/bin/sh
# kyamlify.sh — Rename *.yaml -> *.kyaml then format to KYAML (POSIX)
# Usage: ./kyamlify.sh [ROOT_DIR]
# Env: YAMLFMT_VERSION (default: master)

set -eu

ROOT_DIR="${1:-kubernetes}"
YAMLFMT_VERSION="${YAMLFMT_VERSION:-master}"

# Require Go
command -v go >/dev/null 2>&1 || { echo "error: Go not found in PATH" >&2; exit 1; }

echo "→ Installing yamlfmt @ $YAMLFMT_VERSION"
go install "sigs.k8s.io/yaml/yamlfmt@${YAMLFMT_VERSION}"


echo "→ Formatting all YAML files under ${ROOT_DIR} as KYAML"
find "${ROOT_DIR}" -type f -name '*.yaml' -print0 \
  | xargs -0 -n1 "$(go env GOPATH)/bin/yamlfmt" -o kyaml -w

KYAML Rules

Quote

KEP-5295 introduces KYAML, which tries to address the most significant problems by:

Always double-quoting value strings
Leaving keys unquoted unless they are potentially ambiguous
Always using {} for mappings (associative arrays)
Always using [] for lists

Support for KYAML: a Kubernetes dialect of YAML | Kubernetes v1.34 Sneak Peek | Kubernetes

These rules are similar in practice to JSON5. However, while JSON5 is a superset of JSON (as well as a subset of ES5), KYAML is a subset of YAML.

In fact, I suspect that by adding --- to the first line of a JSON5 file, it would be valid KYAML.

By the way, starting the file with --- is required for KYAML (while it’s optional in YAML).

Experimentation and Additional Observations

I was initially excited about converting all my Kubernetes manifests to the “safer” KYAML format.
I ran my script then followed it by running yamllint, which introduced a few warnings post-conversion.
After fixing all yamllint warnings, I had well-formatted KYAML files.
I considered whether to rename all converted manifest files to use a *.kyaml suffix. I decided against this since I couldn’t find any evidence of this file extension.
KYAML files are 100% valid YAML files, and work with existing tooling. This includes existing Kubernetes versions and tooling.
The main thing introduced with Kubernetes v1.34 is a kubectl get -o kyaml option.
Keeping the *.yaml file extension makes sense since KYAML is still valid YAML and existing tools expect *.yaml or *.yml file extensions, not *.kyaml
After running the script, fixing formatting, and deciding to keep the filenames the same, I could add all modified files in homelab-as-code to a new kyaml branch and make a commit.
I considered opening a Pull Request, however, am still undecided.
My main consideration is whether the KYAML format would impact usability, making it harder for me to write and edit manifests.
I am not sure whether KYAML solves any real problems for me.
I understand YAML limitations but know how to avoid them by quoting values when needed, using linting and formatting tools (manually, with pre-commitand in CI).

My Opinion on the Format

In a way, KYAML is itself “yet another markup language” (despite using existing YAML rules). It is far from the first solution to problems with existing markup languages.

One notable limitation of standarad JSON is no comments. Both JSON5 and Microsoft’s JSONC (JSON with comments, primarily used in VS Code’s setttings.json file) previously addressed this. KYAML has the benefit of being a subset of YAML and designed to work with all existing YAML tooling.

In theory, KYAML could be a “safer” way to write production-grade manifests. However, this was already possible to do with JSON files. Kubernetes manifests can all be written in JSON, but there is a reason that this is rarely done in practice.

JSON files are arguably less readable and harder to work with (for humans, not machines) than YAML. At the same time, JSON files are very much machine-parsable with a lot of existing tooling like jq (though YAML tooling exists as well).

In imitating JSON but staying YAML, KYAML can feel like the worst of both, rather than the best of both world. Not as clean as JSON, and not as “human-readable” as YAML.

Featured image by Marvin Meyer on Unsplash.