What is KYAML? KEP-5295 Reading Notes

While carrying out some routine Release Signal tasks recently, I stumbled upon a PR titled KYAML. Is the Kubernetes community trying to create another YAML standard? Or is there something special about it?

This article is in English. For the Traditional Chinese version, please click here.
本篇文章為英文版本，繁體中文版本請點擊這裡。

Today, let’s take a look at KEP-5295: Introducing KYAML, a safer, less ambiguous YAML subset / encoding!

This post was written on July 31, 2025, and is based on this specific commit.

Why was this KEP proposed?

Anyone who has actually worked with Kubernetes—whether you’re in a DevOps or SRE role—has probably been jokingly called a YAML engineer at some point.

Beyond understanding core concepts like Pods, Deployments, and Nodes, one thing you’re guaranteed to deal with is YAML (YAML Ain’t a Markup Language).

While YAML is widely used for writing these configuration files, it turns out that its original design has some flaws.

So, what exactly is wrong with YAML?

One of the most well-known issues in YAML is The Norway Problem. You can try out the following examples on the Online YAML Parser.

countries:
- GB
- IE
- FR
- DE

This YAML converts to JSON like this:

{"countries": ["GB", "IE", "FR", "DE"]}

Looks fine so far. Now let’s add Norway:

countries:
- GB
- IE
- FR
- DE
- NO

Logically, the resulting JSON should look like:

{"countries": ["GB", "IE", "FR", "DE", "NO"]}

But in reality, it becomes:

{"countries": ["GB", "IE", "FR", "DE", false]}

At this point, you’re probably making this face:

As explained in the YAML 1.1 specification:

YAML allows scalar content to be presented in several formats. For example, the boolean “true” might also be written as “yes”.

In other words, this isn’t a bug—it’s a feature. Something like Yes, which seems like a string, is interpreted as a boolean true.

YAML 1.2 later removed these rules, but here’s the catch: version 1.2.0 was published on July 21, 2009. At the time of writing (2025), tools like Online YAML Parser still convert NO into false, which shows how uneven support still is across different YAML parsers.

These kinds of implicit conversions are common. Take this example:

- just: 4_________2__
- yaml: 11:00

When converted to JSON, you get:

[
  {
    "just": 42
  }, 
  {
    "yaml": 660
  }
]

4_________2__ is interpreted as a number, and 11:00 is also parsed as a number (in base-60). While double quotes are optional for strings, they can be crucial in certain situations.

What about alternatives? JSON should work, right?

Anyone who has written an operator knows that Kubernetes definitely supports JSON. However, JSON has a major drawback: it doesn’t support comments.

For machine-to-machine data exchange, this usually isn’t a big deal. But when it comes to user-facing configuration, the inability to add comments significantly hurts maintainability.

On top of that, many tools (e.g., Helm) are built around YAML. So instead of switching everything to JSON, it makes more sense to focus on making YAML stricter and safer.

That’s why some developers came up with the idea of KYAML!

Goals and Non-Goals of KYAML

At first glance, it might seem like KYAML aims to overhaul everything and establish a brand-new standard. That’s partially true—but also not quite.

Let’s first take a look at the original list of goals:

1. Specify a YAML dialect which is 100% compatible with existing parsers and tooling.
2. Provide libraries and tooling for encoding and converting to this formatting, with stable (idempotent) conversion.
3. Provide a KYAML output format for kubectl.
4. Update examples and documentation throughout the project.
5. Address common YAML pitfalls through an opinionated formatting approach.
6. Document the design and reasons for KYAML and the 100% compatibility with tooling expecting arbitrary YAML.

And here’s the original list of non-goals:

1. Introduce alternative configuration languages that are not compatible with existing tooling.
2. Server-side support for KYAML distinct from what we support in YAML already.
3. Require projects to migrate to KYAML by default.
4. Change the YAML library used by Kubernetes.

Let’s start with what’s true, beginning with the fifth goal:

Address common YAML pitfalls through an opinionated formatting approach.

The idea is to address common YAML issues through an opinionated formatting approach. For example, the Norway Problem mentioned earlier, where NO, which should be a string, is implicitly converted to the boolean false.

As for what’s not quite right, you can still see it in the first and sixth goals:

Specify a YAML dialect which is 100% compatible with existing parsers and tooling.
Document the design and reasons for KYAML and the 100% compatibility with tooling expecting arbitrary YAML.

KYAML must be 100% compatible with designated or existing YAML parsers and tools. Technically, KYAML does not replace YAML nor establish a new standard. You can find related explanations later in the Drawbacks section:

Yet another standard. Rebuttal: KYAML is YAML and users can provide vanilla YAML anywhere that can accept KYAML.

Besides that, it’s not just about the output format. See the second and fourth goals:

Provide libraries and tooling for encoding and converting to this formatting, with stable (idempotent) conversion.
Update examples and documentation throughout the project.

KYAML will provide conversion libraries and tools, and it will also convert existing YAML examples in documentation into KYAML.

Next, let’s look at the Non-Goals section—it’s quite interesting. Check out points two and four:

Server-side support for KYAML distinct from what we support in YAML already.
Change the YAML library used by Kubernetes.

Wait a minute—if KYAML is supposed to be used, why does it say server-side support won’t be provided? And why won’t Kubernetes’ existing YAML libraries be changed?

When I first read this, it felt really contradictory. But after some reflection, it makes sense: server-side doesn’t need to support it. Going back to the first and sixth goals, KYAML must be compatible with designated or existing YAML parsers and tools, so there’s no need to write a special parser for server-side.

