KYAML in Practice: Explicit Kubernetes Manifests Without a Migration

Aug 17 · 7min

By

kubernetescloud infrastructureplatform engineering

Kubernetes manifests are data structures disguised as indentation. Most of the time that is convenient. During a large review, however, indentation makes it surprisingly hard to answer basic questions: where does this mapping end, which list owns this item, and did a formatter change structure or only whitespace?

KYAML is an alternative presentation of the same data. It makes structure explicit with braces, brackets, quoted strings, and trailing commas. Crucially, it is not a new Kubernetes API or serialization format. Every valid KYAML document is valid YAML, so existing Kubernetes versions and YAML-aware tooling can consume it without a migration.

The feature is best understood as a formatting decision with operational consequences—not a new configuration language.

What changes

A conventional manifest relies on indentation:

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

The KYAML representation makes the containers explicit. A simplified example looks like this:

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

The values and hierarchy are unchanged. The additional punctuation carries structural information that block-style YAML leaves to whitespace. That can reduce ambiguity when humans review deeply nested manifests or when generated files produce noisy diffs.

Generate KYAML with kubectl

Kubernetes added KYAML as a native kubectl output format in version 1.34. The initial release was alpha and opt-in:

export KUBECTL_KYAML=true
kubectl get deployment my-app -o kyaml

In Kubernetes 1.35 and later, the beta feature is enabled by default, but the output still must be requested:

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

There are currently no plans to make KYAML the universal default. From Kubernetes 1.36, teams that prefer it can configure get output through kuberc:

kubectl kuberc set --section defaults --command get --option output=kyaml

Version details matter here. A repository that supports several kubectl versions should not assume that every contributor has native -o kyaml support.

Format files outside the cluster

KYAML does not require a live API server. The sigs.k8s.io/yaml project includes a formatter that reads a file or directory and writes KYAML to standard output:

go install sigs.k8s.io/yaml/yamlfmt@latest
yamlfmt -o=kyaml deployment.yaml > deployment.kyaml
yamlfmt -o=kyaml -d deployment.yaml

The diff mode is useful in CI because it can show formatting drift without silently changing the working tree.

Google’s yamlfmt also provides a KYAML formatter. A repository can declare the format once:

formatter:
  type: kyaml

Then preview or apply it consistently:

yamlfmt -dry ./k8s/
yamlfmt ./k8s/

Pick one formatter and pin its version. Two tools that target the same style can still differ at edge cases or evolve at different times; a floating formatter version turns formatting into an uncontrolled build input.

A production adoption pattern

Treat KYAML adoption like any other repository-wide formatting change:

  1. Choose a formatter and pin the exact version.
  2. Convert manifests in a dedicated commit with no semantic edits.
  3. Compare parsed objects before and after conversion, not only text.
  4. Add a CI check so later pull requests cannot mix styles accidentally.
  5. Document how developers reproduce the check locally.

For the semantic comparison, parse both versions and compare normalized JSON. This catches a formatter or conversion mistake that a visual review might miss. Continue running your normal server-side or client-side Kubernetes validation as well; formatting does not validate resource schemas, admission policy, or cluster compatibility.

Tradeoffs

KYAML adds punctuation. Small manifests can feel heavier, and engineers already fluent in block YAML may find it less pleasant to write by hand. It also does not remove Kubernetes’ real sources of configuration complexity: schema evolution, defaulting, controllers, admission, and environment-specific overlays.

Its value appears when explicit structure matters more than minimal syntax—large generated manifests, code review, machine-authored configuration, and repositories where inconsistent YAML styles produce recurring churn.

Do not present KYAML as a correctness boundary. A perfectly formatted manifest can still request the wrong image, omit a resource limit, or fail policy. KYAML makes the document’s shape easier to inspect; it does not prove that the desired state is correct.

Conclusion

KYAML is a low-risk experiment because it preserves YAML compatibility. Start with generated output or one manifest directory, measure whether reviews and diffs become clearer, and keep it only if the explicit syntax earns its extra visual weight.

The useful first-principles question is not “is KYAML better than YAML?” It is “does making structure explicit reduce mistakes in this repository?”

References

>