Kubernetes v1.36: 선언적 검증(Declarative Validation) 정식 출시 (GA)

Kubernetes v1.36에서 Kubernetes 기본 유형(native types)을 위한 **선언적 검증(Declarative Validation)**이 정식 출시(GA, General Availability)되었습니다.

사용자들에게 이는 더욱 신뢰할 수 있고 예측 가능하며, 문서화가 잘 된 API를 의미합니다. 선언적 모델로 전환함으로써, 프로젝트는 OpenAPI를 통해 검증 규칙을 게시하고 Kubebuilder와 같은 생태계 도구와 통합할 수 있는 미래의 가능성을 열게 되었습니다. 기여자 및 생태계 개발자들에게는 수천 줄의 수동 작성 검증 코드를 유지 관리가 용이한 통합 프레임워크로 대체할 수 있는 기회가 됩니다.

이 포스트에서는 왜 이러한 전환이 필요했는지, 선언적 검증 프레임워크는 어떻게 작동하는지, 그리고 이번 GA 릴리스와 함께 어떤 새로운 기능들이 추가되었는지 다룹니다.

동기: "수동 작성" 기술 부채에서의 탈출

수년 동안 Kubernetes 기본 API의 검증은 거의 전적으로 수동으로 작성된 Go 코드에 의존해 왔습니다. 필드가 최소값에 의해 제한되어야 하거나 두 필드가 상호 배타적이어야 하는 경우, 개발자는 이러한 제약 조건을 적용하기 위해 명시적인 Go 함수를 작성해야 했습니다.

Kubernetes API 영역이 확장됨에 따라 이러한 방식은 다음과 같은 시스템적 문제를 야기했습니다:

기술 부채: 프로젝트에 약 18,000줄의 상용구(boilerplate) 검증 코드가 축적되었습니다. 이 코드는 유지 관리가 어렵고 오류가 발생하기 쉬웠으며, 코드 리뷰 시 매우 세밀한 검토가 필요했습니다.
불일치: 중앙 집중식 프레임워크가 없었기에 검증 규칙이 리소스마다 일관성 없게 적용되는 경우가 있었습니다.
불투명한 API: 수동 작성된 검증 로직은 프로그램적으로 발견하거나 분석하기 어려웠습니다. 즉, 클라이언트와 도구들이 소스 코드를 확인하거나 런타임에 오류를 마주하기 전까지는 검증 규칙을 예측할 수 없음을 의미했습니다.

SIG API Machinery가 제안한 해결책은 **선언적 검증(Declarative Validation)**입니다. 이는 types.go 파일 내에서 인터페이스 정의 언어(IDL) 태그(특히 +k8s: 마커 태그)를 직접 사용하여 검증 규칙을 정의하는 방식입니다.

`validation-gen`의 등장

선언적 검증 기능의 핵심은 validation-gen이라는 새로운 코드 생성기입니다. Kubernetes가 딥 카피(deep copies), 변환(conversions), 기본값 설정(defaulting)을 위해 생성기를 사용하는 것처럼, validation-gen은 +k8s: 태그를 구문 분석하고 그에 해당하는 Go 검증 함수를 자동으로 생성합니다.

이렇게 생성된 함수들은 API 스키마에 매끄럽게 등록됩니다. 이 생성기는 확장 가능한 프레임워크로 설계되어, 개발자가 파싱할 태그와 생성할 Go 로직을 기술함으로써 새로운 "검증기(Validator)"를 추가할 수 있습니다.

포괄적인 +k8s: 태그 세트

선언적 검증 프레임워크는 Go 유형에 최적화된 풍부한 검증 기능을 제공하는 포괄적인 마커 태그 세트를 도입합니다. 지원되는 태그의 전체 목록은 공식 문서에서 확인할 수 있습니다. 다음은 현재 Kubernetes 코드베이스에서 흔히 볼 수 있는 주요 태그들입니다:

존재 여부(Presence): +k8s:optional, +k8s:required
기본 제약 조건(Basic Constraints): +k8s:minimum=0, +k8s:maximum=100, +k8s:maxLength=16, +k8s:format=k8s-short-name
컬렉션(Collections): +k8s:listType=map, +k8s:listMapKey=type
유니온(Unions): +k8s:unionMember, +k8s:unionDiscriminator
불변성(Immutability): +k8s:immutable, +k8s:update=[NoSet, NoModify, NoClear]

사용 예시:

type ReplicationControllerSpec struct {
 // +k8s:optional
 // +k8s:minimum=0
 Replicas *int32 `json:"replicas,omitempty"`
}

필드 정의 바로 위에 이러한 태그를 배치함으로써, 제약 조건은 스스로를 설명하게 되며 유형 정의를 읽는 누구에게나 즉시 가시화됩니다.

