API 버전 관리(v1, v1beta1 등)와 Deprecation 정책 이해하기

API 버전 관리(v1, v1beta1 등)와 Deprecation 정책 이해하기

쿠버네티스는 전 세계 수많은 기업의 프로덕션 환경을 책임지는 동시에, 클라우드 네이티브 생태계의 빠른 혁신 속도를 수용해야 하는 거대한 플랫폼입니다. 이 두 가지 상충하는 목표—새로운 기능의 신속한 도입과 기존 운영 환경의 절대적인 안정성 보장—를 동시에 달성하기 위해 쿠버네티스는 매우 엄격하고 체계적인 API 버전 관리 및 폐지(Deprecation) 정책을 운영하고 있습니다. 클러스터 관리자와 애플리케이션 개발자는 자신이 작성하는 YAML 매니페스트가 어느 수준의 안정성을 보장받는지, 그리고 언제 새로운 버전으로 마이그레이션해야 하는지 정확히 이해해야 합니다.

1. 쿠버네티스 API 성숙도 레벨: Alpha, Beta, Stable

쿠버네티스의 모든 API 리소스(Pod, Deployment, Ingress 등)는 apiVersion 필드를 통해 자신의 성숙도(Maturity Level)를 명시합니다. 이 성숙도는 크게 Alpha, Beta, Stable 세 단계로 나뉘며, 각 단계는 해당 API의 신뢰성, 변경 가능성, 그리고 클러스터 내 기본 활성화 여부를 결정짓는 중요한 기준이 됩니다.

1.1. Alpha (알파 레벨)

• 표기법: v1alpha1, v1alpha2, v2alpha1 등
• 특징: 가장 초기 단계의 실험적인 기능입니다. 알파 API는 기능에 버그가 포함되어 있을 가능성이 높으며, 언제든지 설계가 뒤집힐 수 있습니다.
• 호환성 보장: 하위 호환성을 전혀 보장하지 않습니다. 다음 쿠버네티스 마이너 릴리스에서 사전 공지 없이 API 스키마가 변경되거나 기능 자체가 완전히 삭제될 수 있습니다.
• 사용 정책: 기본적으로 클러스터에서 비활성화되어 있습니다. 클러스터 관리자가 Kube-apiserver의 --feature-gates 플래그를 통해 명시적으로 기능을 켜야만 사용할 수 있습니다. 프로덕션 환경에서의 사용은 절대 권장하지 않으며, 단기적인 개념 증명(PoC)이나 기능 테스트 목적으로만 제한적으로 사용해야 합니다.

1.2. Beta (베타 레벨)

• 표기법: v1beta1, v2beta1 등
• 특징: 코드가 충분히 테스트되었고 기능의 유용성이 입증된 단계입니다. 쿠버네티스 커뮤니티에서 해당 기능이 향후 정식 버전으로 승격될 것임에 합의한 상태입니다.
• 호환성 보장: 기능 자체는 삭제되지 않음을 보장하지만, 정식 버전(Stable)으로 넘어가는 과정에서 오브젝트의 세부적인 스키마(필드명, 구조 등)가 하위 호환되지 않는 방식으로 약간 변경될 수 있습니다.
• 사용 정책: v1.24 이전에는 베타 API가 기본적으로 활성화되어 있었으나, 무분별한 베타 API의 프로덕션 도입으로 인한 업그레이드 장애를 막기 위해 최근 버전부터는 새로운 베타 API의 기본 활성화 정책이 보수적으로 변하고 있습니다. 프로덕션 환경에 적용할 수는 있으나, 클러스터 업그레이드 시 매니페스트를 수정해야 할 리스크를 안고 가야 합니다.

1.3. Stable (안정/정식 레벨)

• 표기법: v1, v2 등 (접미사가 없음)
• 특징: 수많은 엣지 케이스가 해결되었고, 프로덕션 환경에서 장기간 안심하고 사용할 수 있는 최고 수준의 안정성을 갖춘 API입니다.
• 호환성 보장: 엄격한 하위 호환성을 보장합니다. v1으로 등록된 API는 향후 동일한 그룹 내에서 어떠한 구조적 파괴(Breaking Change)도 허용되지 않습니다.
• 사용 정책: 프로덕션 환경의 모든 워크로드는 반드시 Stable API 버전을 기준으로 매니페스트를 작성해야 합니다.

2. API Deprecation(폐지) 및 제거(Removal) 정책

오래된 버전을 무한정 지원하면 Kube-apiserver의 코드가 극도로 비대해지고 유지보수가 불가능해집니다. 따라서 쿠버네티스는 특정 API 버전을 더 이상 권장하지 않는 '폐지(Deprecation)' 단계와, 코드 베이스에서 완전히 삭제하여 더 이상 인식하지 못하게 만드는 '제거(Removal)' 단계를 명확한 가이드라인에 따라 실행합니다.

2.1. API 제거의 대원칙

쿠버네티스 커뮤니티가 합의한 API 제거 정책의 핵심은 다음과 같습니다.

1. Stable API의 영속성: v1, v2와 같은 Stable API는 결코 클러스터에서 삭제되지 않습니다. 만약 v1에 설계상 큰 결함이 발견되어 새로운 구조가 필요하다면, 기존 v1을 수정하는 것이 아니라 v2라는 완전히 새로운 API 버전을 만들어 병행 지원해야 합니다.
2. 사전 공지의 의무: API를 제거하기 전에는 반드시 'Deprecation' 선언을 먼저 해야 합니다. Deprecated된 API는 여전히 정상 동작하지만, 클라이언트(kubectl) 사용 시 경고 메시지(Warning)를 출력하여 관리자에게 마이그레이션을 촉구합니다.

