Skip to main content

Your Kubernetes Install Doesn't Have a Finish Line — And More Docs Won't Give It One

9 min readDora NodaDora Noda
Share
On this page

A vendor selling a self-hosted AI platform doesn't lose deals to a competitor. It loses weeks of its own solutions-engineering team's time to a Helm chart that "should just work." Fairwinds, which runs enterprise Kubernetes installs for a living, described the pattern in July 2026: what looks like a deployment turns into a string of ad hoc, three-hour debugging calls that stretch across days, sometimes weeks, with no clean way to predict when — or whether — the install finishes.

The instinct is to blame the chart. Write better docs, add a preflight checklist, ship a Terraform module, staff a bigger support team. Vendors have tried all four, and installs still stall. That's the tell: this isn't a documentation problem. It's a structural one. A Helm chart installs into a cluster someone else already built, configured, and quietly modified over the years. The chart is deterministic. The target it's installing into is not.


The four things that actually stall an install

Fairwinds' account of what breaks these installs isn't vague — it's a repeatable list of the same handful of failure modes, showing up in a different order at every customer:

Failure modeWhat actually happensWho discovers itWhen
Incomplete prerequisitesThe database the chart expects wasn't provisioned; IAM roles or OAuth redirect URIs weren't createdThe install script, mid-runAfter the call has already started
Unstated security/isolation constraintsThe customer's network policy, PSP/PSA config, or air-gapped egress rule blocks something the chart assumes is openWhoever has cluster-admin, usually not on the callHours into debugging
Stakeholder driftSix people — platform team, security, DBA, network, the app owner, the vendor's SE — are each working from a different version of "the plan"The vendor's SE, repeatedlyEvery session
Configuration driftThe cluster docs describe isn't the cluster that exists; someone patched a controller, changed a storage class, or upgraded a CNI plugin since the runbook was writtenNobody, until the chart fails somewhere unexpectedRandomly

None of these are chart bugs. They're properties of installing into a cluster the vendor doesn't control and has never seen. Two customers running "the same" managed Kubernetes distribution can still have meaningfully different isolation models, different admission controllers, different drift from whatever baseline the docs assumed — because a cluster is not a fixed target. It's whatever six months of a different team's ad hoc changes turned it into.

That's also why the failure mode is unpredictable in a way a normal bug isn't. A chart bug is reproducible: same input, same break, same fix, every time. An unknown-starting-state failure isn't — customer A's install stalls on a missing IAM role, customer B's stalls on a network policy nobody flagged, customer C's stalls because a storage class got renamed eighteen months ago and the runbook still references the old one.

The vendor's SE team can get faster at diagnosing each individual failure. They can't get faster at predicting which one shows up next, because the thing generating the failure — the customer's cluster history — is different every time by definition.

Why the paperwork can't fix it

The natural response is to document harder. CrewAI's enterprise Helm chart docs, for example, ship a pre-install checklist covering database creation, IAM setup, and known chart gotchas before anyone runs helm install. That's a reasonable mitigation, and it still doesn't close the gap, for a simple reason: a checklist can tell a customer what to do. It cannot verify they did it, catch a security constraint nobody thought to mention, or force six stakeholders onto the same page before the call starts. Documentation is a description of the target state. It has no power over whether the actual cluster matches that description.

This shows up in the industry data too. In CNCF's 2025 Annual Cloud Native Survey, "cultural changes within the development team" overtook every technical category as the top barrier to cloud-native adoption, cited by 47% of respondents — ahead of tool complexity and skills gaps. That's a striking result for a technology that's been in mainstream production for the better part of a decade: the leftover friction isn't in the software anymore, it's in the coordination problem of getting an organization's people and process aligned before the install even starts. A better Helm chart doesn't touch that. Neither does a longer runbook.

The skills-gap side of this is real too, just smaller than the culture problem. One widely cited startup case study put new-engineer onboarding at three weeks on a Kubernetes-based setup versus two days on a simpler architecture — not because Kubernetes is impossible to learn, but because a new hire has to learn this specific cluster's accumulated quirks, not Kubernetes-in-general. That's the same unknown-starting-state problem showing up as a training cost instead of an install-call cost: the thing being onboarded onto is bespoke, so the ramp is bespoke too.