고급 기능: "앰비언트 래치팅(Ambient Ratcheting)"

이 작업의 가장 중요한 성과 중 하나는 검증 래치팅(Validation Ratcheting)이 이제 API의 표준적이고 자연스러운(ambient) 일부가 되었다는 점입니다. 과거에는 검증을 강화하려면 먼저 수동으로 래치팅 코드를 추가하고, 한 버전을 기다린 다음, 기존 객체가 깨지지 않도록 검증을 강화해야 했습니다.

선언적 검증을 사용하면 이 안전 메커니즘이 내장됩니다. 사용자가 기존 객체를 업데이트할 때, 검증 프레임워크는 유입되는 객체를 oldObject와 비교합니다. 특정 필드의 값이 이전 상태와 의미적으로 동일하다면(즉, 사용자가 변경하지 않았다면) 새로운 검증 규칙은 무시됩니다. 이 "앰비언트 래치팅" 덕분에 기존 사용자에게 최소한의 영향을 주면서 검증을 즉시 완화하거나 강화할 수 있습니다.

`kube-api-linter`를 통한 API 리뷰 확장

GA 단계에 도달하기 위해서는 생성된 코드에 대한 절대적인 신뢰가 필요했지만, 우리의 비전은 단순한 검증 그 이상입니다. 선언적 검증은 API 리뷰를 더 쉽고 일관성 있게, 그리고 확장 가능하게 만들기 위한 포괄적인 접근 방식의 핵심입니다.

검증 규칙을 불투명한 Go 함수에서 구조화된 마커로 옮김으로써 kube-api-linter와 같은 도구에 힘을 실어주고 있습니다. 이 린터는 이제 API 유형을 정적으로 분석하고 API 규칙(conventions)을 자동으로 강제할 수 있어, SIG API Machinery 리뷰어들의 수동 작업 부담을 크게 줄이고 기여자들에게 즉각적인 피드백을 제공합니다.

향후 계획

Kubernetes v1.36 출시와 함께 선언적 검증이 정식 출시(GA)되었습니다. 안정적인 기능으로서 관련 DeclarativeValidation 기능 게이트(feature gate)는 이제 기본적으로 활성화됩니다. 이는 Kubernetes 기본 유형에 새로운 검증 규칙을 추가하는 기본 메커니즘이 되었습니다.

앞으로 프로젝트는 선언적 검증을 더욱 광범위하게 채택할 계획입니다. 여기에는 기존 API의 남은 수동 검증 코드를 마이그레이션하고, 모든 새로운 API 및 필드에 이 방식의 사용을 의무화하는 것이 포함됩니다. 이러한 지속적인 전환은 코드베이스의 복잡성을 줄이는 동시에 전체 Kubernetes API 영역의 일관성과 신뢰성을 향상시킬 것입니다.

핵심 마이그레이션을 넘어, 선언적 검증은 더 넓은 생태계를 위한 흥미로운 미래를 열어줍니다. 검증 규칙이 이제 불투명한 Go 코드가 아닌 구조화된 마커로 정의되므로, Kubernetes API 서버가 게시하는 OpenAPI 스키마에 이를 파싱하여 반영할 수 있습니다. 이는 kubectl, 클라이언트 라이브러리, IDE가 요청이 클러스터에 전송되기도 전에 풍부한 클라이언트 측 검증을 수행할 수 있는 길을 열어줍니다. 또한 동일한 선언적 프레임워크를 Kubebuilder와 같은 생태계 도구에서도 활용할 수 있어, 커스텀 리소스 정의(CRD) 작성자들에게 더욱 일관된 개발 경험을 제공할 수 있습니다.

참여 방법

선언적 검증으로의 전환은 계속 진행 중인 노력입니다. 프레임워크 자체는 GA이지만, 오래된 API를 새로운 선언적 형식으로 마이그레이션하는 작업이 여전히 남아 있습니다.

Kubernetes API Machinery의 핵심에 기여하는 데 관심이 있다면, 이곳이 시작하기에 아주 좋은 곳입니다. validation-gen 문서를 확인하고, sig/api-machinery 태그가 달린 이슈를 찾아보세요. 그리고 Kubernetes Slack의 #sig-api-machinery 및 #sig-api-machinery-dev-tools 채널에서 대화에 참여해 보세요. (초대장이 필요하다면 https://slack.k8s.io/를 방문하세요). 또한 SIG API Machinery 회의에 참석하여 직접 참여할 수도 있습니다.

감사의 말

이 기능이 GA에 도달할 수 있도록 도와주신 모든 분들께 깊은 감사를 드립니다:

그리고 그 과정에서 기여해주신 Kubernetes 커뮤니티의 다른 많은 분들께도 감사드립니다.

Kubernetes 검증의 선언적 미래에 오신 것을 환영합니다!