2.2. 성숙도별 지원 및 제거 타임라인

• Alpha API: 폐지 공지(Deprecation Notice) 없이 언제든지 제거될 수 있습니다.
• Beta API: 특정 베타 버전(예: v1beta1)이 도입된 후 더 안정적인 버전(예: v1beta2 또는 v1)이 출시되면, 기존 베타 버전은 즉시 Deprecated 상태가 됩니다. 가장 중요한 규칙은, 베타 API는 Deprecated된 시점으로부터 정확히 3개의 마이너 릴리스(약 9개월~1년)가 지나면 Kube-apiserver에서 완전히 제거(Removed)된다는 것입니다. 과거 extensions/v1beta1 Deployment나 networking.k8s.io/v1beta1 Ingress가 v1.16, v1.22 업데이트 시 대거 삭제되면서 전 세계 수많은 클러스터에 대장애를 일으켰던 원인이 바로 이 엄격한 베타 제거 타임라인 규칙 때문입니다.

3. Kube-apiserver 내부의 다중 버전 변환(Conversion) 아키텍처

클러스터 관리자 입장에서 가장 헷갈리는 질문 중 하나는 "내 클러스터에 v1beta1 매니페스트로 배포된 리소스가 있는데, 클러스터를 업그레이드하면 어떻게 되는가?"입니다. 이를 이해하려면 API 서버의 내부 변환(Conversion) 메커니즘을 알아야 합니다.

쿠버네티스의 특정 리소스(예: HPA)가 v2beta2와 v2 버전을 동시에 지원한다고 가정해 봅시다. Kube-apiserver는 etcd 백엔드 스토리지에 데이터를 저장할 때, 각기 다른 버전으로 파편화하여 저장하지 않습니다. API 서버는 내부적으로 스토리지 버전(Storage Version)이라는 단일 버전을 지정해 두고, 클라이언트가 어떤 API 버전으로 요청을 보내든 이를 내부 표현식(Internal Version)으로 자동 변환(Convert)하여 일관된 스키마로 etcd에 기록합니다.

1. 사용자가 구버전인 v2beta2 매니페스트로 kubectl apply를 실행합니다.
2. Kube-apiserver 내부의 Conversion Webhook이나 기본 변환 함수가 이를 가로채어 최신 스키마인 v2 형태로 데이터를 매핑하고 조립합니다.
3. etcd에는 최종적으로 v2 포맷으로 저장됩니다.
4. 나중에 사용자가 kubectl get hpa -o yaml을 요청하면, API 서버는 etcd에 저장된 v2 데이터를 다시 사용자가 선호하는 버전(또는 기본 제공 버전)으로 역변환하여 응답합니다.

이러한 유연한 Conversion 아키텍처 덕분에, API 버전이 바뀌더라도 기존 클러스터에서 동작 중인 실제 워크로드(파드, 컨테이너)가 재시작되거나 중단되는 일은 발생하지 않습니다. 문제는 '클러스터 내부의 동작'이 아니라 '사용자가 보유한 정적 매니페스트(YAML) 파일'입니다.

4. 클러스터 업그레이드와 API 마이그레이션 실무 가이드

특정 API 버전이 제거되는 쿠버네티스 버전(예: v1.22, v1.25 등)으로 클러스터 컨트롤 플레인을 업그레이드할 때는 치명적인 장애를 예방하기 위한 사전 작업이 필수적입니다. API가 제거되면, 기존에 v1beta1으로 작성해 둔 Git 저장소의 YAML 파일을 kubectl apply로 배포하는 순간 API 서버가 "해당 리소스를 찾을 수 없음" 에러를 뱉으며 CI/CD 파이프라인이 즉시 마비되기 때문입니다.

4.1. Deprecation 감지와 감사(Audit) 로깅

업그레이드 전 가장 먼저 해야 할 일은 클러스터에 곧 삭제될 API를 호출하는 주체가 있는지 찾아내는 것입니다.

• Kube-apiserver의 감사 로그(Audit Log)를 분석하여 구버전 API 엔드포인트에 대한 요청(User-Agent 포함)을 모니터링합니다.
• 쿠버네티스는 API 서버 내부에 Warning 헤더를 포함하여 응답합니다. kubectl 명령어를 칠 때 나오는 "W0824 ... is deprecated" 형태의 경고 메시지를 주의 깊게 수집해야 합니다.
• Pluto, Kube-no-trouble(kubent)와 같은 오픈소스 CLI 도구를 CI/CD 파이프라인에 통합하여 헬름(Helm) 차트나 로컬 YAML 파일 중에 폐지 예정인 API를 사용하고 있는 매니페스트가 있는지 자동으로 스캐닝합니다.

4.2. 매니페스트 변환 및 kubectl convert 플러그인

식별된 레거시 YAML 파일들은 수동으로 버전을 수정해야 합니다. 단순히 apiVersion: v1beta1을 v1으로 문자열 치환만 해서는 안 됩니다. 버전이 올라가면서 필드의 이름이 바뀌거나 구조가 중첩되는 등 스키마 변경이 동반되기 때문입니다.
쿠버네티스는 이를 돕기 위해 kubectl-convert 플러그인을 제공합니다. 이 도구는 로컬에 있는 구버전 YAML 파일을 읽어, 현재 클러스터의 Kube-apiserver가 제공하는 최신 API 스키마(예: v1)에 맞추어 구조를 안전하게 자동 변환해 줍니다. 이렇게 변환된 최신 코드를 Git 저장소에 커밋(Commit)하여 인프라 형상을 최신 상태로 동기화하는 것이 성공적인 클러스터 업그레이드의 핵심입니다.