Now that we understand the motivation, let’s dive into the actual proposal and design!

Proposal

Here is the original text on how the KEP proposes to solve YAML issues:

1. Always double-quoting value strings (no ambiguity around things like “NO”).
2. Unquoted keys, unless they are not obviously “safe” (e.g. “no” would always be quoted).
3. Always using {} for structs and maps (no more obscure errors about mapping values).
4. Always using [] for lists (no more trying to figure out if a dash changes the meaning).

All strings are always enclosed in double quotes. Keys in key-value pairs generally do not have quotes (unless they are clearly unsafe, like no). Use {} to represent all structs and maps, and [] to represent all lists.

Combining these ideas, KYAML is not whitespace-sensitive. These formats return to flow style rather than the commonly used block style in YAML.

At this point, you might think: “Isn’t this just JSON?” Congratulations, yes it is! The differences from JSON are:

1. Allows comments (when authored by users).
2. Allows trailing commas on the last item in a list or struct/map.
3. Does not require quoted keys.

You can write comments, add trailing commas in maps or structs, and you don’t need to quote every key.

If every struct or map must have {}, here comes the problem—see the following:

{
    # this is the deck service
    "apiVersion": "v1",
    "kind": "Service",
    "metadata": {
        "name": "deck",
        "namespace": "default",
    },
    "spec": {
        "selector": {
            "app": "deck",
        },
        "ports": [
            {
                "port": 80,
                "targetPort": 8080,
            },
        ],
        "type": "NodePort",
    },
}

These are invalid JSON because JSON does not allow comments, but they are valid YAML.

KYAML starts structs with {}, just like JSON. So, how do you tell whether the content is YAML or JSON?

To solve this, KYAML requires the document to start with a separator (---). This simultaneously resolves ambiguity between KYAML and JSON and separates ill-formed JSON.

Once {} and [] are introduced, debates arise (e.g., whether to put brackets on new lines or inline). According to the KEP, the preference is to write them inline to save vertical space. Here’s the original text:

KYAML also tries to economize on vertical space by “cuddling” some kinds of brackets together.

The design concepts have been covered up to this point. Due to the length of the article, those interested in the design details can refer directly to the KEP for further reading.

In short, the final output will look something like this when running kubectl get -o kyaml svc hostnames:

---
{
  apiVersion: "v1",
  kind: "Service",
  metadata: {
    creationTimestamp: "2025-05-09T21:14:40Z",
    labels: {
      app: "hostnames",
    },
    name: "hostnames",
    namespace: "default",
    resourceVersion: "37697",
    uid: "7aad616c-1686-4231-b32e-5ec68a738bba",
  },
  spec: {
    clusterIP: "10.0.162.160",
    clusterIPs: [
      "10.0.162.160",
    ],
    internalTrafficPolicy: "Cluster",
    ipFamilies: [
      "IPv4",
    ],
    ipFamilyPolicy: "SingleStack",
    ports: [{
      port: 80,
      protocol: "TCP",
      targetPort: 9376,
    }],
    selector: {
      app: "hostnames",
    },
    sessionAffinity: "None",
    type: "ClusterIP",
  },
  status: {
    loadBalancer: {},
  },
}

How to Use

The feature gate isn’t very practical for users on the CLI kubectl side, but a similar approach is the environment variable KUBECTL_KYAML. This is actually quite similar to how kuberc works.

In the Alpha stage, you need to set the environment variable KUBECTL_KYAML to true. According to tracking, this will appear in version 1.34.

In the Beta stage, it will be enabled by default unless you explicitly set KUBECTL_KYAML to false.

In the GA stage, the KUBECTL_KYAML variable will be ignored, and KYAML can be used freely.

Once the stage is confirmed, you can run commands like kubectl get -o kyaml ... — yep, just add a “k” inside -o yaml. That’s how simple it is!

Summary

In one sentence: “KYAML is YAML, but not all YAML is KYAML.”

Personally, I think YAML is like JavaScript—weakly typed and causing all sorts of quirks (e.g., 9 + "1" => "91" or 91 - "1" = 9). KYAML is more like TypeScript, providing strong typing to fix JavaScript’s flaws. The difference is KYAML’s output still complies with the YAML specification.

If no major issues arise, I’m optimistic about this improvement. It removes much of YAML’s ambiguity, fixes JSON’s lack of comments, separates ill-formed JSON, and doesn’t require changes to the existing Kubernetes API Server libraries.

It’s a win-win situation, and I look forward to other projects hurt by YAML to follow suit and eliminate YAML’s latent problems.

This is my first serious read of a KEP and recording my thought process in an article. If you like this kind of content, please hit reactions or leave your thoughts.

Afterword

Recently, someone on Medium claimed to have access to a “Kubernetes 2.0 secret internal test,” which some people then shared on social media, saying Kubernetes 2.0 is coming soon, certain features will be removed, and that there’s no need to learn Helm or Argo anymore.

At CNTUG, I often encourage everyone that using open source software takes effort, and it’s best to participate in the community to avoid being misled by rumors or false information.

At KubeCon talks, SIG members always share new features and release roadmaps. For major version changes like this, all SIGs are expected to follow along. As of mid-2025, the current version is 1.34, and SIG Storage’s roadmap already extends to 1.39—so it’s safe to say a major version update isn’t likely within the next two years.

Moreover, in Kubernetes Slack discussions, nobody is really talking about a 2.0 timeline. If a 2.0 were really coming, submitting KEPs to change the architecture would be a much more realistic approach.

Reference

• KEP-5295: Introducing KYAML, a safer, less ambiguous YAML subset / encoding