Kubernetes KYAML: A Safer YAML Output Format

Kubernetes KYAML makes manifests more explicit with braces, brackets, quoted values, and comments. Learn when to use it and where conversion can surprise you.

Kubernetes manifests are usually written in block-style YAML because indentation keeps a Deployment or Service compact. That compactness has a cost: one indentation change can alter the object while leaving the file syntactically valid. Unquoted values can also be interpreted as booleans or numbers by some YAML processors. The Kubernetes project’s new KYAML output format narrows the choices without asking the API server to learn a new language.

The change is timely. The official Kubernetes KYAML reference describes KYAML as a safer, less ambiguous YAML subset. The project’s recent announcement frames it as a formatting habit rather than a migration: ordinary block YAML still works, and KYAML is a choice for output and review.

What KYAML changes

KYAML uses YAML flow style for the structure that matters most in a Kubernetes object. Maps use {}, lists use [], and value strings are double-quoted. A generated object therefore makes its boundaries visible instead of asking the reader to count indentation. Comments remain allowed, and a trailing comma can make a one-line edit easier to spot in a diff. These rules are described in the KYAML reference and the KYAML enhancement proposal.

Here is the same small Pod in conventional block YAML:

apiVersion: v1
kind: Pod
metadata:
  name: api
  labels:
    app: api
spec:
  containers:
    - name: api
      image: example/api:1.4
      ports:
        - containerPort: 8080

KYAML makes the collection boundaries explicit:

---
{
  apiVersion: "v1",
  kind: "Pod",
  metadata: {
    name: "api",
    labels: {
      app: "api",
    },
  },
  spec: {
    containers: [{
      name: "api",
      image: "example/api:1.4",
      ports: [{
        containerPort: 8080,
      }],
    }],
  },
}

The --- header is still YAML’s document separator. The KEP says it helps distinguish KYAML from JSON because both begin with an opening brace; Kubernetes 1.33 and later can handle KYAML without that header, but the header is part of the normal rendering convention. KYAML is not JSON with a relaxed parser: it is YAML with a deliberately small set of output rules.

Why explicit structure helps during review

Indentation is no longer the only signal

In block YAML, the containers list and the metadata map are shaped by indentation. A misplaced two-space shift can move a key under the wrong parent. The KYAML KEP calls out this problem, including the extra risk created when a template engine emits whitespace outside the main YAML context.

KYAML does not make a bad object valid. It makes the nesting visible enough that a reviewer can see whether ports belongs to the container and whether labels belongs to metadata. That is useful in generated output, pull requests, and incident-time comparisons. It is not permission to skip schema validation.

Strings stop looking like other types

YAML processors have historically disagreed about which unquoted scalars should become booleans, numbers, dates, or strings. The KEP uses values such as NO, YES, and 11:00 to illustrate why optional quoting can be surprising. KYAML always double-quotes value strings, so a value intended as text stays visually distinct from true, false, null, and numeric values.

The rule also clarifies the boundary with JSON. RFC 8259 defines JSON values as strings, numbers, booleans, null, objects, and arrays; object names are strings. KYAML keeps that explicit object-and-array shape but permits comments, trailing commas, and unquoted keys when a key is clearly a string. JSON remains a valid data-interchange format; KYAML is a more comfortable configuration rendering for Kubernetes objects.

Comments can stay with the object

JSON’s grammar has no comments, while KYAML permits them. That matters when a manifest contains a short operational explanation, such as why a probe delay is longer than the image’s normal startup time. The Kubernetes object model documentation still defines the meaning of the object through fields such as apiVersion, kind, metadata, and spec; comments do not change the desired state sent to the API.

Use comments for intent, not for a second configuration system. If the comment is the only place that records a dependency or an exception, put that information in the repository documentation or an annotation as well. A formatter can preserve many comments, but no formatter can make an undocumented ownership decision durable.

KYAML is a client-side representation, not a new API

Kubernetes still processes object requests as JSON. The Kubernetes object documentation explains the path: you write YAML or JSON, kubectl converts the information to JSON or another supported serialization, and the API request carries JSON over HTTP. KYAML does not change the API server, object schema, or reconciliation behavior.

