Back to index
OtherA week to get something running, months to operate well·Free and open source, infrastructure costs are yours

Kubeflow Documentation and Tutorials

3.0

Comprehensive documentation for a platform most teams should not adopt. The pipelines component is genuinely good and the rest is an enormous amount of infrastructure looking for a justification.

What We Liked

  • Pipelines are well designed and the SDK documentation is the strongest part of the project
  • Real multi-tenancy and resource isolation, which matters at genuine organisational scale
  • No vendor lock-in, which is a legitimate reason to choose it over a managed platform
  • Katib for hyperparameter search is solid and under-appreciated

What Could Be Better

  • The operational burden is severe and the documentation consistently underplays it
  • Component versions and compatibility are a recurring source of pain
  • Installation and upgrade guidance has historically been the weakest area
  • Assumes deep Kubernetes expertise while presenting itself as an ML platform

Detailed review

I need to be direct about my position because a balanced review here would be misleading. Most teams that adopt this platform should not have. The documentation is thorough, the engineering is real, the individual components are mostly good, and the total cost of running it is dramatically higher than the people choosing it expect. That gap between expectation and reality is the single most important thing to communicate about this project, and the documentation does approximately nothing to close it.

Start with what is genuinely good, because there is real value here. The pipelines component is well designed. Defining machine learning workflows as directed graphs of containerised steps, with typed inputs and outputs, caching of unchanged steps, and artifact lineage tracked automatically, is the correct abstraction for this problem. The SDK documentation is the strongest part of the project, the concepts are explained properly, and someone who learns to think in pipelines here will carry that thinking to any orchestration tool.

If you read one part of this documentation, read that. Katib, the hyperparameter tuning component, is better than its reputation and gets less attention than it deserves. Grid search, random search, Bayesian optimisation and early stopping strategies, running as Kubernetes jobs with proper parallelism. For a team already on this platform, it is a sensible way to run a search without building the orchestration yourself.

The multi-tenancy story is the real argument for the platform and it is a narrow one. If you are a platform team supporting many data science teams who need isolated namespaces, quota enforcement, shared GPU pools with fair scheduling, and per-team access control, then a Kubernetes-native platform is a reasonable answer and the documentation covers those concerns properly. That is a genuine use case. It describes maybe a few percent of the organisations that install this.

And the absence of lock-in is worth something real. Everything runs on your cluster, on any cloud or on-premises, and nothing depends on a vendor's control plane. For organisations with regulatory constraints or a strategic aversion to managed services, that matters. Now the reality.

This is not a product you install, it is an infrastructure programme you commit to. It is a collection of separately versioned components with their own dependencies, custom resource definitions, controllers and service mesh requirements, glued together on top of Kubernetes. Every one of those components can break independently. Upgrades have historically been unpleasant, sometimes to the point where reinstalling and migrating was the recommended path.

The documentation describes each component competently and never assembles an honest picture of what it is like to keep the whole thing healthy over two years. That silence is the core criticism. Version compatibility is a recurring and specific pain. Which version of the platform works with which Kubernetes version, which component versions are compatible with each other, which installation manifest corresponds to which release.

This information exists and it is scattered, sometimes contradictory between the documentation and the repository, and it is exactly the information you most need before starting. Installation is where most people meet the wall. The documentation offers several paths, they vary in maintenance quality, and the experience of following one is frequently a sequence of pods that will not start for reasons requiring you to debug Kubernetes rather than machine learning. There have been distributions and managed offerings that improve this, which is itself telling.

When an ecosystem grows up around making your installation survivable, the installation is a problem. The framing problem underlies all of it. This presents as a machine learning platform and it is a Kubernetes platform that hosts machine learning workloads. The person who succeeds with it is a competent Kubernetes operator who has learned some machine learning, not a data scientist who has learned some infrastructure.

The documentation is written as though the second person is the audience, and that mismatch sets up a lot of failed adoptions. The honest advice for a data science team without dedicated platform engineering is that a managed offering will get you further faster, and the lock-in you are avoiding is cheaper than the operations you are taking on. There is also the question of whether the full platform is the right unit at all. Many teams would be better served using the pipelines component alone, or a lighter orchestrator entirely, and getting serving from something purpose-built.

The documentation naturally presents the integrated whole as the goal. My three point zero is for genuinely good pipelines documentation, a solid tuning component, real multi-tenancy for the organisations that need it, and freedom from vendor control. Marked down hard for consistently understating the operational cost, for compatibility and installation pain that the documentation treats as incidental rather than central, and for addressing an audience that is not the audience who can actually run this. Read the pipelines material.

Think very carefully before installing the rest.

[ final ]

The verdict.

Justifiable if you have a platform team, many teams to serve, and a hard requirement to stay off managed services. For everyone else it is infrastructure you will regret.