KYAML for Kubernetes: reducing manifest ambiguity without a rushed migration

Why this news matters

Kubernetes maintains the desired state of containerized applications across a group of machines. If container, Pod, node, or cluster is unfamiliar, start with “What is Kubernetes, where is it useful, and when is a simpler option better?”. This article covers a narrower subject: how Kubernetes manifests are represented.

In a manifest, a team describes which object should exist and how it should be configured. These files are often written in YAML. Indentation determines nesting, while a parser may interpret unquoted values as numbers or booleans. A file can therefore look correct to a person while a program reads a different structure.

KYAML narrows the permitted writing choices while remaining valid YAML. It makes structure and string values more explicit, but it does not change cluster behavior or correct a flawed configuration.

Output through kubectl -o kyaml appeared as alpha in Kubernetes 1.34 and became beta in 1.35. The official post confirms the beta stage starting with version 1.35. KYAML must still be selected explicitly with -o kyaml: it does not become the default output format or require teams to convert existing manifests.

How a program reads a manifest

A Kubernetes resource is an object managed by the system. The running example uses a ConfigMap, a resource for non-confidential configuration values. Its data field contains key-value pairs whose values must be text strings.

apiVersion: v1
kind: ConfigMap
metadata:
  name: demo-settings
data:
  FEATURE_ENABLED: "true"
  RETRY_LIMIT: "3"

The fields mean the following:

• apiVersion: v1 identifies the Kubernetes API version in which this resource type is defined;
• kind: ConfigMap names the resource type;
• metadata.name assigns the name demo-settings;
• data contains two configuration values.

First, a YAML parser turns the text into a general data structure. Kubernetes then checks that structure against the resource schema, including whether fields are known and values have permitted types.

A data type identifies whether a value is a string, number, boolean, list, or object. The quotes show that true and 3 are strings here. Without quotes, a parser may read them as a boolean and a number. Exact behavior depends on the YAML version and parser.

Indentation also carries meaning. Moving RETRY_LIMIT to the left may take it out of data and place it at another level. A different shift may make the file syntactically invalid. A linter can find some syntax and style problems, but it cannot determine the author’s intent by itself.

The same object in KYAML and JSON

KYAML uses flow style. Structures containing key-value pairs have explicit {} boundaries, while lists use []. String values are double-quoted. The official representation also includes an initial --- document marker and trailing commas.

---
{
  apiVersion: "v1",
  kind: "ConfigMap",
  metadata: {
    name: "demo-settings",
  },
  data: {
    # These values must remain strings.
    FEATURE_ENABLED: "true",
    RETRY_LIMIT: "3",
  },
}

This is valid YAML, not a separate language. A regular YAML parser can read it; no dedicated KYAML parser is required.

JSON also uses explicit brackets and quotes, but its keys must be quoted as well. Standard JSON does not permit comments or trailing commas.

{
  "apiVersion": "v1",
  "kind": "ConfigMap",
  "metadata": {
    "name": "demo-settings"
  },
  "data": {
    "FEATURE_ENABLED": "true",
    "RETRY_LIMIT": "3"
  }
}

The practical differences are:

• YAML is usually shorter and supports comments, but its structure depends on indentation and the types of unquoted values may be unclear.
• KYAML retains comments and YAML compatibility while making structures and strings explicit. The cost is a longer, less familiar representation.
• JSON also makes structure explicit and has broad tool support, but it does not permit comments or trailing commas.

A comment in hand-written KYAML is not part of the data structure. If an object is retrieved from a cluster with kubectl get, comments from the original manifest cannot be reconstructed because the Kubernetes API does not store them.

What is known about KYAML status

KYAML is developed through KEP 5295. A KEP, or Kubernetes Enhancement Proposal, records the motivation, boundaries, and technical design of a change.

In kubectl 1.34, the capability was alpha and required an opt-in. It moved to beta and became enabled by default in 1.35, although users must still select the output format with -o kyaml.

As of August 15, 2026, the official releases list names 1.36 as the latest released minor version and 1.37 as upcoming. Meanwhile, the KEP already shows STABLE, Implemented, and Latest v1.37. Those labels describe the implementation and target milestone for a future release; they do not prove that 1.37 is available to users. This article therefore reports beta as the confirmed stage starting with 1.35 and stable as the planned state for 1.37.

Future stabilization will not automatically make the format mandatory. An ordinary kubectl get does not print KYAML by default, and the KEP does not require projects to migrate. The format must be selected. For example, on a separate test cluster with a suitable client version, the syntax is:

kubectl get deployment my-app -o kyaml

This command is not part of the local lesson below because it contacts a cluster. A first learning exercise only needs a disposable local copy. Before adopting KYAML in a repository, separately check the actual editors, formatters, linters, and CI pipeline.

KYAML cannot correct an unknown field name, an unacceptable value, or flawed configuration logic. A syntactically valid file may fail the Kubernetes schema. Schema conformance also does not prove that a configuration implements the author’s intent.

One local experiment with an agent

Create a new disposable empty folder and save the first synthetic example there as demo-settings.yaml. Do not use a working repository, a real manifest, or private data. This step needs no kubectl, cluster, network, or credentials.

Prompt for the agent:

The new empty folder I specify contains only the synthetic demo-settings.yaml
from this article. Read only that file. Do not change the original. Create only
demo-settings.kyaml and notes.md beside it, preserving the same data. Do not run
commands or access other folders, the network, Git, kubectl, kubeconfig, or
secrets. Show the full diff. Stop if the path is ambiguous, the folder is not
empty, the data is not synthetic, or extra software would be required.

Expected result: the new file begins with ---, structures use flow-style {} boundaries, string values are quoted, and entries have trailing commas. apiVersion, kind, metadata.name, and the two pairs in data must remain unchanged.

Independent verification: do not accept the agent’s statement that the structures match as proof. Compare every key and value with the original yourself. If a trusted YAML parser already exists on the computer, compare the normalized structures separately. Do not install software only for this lesson. If data changed, a third file appeared, or access outside the folder was required, the experiment did not pass.

Should you use KYAML?

In a learning file, KYAML helps reveal object boundaries and string values. In a new repository, it is reasonable to test it on one manifest after checking the editor, formatter, linter, parser, kubectl version, and CI pipeline.

In an existing codebase, first establish whether the team actually encounters indentation mistakes or ambiguous types. If conventional YAML already follows a consistent style and passes reliable checks, a bulk conversion will create a large diff without guaranteed benefit.

The conclusion is simple: a local copy experiment is justified; an urgent migration is not. KYAML makes structure and strings more visible, but it does not replace schemas, tests, or human review. Decide only after checking the team’s actual tools. If the platform itself remains unclear, return to the Kubernetes foundation article before evaluating its manifest format.

Sources

• Kubernetes Blog: How to Pretty-Print Your Kubernetes YAML as KYAML and Why You’d Want To
• Kubernetes Enhancement Proposal 5295
• Kubernetes: Releases