Spotlight on SIG Architecture: API Governance

Source: Kubernetes Blog

SIG Architecture Spotlight – API Governance

This is the fifth interview of the SIG Architecture Spotlight series that covers the different sub‑projects. In this episode we talk with Jordan Liggitt, lead of the API Governance sub‑project.

Introduction

FM: Hello Jordan, thank you for your availability. Tell us a bit about yourself, your role and how you got involved in Kubernetes.

JL: My name is Jordan Liggitt. I’m a Christian, husband, father of four, software engineer at Google by day, and amateur musician by stealth. I was born in Texas (and still like to claim it as my point of origin), but I’ve lived in North Carolina for most of my life.

I’ve been working on Kubernetes since 2014. At that time I was working on authentication and authorization at Red Hat, and my very first pull request to Kubernetes attempted to add an OAuth server to the Kubernetes API server. It never left work‑in‑progress status. I ended up taking a different approach that layered on top of the core Kubernetes API server in a separate project (spoiler alert: this is foreshadowing) and closed the PR without merging six months later.

Undeterred by that start, I stayed involved, helped build Kubernetes authentication and authorization capabilities, and got involved in the definition and evolution of the core Kubernetes APIs—from early beta APIs like v1beta3 to v1. I was tagged as an API reviewer in 2016 based on those contributions, and added as an API approver in 2017.

Today I help lead the API Governance and code‑organization sub‑projects for SIG Architecture, and I am a tech lead for SIG Auth.

FM: And when did you get specifically involved in the API Governance project?

JL: Around 2019.

Goals and Scope of API Governance

FM: How would you describe the main goals and areas of intervention of the sub‑project?

JL:

• Surface area: All the various APIs Kubernetes has. Many people don’t realize that things like command‑line flags, configuration files, how binaries are run, how they talk to back‑end components (e.g., the container runtime), and how data is persisted are also APIs.
• Common misconception: “The API” is often thought of as only the REST API—the biggest and most obvious one with the largest audience. The other surfaces have narrower audiences, so there is more flexibility, but they still require careful consideration.

Goals:

1. Stability while still enabling innovation.
2. Balance “be stable” with “allow change”.

Quality Gates & Lifecycle Involvement

FM: Speaking of changes, in terms of ensuring consistency and quality (which is clearly one of the reasons this project exists), what are the specific quality gates in the lifecycle of a Kubernetes change? Does API Governance get involved during the release cycle, prior to it through guidelines, or somewhere in between? At what points do you ensure the intended role is fulfilled?

JL:

• We maintain guidelines and conventions for APIs in general and for how to change an API. These are living documents that we update as new scenarios arise.
• Because the documents are long and dense, we also provide hands‑on involvement at either the design stage or the implementation stage.
• If a team moves ahead with design work without feedback from API Review (often due to bandwidth constraints), that’s fine—but when implementation begins, the API review will happen then, potentially with substantial feedback.

Bottom line: We get involved whenever a new API is created or an existing API is changed, either at design time or during implementation.

Interaction with KEPs

FM: Is this during the Kubernetes Enhancement Proposal (KEP) process? Since KEPs are mandatory for enhancements, I assume part of the work intersects with API Governance?

JL:

• Yes, it can. KEPs vary in detail. Some include literal API definitions, allowing us to perform an API review at the design stage and then check fidelity during implementation.
• Other KEPs are more conceptual, leaving details to the implementation. In those cases, API Review typically gets involved later, possibly recommending structural changes.

There’s a trade‑off: detailed design upfront vs. iterative discovery during implementation. Teams work differently, and we’re flexible—happy to consult early or later as needed.

Maintaining Conceptual Integrity

FM: This reminds me of what Fred Brooks wrote in The Mythical Man‑Month about conceptual integrity being central to product quality. No matter how you structure the process, there must be a point where someone looks at what is coming and ensures conceptual integrity. Kubernetes uses APIs everywhere—externally and internally—so API Governance is critical to maintaining that integrity. How is this captured?

JL:

• The conventions document captures patterns we’ve learned over time: what to do in various situations.
• We also have automated linters and checks (e.g., for spec/status semantics) that catch issues even when humans miss them.
• As new scenarios arise—and they do constantly—we think through how to approach them, then fold the results back into our documentation and tools.
• Sometimes it takes a few attempts before we settle on an approach that works well.

FM: Exactly. Each new interaction improves the guidelines.

JL: Right. And sometimes the first approach turns out to be wrong; it may take two or three iterations before we land on something robust.

The Impact of Custom Resource Definitions

FM: Is there any particular change, episode, or domain that stands out as especially noteworthy, complex, or interesting in your experience?

JL: The watershed moment was Custom Resources.

Prior to that, every API was handcrafted by us and fully reviewed. There were inconsistencies, but we…

(Interview continues…)

API Governance – Interview Transcript

Custom Resources and Built‑in Validation

Speaker: Jordan

“Good and controlled every type and field. When Custom Resources arrived, anyone could define anything. The first version did not even require a schema. That made it extremely powerful – it enabled change immediately – but it left us playing catch‑up on stability and consistency.

When Custom Resources graduated to General Availability (GA), schemas became required, but escape hatches still existed for backward compatibility. Since then, we’ve been working on giving CRD authors validation capabilities comparable to built‑ins. Built‑in validation rules for CRDs have only just reached GA in the last few releases.

So CRDs opened the “anything is possible” era. Built‑in validation rules are the second major milestone: bringing consistency back.

The three major themes have been defining schemas, validating data, and handling pre‑existing invalid data. With ratcheting validation (allowing data to improve without breaking existing objects), we can now guide CRD authors toward conventions without breaking the world.”

API Governance in Context

(The interview continues beyond this point.)