Installing into a cluster vs. owning the fleet

There's a different way to structure the problem, and it isn't a better chart — it's not installing into someone else's cluster at all.

Cluster API (CAPI) is the Kubernetes SIG-Cluster-Lifecycle project for declaratively provisioning clusters: you define a Cluster and a set of Machine resources, a bootstrap provider (kubeadm, Talos, RKE2, K3s) turns each bare machine or cloud instance into a node, and controllers reconcile the fleet to that declared state continuously — not once, at install time, but forever. CAPI has been production-grade since v1.0 in October 2021 and is now at v1.12 (January 2026), with in-place upgrades and chained multi-minor-version upgrades added along the way.

The relevant shift isn't the tooling — it's who's answering the question "what does this cluster look like?" When a vendor ships a Helm chart, that question gets answered by the customer's infrastructure history, and the vendor finds out the answer live, on the call, one broken assumption at a time. When a platform owns node bootstrap through Cluster API, the platform answered that question itself, at provisioning time, because it built the cluster from a known machine image and a declared spec. There's no discovery phase, because there's nothing left to discover — the fleet's isolation model, admission config, and CNI setup are the platform's own decisions, not an inherited unknown.

Run the same four failure modes from the table above against that model:

Failure modeInstalling into an existing clusterOwning the fleet via Cluster API
Incomplete prerequisitesDiscovered mid-installDoesn't apply — the platform provisions the DB/IAM itself as part of the same declared state
Unstated security constraintsDiscovered by whoever has cluster-admin, hours inDoesn't apply — the platform set the network policy and admission config; nothing is unstated to itself
Stakeholder driftSix people, six versions of the planOne team, one control plane — there's no second "customer infra owner" to reconcile with
Configuration driftDocs vs. reality mismatch, discovered randomlyCAPI's reconciliation loop continuously corrects drift back to the declared spec — it doesn't just avoid drift at t=0, it fights it at every t after

That's the honest scope of what changes: four specific, named categories of failure structurally disappear, not because anyone got better at writing checklists, but because the situation that produces them — an unknown, already-modified cluster — never arises in the first place.

What owning the fleet doesn't fix

It's worth being precise about the edges of this claim, because "own the whole stack" invites overselling. A Cluster-API-provisioned fleet still shares real risk with every other cluster on the planet: hardware fails, networks partition, a bad node image still ships a bad node image. Migrating a customer's existing data and workloads onto a new platform is a separate problem CAPI doesn't touch — that's an application-layer migration, not an infrastructure one. And a genuinely air-gapped, fully on-prem deployment still needs a real bootstrap story for machines the platform can't reach over the network by default.

What CAPI-based fleet ownership eliminates is narrower and more specific than "all install pain": it's the unknown-starting-state class of failure — the four rows in the table above — because those come specifically from installing into infrastructure the platform didn't build and can't fully see. A platform that provisions its own fleet doesn't get to skip operating Kubernetes. It gets to skip finding out, mid-call, what someone else did to it.

The git-push version of the same idea

This is the same structural bet a golden-path deploy flow makes at the application layer: a developer running git push to get a running service shouldn't need to know what admission controller their cluster runs, any more than a platform vendor's customer should need to reconcile six stakeholders' mental models before an install can start. Organizations that invest in well-designed golden paths see voluntary platform adoption above 80%, against under 20% where developers are handed the YAML and told to figure it out — the same gap, one layer up the stack, between "here's a target you have to reverse-engineer" and "here's a known-good path that already accounts for what you need."

Bex applies that same logic to the infrastructure layer the platform itself runs on: it provisions and bootstraps its own Cluster-API-managed fleet rather than shipping a chart for someone else's cluster, so a git push becomes a running HTTPS service on machines Bex owns end to end — no unstated constraint to discover, no six-way plan to reconcile, because there's no second infrastructure owner in the loop. Bex.co is open source; the repo's on GitHub if you want to see how the fleet side is built.


Bex.co is the open-source, AI-native Render alternative — push a git repo, get a running HTTPS service on machines you own. Star the repo on GitHub or deploy your first app today.

Related articles

Run this on infrastructure you own

bex is the open-source, AI-native Render alternative — push a git repo and get a running HTTPS service on your own machines.

Get started with bex