Embracing KYAML: The Evolved Approach to Kubernetes YAML Configuration

YAML has established itself as the primary format for Kubernetes manifests, underpinning countless tutorials and configuration files. While not inherently flawed, standard YAML's extensive features can lead to confusion and inefficiencies, particularly when applied to Kubernetes. Given that Kubernetes only requires a subset of YAML's capabilities, the SIG CLI initiative has introduced KYAML, a refined approach that maintains YAML's inherent strengths while reducing potential pitfalls.

Understanding KYAML

KYAML is essentially a specific dialect of YAML, tailored for Kubernetes use, ensuring seamless compatibility with existing ecosystem tools, as outlined in KEP 5295. Rather than introducing an entirely new syntax, KYAML limits the variations allowed in standard YAML, promoting uniformity in syntax and style. Thus, every valid KYAML remains valid YAML, but with a focus on consistent formatting.

How KYAML Addresses Common YAML Challenges

Standard YAML can be tricky due to:

• Whitespace Sensitivity: YAML's reliance on indentation can lead to subtle errors. An incorrectly indented line might still be syntactically correct yet create unexpected outcomes, particularly problematic in templating scenarios like Helm.
• Silent Type Coercion: With YAML allowing optional string quoting, values that appear as strings can inadvertently be interpreted as other types. A notable example is the infamous "Norway Bug," where NO is treated as a boolean false instead of the string.
• JSON Limitations: Transitioning to JSON presents its own issues, such as restricted comment support and the necessity for strict formatting rules.

KYAML overcomes these by embracing explicit structuring and typing:

• It does not rely on whitespace for data structure
• All strings are enclosed in quotes, eliminating silent type coercion
• Mapping is consistently encased in braces {}
• Lists are uniformly represented by brackets []
• Comments and trailing commas are permitted, unlike in JSON
• An explicit --- header differentiates it from JSON where both structures may start with {

This style is often referred to as flow style, presenting a clearer alternative to the typical block style that most users encounter.

A Practical Comparison: Standard YAML vs KYAML

Consider a simple Pod manifest in both formats:

Standard YAML

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  labels:
    app: demo
spec:
  containers:
    - name: nginx
      image: nginx:1.20

KYAML Format

---
{apiVersion: "v1", kind: "Pod", metadata: {name: "my-pod", labels: {app: "demo"}}, spec: {containers: [{name: "nginx", image: "nginx:1.20"}]}}

The distinction is clear in how every aspect of the structure is made explicit in KYAML, promoting readability and reducing potential errors associated with indentation and implicit typing.

Generating KYAML Output

There are various methods to generate KYAML formatted output:

Option 1: kubectl -o kyaml

Kubernetes version 1.34 introduced KYAML as a native output format:

kubectl get deployment my-app -o kyaml > my-app.yaml

Note that although it’s not set as the default format, users can configure their preference via the kuberc command.

Option 2: Kubernetes' yamlfmt

The sigs.k8s.io/yaml repository includes the yamlfmt utility for converting files to KYAML:

go install sigs.k8s.io/yaml/yamlfmt@latest

Running yamlfmt on a file outputs the KYAML to the standard output, allowing for redirected saving.

Option 3: Google's yamlfmt

Google's yamlfmt also supports KYAML conversion. You can install it via Go or download a binary from its releases page:

go install github.com/google/yamlfmt/cmd/yamlfmt@latest

This tool facilitates both directory conversions and pre-commit hooks, making integration into CI pipelines straightforward.

Is Adopting KYAML Beneficial?

The question of whether to adopt KYAML boils down to consistency and reducing error-proneness in your YAML configurations. Any file that complies with KYAML remains valid YAML, ensuring compatibility with existing tools and workflows. While existing block-style YAML will continue to function, switching to KYAML promotes clearer, more maintainable configurations across teams and projects.

Ultimately, embracing KYAML serves as more of a shift in best practices rather than a technical migration; it's about cultivating better habits in managing Kubernetes manifests.