Kubernetes SIG Architecture가 API 거버넌스 프레임워크를 통해 REST API, CLI 플래그, 설정 파일 등 모든 API 표면의 안정성과 진화를 동시에 관리하는 체계 구축

Context

Kubernetes는 REST API뿐 아니라 CLI 플래그, 설정 파일, 바이너리 실행 방식, 컨테이너 런타임 통신 등 다양한 API 표면을 노출하고 있다. 이러한 광범위한 API 표면에서 안정성을 유지하면서도 혁신을 계속하기 위한 일관된 거버넌스 프레임워크가 필요했다.

Technical Solution

• 모든 API 표면에 대한 거버넌스 적용: REST API, CLI 플래그, 설정 파일, 바이너리 실행 방식, 백엔드 컴포넌트(컨테이너 런타임) 통신, 데이터 지속성 인터페이스를 하나의 프레임워크로 관리
• 설계 단계와 구현 단계 모두에서 API 리뷰 수행: Kubernetes Enhancement Proposal(KEP) 프로세스 중 설계 문서에 API 정의가 포함되면 설계 단계에서 리뷰, 상세하지 않은 KEP는 구현 단계에서 리뷰 진행
• 컨벤션 문서와 자동화된 린터 도입: spec/status 의미론 같은 패턴 정합성을 자동 검사하는 도구와 지속 업데이트되는 컨벤션 문서를 병행
• 점진적 학습 구조로 신규 기여자 온보딩: 소규모 API 변경 사례를 따라가며 설계-구현-리뷰 전 과정을 관찰한 후 규모를 키우는 방식으로 진행
• 호환성과 안정성 우선 설계: 현재 변경이 미래에 어떻게 진화할 수 있을지 미리 검토하고, 하위 호환성을 유지하면서 개선할 수 있는 설계 여백 확보

Key Takeaway

API 거버넌스의 핵심은 사용자와의 신뢰 관계 유지에 있다: 더 많은 작업, 느린 진행, 코드 중복 등의 비용을 감수하더라도 하위 호환성 약속을 지키는 것이 장기적으로 사용자 경험을 향상시킨다. 미래의 불확실성과 실수 가능성을 전제하고 설계 단계부터 진화 가능성을 확보하는 접근이 필수적이다.