API Deprecations

하나의 API Group은 여러 개의 API Version을 지원한다.

그렇다면 여러 버전을 지원해야 하는 이유는 무엇이며, 몇 가지 버전을 지원해야 하는가? 더 이상 사용하지 않는 오래된 버전은 어느 시점에 제거할 수 있는가?

 

이 글에서는 위와 같은 부분을 위한 Kubernetes API Deprecations(지원 중단 정책)에 대해 정리한다.

 

Deprecations 정책

1. API 요소는 API Group의 버전을 증가시키는 방법으로만 제거할 수 있다.

즉, v1alphav1의 요소는 v1alphav2 이상의 버전에서 삭제할 수 있다.

 

2. API 개체는 일부 버전에 존재하지 않는 전체 REST 리소스를 제외하고, 특정 릴리스의 API 버전 간에 정보 손실 없이 변경할 수 있어야 한다.

즉, v1으로 작성한 객체를 v2로 읽은 후 v1으로 변환했을 때, 그 결과는 원본 객체와 동일해야 한다.

 

3. API 버전은 안정화된 새 API 버전이 출시될 때까지 지원된다. 

GA API 버전은 alpha, beta, GA API 버전을 대체할 수 있다. 하지만 alpha, beta 버전은 GA API 버전을 대체할 수 없다.

 

4a. 최신 API 버전을 제외하고, 오래된 API 버전은 사용 금지를 알린 후 아래의 기간 동안 또는 그 이상 지원되어야 한다.

버전	기간
GA	12개월 또는 3 릴리즈
beta	9개월 또는 3 릴리즈
alpha	0 릴리즈

 

4b. API Group의 새 버전과 이전 버전을 모두 지원하는 두 번째 릴리즈가 발생할 때까지 preferred version과 Storage version은 새 버전으로 변경되지 않을 수 있다.

 

kubectl convert

kubernetes 클러스터 업그레이드 시 기존 매니페스트(yaml) 파일의 버전 업데이트가 필요하다.

convert는 별도 플러그인이므로 설치가 필요하다.

 

설치 방법 참고

https://kubernetes.io/ko/docs/tasks/tools/install-kubectl-linux/#kubectl-convert-%ED%94%8C%EB%9F%AC%EA%B7%B8%EC%9D%B8-%EC%84%A4%EC%B9%98

리눅스에 kubectl 설치 및 설정

 

매니페스트 파일 업데이트

kubectl convert -f <OLD_FILE> --output-verion <NEW_API>

# 예시
kubectl convert -f nginx.yaml --output-verion apps/v1
kubectl convert -f nginx_old.yaml --output-verion apps/v1 > nginx_new.yaml

 

 

---

참고 문서

https://kubernetes.io/docs/reference/using-api/deprecation-policy/

Kubernetes Deprecation Policy