Cognitive load is the new downtime

Exposing raw YAML to developers is not a platform. It's technical documentation masquerading as a product.

There's a pattern that keeps repeating in Platform Engineering. We build something powerful, slashing a "platform" sticker on top of it, and then hand it to developers with the assumption that power is enough.

We wrap it with some "golden path" (not the one from Leto the Second from the Dune saga) documentation — maybe a portal, maybe a few Terraform modules — and expect teams to run with it.

The truth, widely acknowledged, is the following:

Exposing Kubernetes through YAML isn't abstraction. It's delegation without responsibility.

Developers don't need more tools. They need interfaces. And those interfaces should be APIs, not configuration dialects with a thousand footnotes.

I already spoke about interfaces through the Cluster API and ClusterClass concept in the previous The Platform Brief issue: here's the link.

Yes, kubectl is still an API client. And yes, Kubernetes has a beautifully designed API server. But the moment your internal platform is defined by copy-pasting YAML into Git repos — you've lost the plot.

The elephant in the room: the Cognitive Load

Not complexity — cognitive load.

Complexity is inherent. Distributed systems are hard. But cognitive load is how much mental effort we demand from someone just to operate within the system.

I already shared how Cluster API concepts created a huge barrier also to me, you can imagine what could happen with your developers when dealing with complicated interfaces.

And when your “developer experience” requires understanding Kubernetes concepts like:

• probes vs policies vs roles vs bindings
• the impact of every field in a Deployment spec
• what dnsPolicy=ClusterFirst actually means

...then what you've built isn't a platform: it's a crash course in Kubernetes internals — with your developers as unwilling students.

I've seen things you Platform Engineers wouldn't believe. Delusional developers unwill to learn Kubernetes (cit.)

Congratulations, you just shipped a "non" product, rather, a burden.

The Fallacy of "Let's Just Document It"

This is the classic trap.

You build a YAML-heavy workflow, realise nobody understands it: how to solve that?

Just write the docs.

But documenting complexity isn't the same as reducing it.

It's like writing:

“To increase the volume, press the Increase Volume button.”

That's not a product interface — that's an instruction manual for a broken one. You can also witness this in the Open Source world: code is easy, documentation is always the Achilles' Heel.

True platforms don't need explanations for every field. They reduce the number of decisions, hide internal mechanics, and create opinionated contracts developers can trust without having to learn the plumbing.

The Docker Lesson

This is a bold opinion, I had to argue several times throughout these years: Docker win the container battle for developers, sorry Podman and other players.

Docker didn't win because it invented containers: they were there since (maybe) SolarisOS. It won because it made containers usable.

Most developers couldn't explain cgroups, namespaces, or overlay filesystems — and they didn’t need to. Docker abstracted them away through a simple UX and CLI (such as APIs).

You could package an app without knowing what was under the hood. It wasn't just a wrapper — it was a mental offload.

Have we done the same with Kubernetes? Not at all, instead, we've wrapped it with more YAML.

Kubernetes made Distributed Systems possible — but also fragile

Kubernetes introduced powerful building blocks for distributed infrastructure:

• declarative state
• continuous reconciliation
• failure recovery
• service discovery
• configuration scoping
• pick you preferred ones missing from this list

But it didn't build an interface for humans. That part was left to "us" — the platform teams. And in many cases, we’ve failed to meet that responsibility.

We hand devs a Helm chart and call it self-service. We tell them to own their deployments while giving them a thousand-line CRD to copy. We build multi-tenant clusters and pretend Namespace + RBAC is a product boundary.

This isn't DevEx. This is a defence mechanism disguised as empowerment.

I'm still convinced Kubernetes is a powerful framework to build complex systems: in both aspects. Complex for what they achieve, and complex to consume, unfortunately: this is the goal of this The Platform Brief issue.

Infrastructure is NOT a product until it acts like one

Infrastructure is not a product just because it exists. It becomes a product when it delivers concrete value, when it abstracts implementation details, and when it provides interfaces, not instruction manuals.

If you're exposing infrastructure without:

• contract versioning
• sensible defaults
• safety nets
• discoverable APIs
• limited surface area

...then you're not building a platform. You're throwing complexity over the wall and branding it.

And if your "platform" is just kubectl with CI, then what you've really done is push operational pain downstream — to the very teams you promised to empower.

What real platforms do

Real platforms abstract, not expose.

They remove decisions, not multiply them. They provide APIs, not file formats. They don't require developers to learn how the system works — unless they want to go deeper.

And when they drift, they reconcile — not with a ticket, but automatically.

They behave like systems that are designed, not simply wired together.

Developers are expected to deploy applications easily, without installing CRDs, architecting logs retrieval, or designing Service Mesh.

Developers are your restaurant customers: they're not expected to serve the meal or cook it.

Closing thought

Your developers don't want Kubernetes, and it's legit. They want what Kubernetes enables: velocity, scale, resilience.

But they want it through an interface that respects their time, not a spec that assumes their expertise.

If your platform increases cognitive load, it doesn't matter how well it's documented or how powerful it is. It will eventually become unusable — not because of downtime, but because of human drag.

And in the end, that’s what kills platforms. Not failure. Not complexity.

Just exhaustion.