That distinction makes adoption low-risk. The kubectl apply reference accepts JSON and YAML input, including KYAML because KYAML is valid YAML. The same reference lists kyaml as an output option:

kubectl get deployment/api -o kyaml
kubectl get deployment/api -o kyaml > api.yaml

The exact availability depends on the Kubernetes client and feature state. KYAML was introduced as alpha in Kubernetes 1.34 and enabled by default as beta in 1.35, while the explicit -o kyaml output option remains the important switch. Check the versioned KYAML guidance before standardizing a command in a shared script.

The output is suitable for a human-readable snapshot, but do not make a byte-for-byte contract around it. The KEP says rendering details may change, map ordering is not guaranteed, and automation should wait until clients are known to support the format. If a parser needs stable machine input, use JSON or a documented API response rather than matching lines in formatted output.

Anchors, aliases, and data that cannot survive conversion

YAML has features that do not map cleanly to a Kubernetes API object. The YAML 1.2.2 specification defines an anchor with & and an alias with *; an alias refers to a preceding anchored node. Those are serialization features, not Kubernetes fields. Once a YAML processor composes the representation into a native object, the anchor name does not carry application meaning.

KYAML may therefore simplify anchors and aliases while preserving the resulting object value. The KYAML KEP permits aliases to be reified during rendering when the unmarshaled object is unchanged. In plain language: the output may repeat the data instead of preserving the author’s anchor spelling.

That has a practical consequence for Helm and other renderers. The Helm YAML techniques guide warns that an anchor is expanded the first time YAML is consumed and can be discarded when Helm or Kubernetes reads and rewrites the file. Use anchors to reduce repetition inside a controlled input file, but do not use them as a durable inheritance mechanism across tools. For reusable Kubernetes configuration, prefer a chart value, a Kustomize overlay, or a generated file whose fully rendered output is reviewed.

Do not assume that every valid YAML document can be rendered as KYAML. The KEP notes that complex keys, explicit tags, global tags, anchors, and aliases may be simplified or may fail conversion when their meaning cannot be represented through the JSON-shaped Kubernetes object. That is another reason to treat KYAML as a useful output and review format rather than the canonical source for every YAML feature.

A six-minute KYAML workflow

Use this workflow when you want clearer output without changing how a resource is applied.

1. Check the client version. Run kubectl version --client and read the KYAML status table for that client line. Do not assume the cluster version and client version have the same feature state.
2. Preview the object. Run kubectl get deployment/api -o kyaml and inspect the output. Look for explicit string values, collection boundaries, and comments that need to be carried into repository documentation.
3. Compare before applying. Run kubectl diff -f ./k8s/ before kubectl apply -f ./k8s/. Kubernetes’ declarative configuration guide documents this diff-then-apply workflow and explains how kubectl apply compares the file, the live object, and the last-applied annotation.
4. Validate the object. Keep schema validation enabled. The kubectl apply reference documents --validate=strict, warn, and ignore; default to strict unless a migration requires a written exception.
5. Commit the source, not a mystery snapshot. If KYAML is generated from a chart or overlay, record the generator and version beside the output. A reviewer should be able to reproduce the file instead of wondering whether a formatting change also changed values.
6. Use the smallest format that communicates intent. Keep block YAML for hand-authored files where indentation is easier to scan. Prefer KYAML for generated snapshots, formatter output, and reviews where explicit braces and quoted values expose the object shape.

For a quick local conversion, pair the workflow with the YAML ↔ JSON converter. It is useful for checking the data shape, but it is not a Kubernetes schema validator and cannot tell you whether a field is legal for a particular API version.

YAML, JSON, or KYAML?

The format choice should follow the boundary. Kubernetes’ API remains JSON-shaped, but repository authors need comments and reviewable configuration. KYAML sits between those needs: it keeps YAML compatibility while reducing the number of formatting choices that can surprise a reader.

FAQ

Read next

• Try the YAML ↔ JSON converter.
• Read The YAML + JSON config reference.
• Review the kubectl cheatsheet.
• For startup and probe behavior, see Kubernetes readiness probe debugging.

Tags: #kubernetes, #kyaml, #yaml, #json, #configuration