API Governance in Kubernetes:

Why Stable Interfaces Are Crucial for the Ecosystem

Kubernetes is now much more than a Container orchestrator. A vast ecosystem has developed around the platform, with tools, extensions, platform solutions, and automations all built on the same foundations. These foundations are APIs. They form the interfaces through which clusters are managed, resources are defined, and components communicate with each other.

As this ecosystem grows, a central question becomes increasingly important: How can a system with thousands of contributors continue to evolve in a way that allows for innovation without jeopardizing existing users? This is where a part of the Kubernetes community comes into play, often working in the background but playing a central role in the stability of the entire project: API Governance.

The Role of API Governance

API Governance is a subproject within SIG Architecture, the group concerned with the overarching architecture of Kubernetes. The goal of this subproject is to ensure that Kubernetes APIs develop consistently and stably.

This involves more than just the well-known REST API of the Kubernetes API Server. As Jordan Liggitt—one of the long-standing Kubernetes developers and co-responsible for API Governance—explains, the API surface encompasses much more. Even things like command-line parameters, configuration files, the way Kubernetes components are started, or how they communicate with other systems can be considered APIs. Even the interfaces to Container runtimes or persistence mechanisms are part of this broader understanding.

These various interfaces have different target audiences, but they all represent contracts between Kubernetes and its users. Once tools or platforms are built on them, an expectation arises: that these interfaces behave reliably and do not suddenly change fundamentally.

API Governance ensures that this expectation is met.

Stability Without Stagnation

The central challenge is to reconcile two seemingly opposing goals: stability and evolution.

A system naturally remains stable if it is not changed. However, a project like Kubernetes must constantly evolve. New requirements arise, new use cases emerge, and the ecosystem continuously grows.

The task of API Governance is therefore to find a way to enable changes without breaking existing integrations. Extensive guidelines and conventions exist to describe how APIs should be designed and developed. These documents are not static rules but are continuously developed as new scenarios arise.

In addition to these guidelines, automated checks are also used. Tools check typical patterns such as the separation between spec and status or other structural conventions. This allows many errors to be identified before they are incorporated into the project.

When API Governance Intervenes in the Development Process

New features or major changes to Kubernetes are usually planned through so-called Kubernetes Enhancement Proposals (KEPs). These documents describe how a feature should work and what impact it will have on the system.

API Governance can be involved at different points in time. Ideally, this happens during the design phase when a KEP describes specific API structures. In this case, it can be checked early on whether the design is consistent with existing conventions and whether it remains extendable in the long term.

In other cases, details are only worked out during implementation. Then the API review occurs later in the process. This is fundamentally possible but can lead to larger changes being necessary if structural problems are discovered.

In practice, it is repeatedly shown that early coordination with API Governance is particularly helpful. Presenting major design decisions shortly before important milestones like the enhancement freeze often makes thorough discussion more difficult.

A Turning Point for Kubernetes APIs: Custom Resources

A particularly defining moment for the development of Kubernetes APIs was the introduction of Custom Resource Definitions (CRDs).

Before the introduction of CRDs, all Kubernetes APIs were created directly by the core developers and fully reviewed. Although there were inconsistencies even then, the community had a clear overview of all existing resources.

With CRDs, this situation changed fundamentally. Suddenly, anyone could define their own APIs and integrate them into Kubernetes. This capability greatly expanded the platform and enabled the development of entire ecosystems, such as around operators.

The first version of CRDs, however, also brought challenges. In the early phase, it was even possible to define Custom Resources without a schema. This resulted in a high degree of flexibility but also a loss of consistency.

With the further development of CRDs, additional mechanisms were introduced. When CRDs finally reached stable GA status, mandatory schemas were introduced, for example. In recent releases, new validation mechanisms have also been added, offering CRD authors similar capabilities to those of built-in Kubernetes resources.

An important step was also the introduction of ratcheting validation. This approach allows existing resources to be gradually improved without immediately invalidating already stored objects. This way, stricter rules can be introduced without breaking existing systems.

Collaboration Within the Kubernetes Architecture

API Governance does not work in isolation but closely collaborates with other groups within the project. Particularly important is the collaboration with SIG API Machinery.

While API Machinery develops the technical foundations for Kubernetes APIs—such as mechanisms for versioning, storage, or validation—API Governance ensures that these capabilities are used consistently. At the same time, SIG Architecture coordinates the overarching direction of the system.

This collaboration ensures that the technical tools, architecture, and specific API designs develop in a common direction.

Why API Stability Is So Important for Users

From the perspective of Kubernetes users, stable APIs are much more than a technical detail. Many companies have built extensive automations, platform tools, or integrations that work directly with Kubernetes interfaces.

If these interfaces were to change unexpectedly, it would have immediate impacts on entire platform landscapes.

This is precisely why the Kubernetes community takes the issue of API compatibility so seriously. Even if this sometimes means additional work or slows down decisions, the project pursues a clear goal: users should be able to rely on their integrations working in the long term.

An important thought behind this is that today’s developers cannot know all future requirements. Good API designs must therefore be consciously designed to be extendable later without affecting existing users.

How to Get Involved in API Governance

For new contributors, the topic of API Governance may initially seem complex. However, getting started does not have to involve the entire rulebook.

Often, it is useful to accompany a specific change in the project. Following the path of a small API adjustment from idea through design to implementation quickly gives a sense of how the various conventions are applied in practice.

Direct discussions within the community, such as in design reviews or joint PR meetings, are particularly helpful. Such conversations often convey a much deeper understanding than pure documentation.

Conclusion

API Governance is one of the areas of Kubernetes that rarely takes the spotlight but is indispensable for the functioning of the entire ecosystem.

In a project with thousands of developers and a vast user base, it ensures that APIs remain consistent while still being able to evolve. Especially because Kubernetes is so heavily built on APIs, this balance is crucial.

Ultimately, the community pursues a clear goal: to give users the confidence that they can build on Kubernetes—today and in the future.