SIG Architecture에 대한 스포트라이트: API 거버넌스

Source: Kubernetes Blog

SIG Architecture Spotlight – API Governance

이것은 다양한 하위 프로젝트를 다루는 SIG Architecture Spotlight 시리즈의 다섯 번째 인터뷰입니다. 이번 에피소드에서는 Jordan Liggitt에게 API Governance 하위 프로젝트의 리더에 대해 이야기합니다.

Introduction

FM: 안녕하세요 Jordan, 시간을 내 주셔서 감사합니다. 본인 소개와 역할, 그리고 쿠버네티스에 어떻게 참여하게 되었는지 말씀해 주세요.

JL: 제 이름은 Jordan Liggitt입니다. 저는 기독교인이고, 남편이며, 네 자녀의 아버지이자, 낮에는 구글에서 소프트웨어 엔지니어로, 은밀히는 아마추어 뮤지션으로 활동하고 있습니다. 텍사스에서 태어났고(여전히 제 출신지라고 주장하고 싶어요), 대부분의 인생을 노스캐롤라이나에서 살아왔습니다.

저는 2014년부터 쿠버네티스에 참여했습니다. 그때 저는 레드햇에서 인증 및 인가 작업을 하고 있었고, 쿠버네티스에 대한 제 첫 번째 풀 리퀘스트는 쿠버네티스 API 서버에 OAuth 서버를 추가하려는 시도였습니다. 이 PR은 진행 중인 상태에서 머물렀고, 결국 핵심 쿠버네티스 API 서버 위에 별도 프로젝트로 레이어링하는 다른 접근 방식을 택했으며(스포일러: 이것이 앞서 언급한 내용의 암시입니다), 6개월 후에 머지되지 않은 채 PR을 닫았습니다.

그 시작에 좌절하지 않고 계속 참여하면서 쿠버네티스 인증 및 인가 기능을 구축하는 데 도움을 주었고, v1beta3와 같은 초기 베타 API부터 v1에 이르는 핵심 쿠버네티스 API 정의와 진화에 관여했습니다. 2016년에 이러한 기여를 바탕으로 API reviewer로 지정되었고, 2017년에 API approver로 추가되었습니다.

현재 저는 SIG Architecture의 API Governance와 code‑organization 하위 프로젝트를 공동 리드하고 있으며, SIG Auth의 기술 리드이기도 합니다.

FM: 언제 API Governance 프로젝트에 구체적으로 참여하게 되었나요?

JL: 2019년경에요.

Goals and Scope of API Governance

FM: 이 하위 프로젝트의 주요 목표와 개입 영역을 어떻게 설명하시겠어요?

JL:

• 범위: 쿠버네티스가 보유하고 있는 모든 다양한 API들입니다. 많은 사람들이 커맨드‑라인 플래그, 설정 파일, 바이너리 실행 방식, 백엔드 컴포넌트(예: 컨테이너 런타임)와의 통신 방식, 데이터 영속화 방식 등도 API에 해당한다는 사실을 인식하지 못합니다.
• 일반적인 오해: “API”는 종종 가장 크고 가장 명백한 REST API만을 의미한다고 생각됩니다. 다른 표면들은 청중이 좁기 때문에 유연성이 더 크지만, 여전히 신중한 고려가 필요합니다.

목표:

1. 안정성을 유지하면서 혁신을 가능하게 하는 것.
2. “안정적이어야 함”과 “변경을 허용해야 함” 사이의 균형을 맞추는 것.

Quality Gates & Lifecycle Involvement

FM: 변경 사항에 대해 말하자면, 일관성과 품질을 보장하기 위해(이 프로젝트가 존재하는 주요 이유 중 하나) 쿠버네티스 변경 라이프사이클에서 구체적인 품질 게이트는 무엇인가요? API Governance는 릴리즈 사이클 중에, 가이드라인을 통해 사전에, 혹은 그 사이 어딘가에서 개입하나요? 어떤 시점에 의도된 역할이 수행되는지 알려 주세요.

JL:

• 우리는 일반 API와 API 변경 방법에 대한 가이드라인 및 컨벤션을 유지합니다. 이는 새로운 시나리오가 등장함에 따라 업데이트되는 살아있는 문서입니다.
• 문서가 길고 복잡하기 때문에 디자인 단계 혹은 구현 단계에서 직접적인 참여도 제공합니다.
• 팀이 API Review의 피드백 없이 디자인 작업을 진행한다면(대개는 리소스 부족 때문) 괜찮지만, 구현이 시작될 때 API 리뷰가 진행되며, 이때 상당한 피드백이 제공될 수 있습니다.

핵심: 새로운 API가 생성되거나 기존 API가 변경될 때마다, 디자인 단계든 구현 단계든 언제든 개입합니다.

Interaction with KEPs

FM: 이는 Kubernetes Enhancement Proposal(KEP) 프로세스와 관련된 건가요? KEP가 개선 사항에 필수이므로, 작업의 일부가 API Governance와 교차한다고 생각합니다.

JL:

• 네, 그럴 수 있습니다. KEP는 상세 정도가 다양합니다. 일부는 문자 그대로 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 거버넌스 – 인터뷰 전사

사용자 정의 리소스와 내장 검증

Speaker: Jordan

“모든 타입과 필드를 잘 제어했습니다. 사용자 정의 리소스가 등장했을 때, 누구나 무엇이든 정의할 수 있었습니다. 첫 번째 버전은 스키마조차 필요하지 않았습니다. 이는 매우 강력했으며—즉시 변경을 가능하게 했지만—안정성과 일관성을 따라잡는 데 어려움을 남겼습니다.

사용자 정의 리소스가 일반 제공(GA) 단계에 도달했을 때, 스키마가 필수가 되었지만, 이전 호환성을 위한 예외 경로는 여전히 존재했습니다. 그 이후로 우리는 CRD 작성자에게 내장 검증과 견줄 수 있는 검증 기능을 제공하기 위해 노력해 왔습니다. CRD용 내장 검증 규칙은 최근 몇 릴리스에서야 비로소 GA에 도달했습니다.

그래서 CRD는 “무엇이든 가능” 시대를 열었습니다. 내장 검증 규칙은 두 번째 주요 이정표이며: 일관성을 되찾는 것입니다.

세 가지 주요 주제는 스키마 정의, 데이터 검증, 그리고 이미 존재하는 잘못된 데이터 처리였습니다. 래칫 검증(기존 객체를 깨뜨리지 않고 데이터가 개선될 수 있도록 허용) 덕분에 이제 우리는 CRD 작성자를 관례에 맞추도록 안내하면서도 세상을 깨뜨리지 않을 수 있습니다.”

컨텍스트에서 본 API 거버넌스

(인터뷰는 이 지점 이후에도 계속됩니다.)