[kubernetes] Version Upgrade

버전 차이(skew) 정책

쿠버네티스 버전은 x.y.z로 표현된다. 여기서 x는 메이저 버전, y 는 마이너 버전, z는 패치 버전을 의미한다. 

쿠버네티스 프로젝트는 최근 세 개의 마이너 릴리스 (1.31, 1.30, 1.29) 에 대한 릴리스 분기를 유지한다. 쿠버네티스 1.19 이상은 약 1년간의 패치 지원을 받는다. 쿠버네티스 1.18 이상은 약 9개월의 패치 지원을 받는다.
공식문서: https://kubernetes.io/ko/releases/version-skew-policy/

버전 번호 체계 (x.y.z)

• x (메이저 버전):
  • 큰 변화나 호환성이 깨지는 주요 업데이트가 발생할 때 증가한다.
  • 예: 2.y.z가 나오면 기존 설정과 호환되지 않는 주요 기능 변화가 있을 수 있다. 
• y (마이너 버전):
  • 새로운 기능, 개선 사항 및 일부 호환성 있는 변경 사항이 추가될 때 증가한다. 
  • 약 3~4개월 주기로 새 마이너 버전이 출시된다.
  • 예: 1.31.0에서 1.32.0으로 업그레이드 시 새로운 기능이 포함된다. 
• z (패치 버전):
  • 버그 수정, 보안 패치 및 안정성 개선을 포함한다. 
  • 예: 1.31.1, 1.31.2 등으로 증가한다. 

kube-apiserver

고가용성(HA) 클러스터에서 최신 및 가장 오래된 kube-apiserver 인스턴스가 각각 한 단계 마이너 버전 내에 있어야 한다.

• 최신 kube-apiserver는 1.31 이다.
• 다른 kube-apiserver 인스턴스는 1.31 및 1.30 을 지원한다.

kubelet

kubelet은 kube-apiserver보다 최신일 수 없으며, 2단계의 낮은 마이너 버전까지 지원한다.

• kube-apiserver가 1.31 이다.
• kubelet은 1.31, 1.30 및 1.29 을 지원한다.

HA 클러스터의 kube-apiserver 인스턴스 사이에 버전 차이가 있으면 허용되는 kubelet 버전의 범위도 줄어든다.

• kube-apiserver 인스턴스는 1.31 및 1.30 이다.
• kubelet은 1.30 및 1.29 을 지원한다(1.31 는 kube-apiserver의 1.30 인스턴스보다 최신 버전이기 때문에 지원하지 않는다).

kube-controller-manager, kube-scheduler 그리고 cloud-controller-manager

kube-controller-manager, kube-scheduler 그리고 cloud-controller-manager는 그들과 통신하는 kube-apiserver 인스턴스보다 최신 버전이면 안 된다. kube-apiserver 마이너 버전과 일치할 것으로 예상하지만, 최대 한 단계 낮은 마이너 버전까지는 허용한다(실시간 업그레이드를 지원하기 위해서)

• kube-apiserver은 1.31 이다.
• kube-controller-manager, kube-scheduler 그리고 cloud-controller-manager는 1.31 과 1.30 을 지원한다.

예시

HA 클러스터의 kube-apiserver 인스턴스 간에 버전 차이가 존재하고 이러한 구성 요소가 클러스터의 모든 kube-apiserver 인스턴스와 통신할 수 있는 경우(예를 들어, 로드 밸런서를 통해서)에는 구성 요소의 허용하는 버전의 범위도 줄어든다.

• kube-apiserver 인스턴스는 1.31 및 1.30 이다.
• kube-controller-manager, kube-scheduler 그리고 cloud-controller-manager는 모든 kube-apiserver 인스턴스로 라우팅하는 로드 밸런서와 통신한다.
• kube-controller-manager, kube-scheduler 그리고 cloud-controller-manager는 1.30 에서 지원한다(1.31 는 kube-apiserver 인스턴스의 1.30 버전보다 최신이기 때문에 지원하지 않는다).

kubectl

kubectl은 kube-apiserver의 한 단계 마이너 버전(이전 또는 최신) 내에서 지원한다.

• kube-apiserver은 1.31 이다.
• kubectl은 1.32, 1.31 및 1.30 을 지원한다.

예시

HA 클러스터의 kube-apiserver 인스턴스 간에 버전 차이가 있으면 지원되는 kubectl 버전의 범위도 줄어든다.

예

• kube-apiserver 인스턴스는 1.31 및 1.30 이다.
• kubectl은 1.31 및 1.30 에서 지원한다(다른 버전은 kube-apiserver 인스턴스 중에 한 단계 이상의 마이너 버전 차이가 난다).

지원되는 구성 요소 업그레이드 순서

구성요소 간 지원되는 버전 차이는 구성요소를 업그레이드하는 순서에 영향을 준다. 이 섹션에서는 기존 클러스터를 버전 1.30 에서 버전 1.31 로 전환하기 위해 구성 요소를 업그레이드하는 순서를 설명한다.

선택적으로, 업그레이드를 준비할 때, 쿠버네티스 프로젝트는 업그레이드 중 가능한 많은 회귀 분석 및 버그 수정의 이점을 얻기 위해 다음을 수행할 것을 권장한다.

• 구성 요소가 현재 마이너 버전의 최신 패치 버전에 있는지 확인한다.
• 구성 요소를 대상 마이너 버전의 최신 패치 버전으로 업그레이드 한다.

예를 들어, 만약 1.30 버전을 실행 중인 경우, 최신 패치 버전을 사용 중인지 확인한다. 그런 다음, 최신 패치 버전인 1.31로 업그레이드 한다.

kube-apiserver

사전 요구 사항

• 단일 인스턴스 클러스터에서 기존 kube-apiserver 인스턴스는 1.30 이어야 한다.
• HA 클러스터에서 모든 kube-apiserver 인스턴스는 1.30 또는 1.31 이어야 한다(이것은 kube-apiserver 인스턴스 간의 가장 최신과 오래된 버전의 차이를 최대 1개의 마이너 버전의 차이로 보장한다).
• 이 서버와 통신하는 kube-controller-manager, kube-scheduler 그리고 cloud-controller-manager의 버전은 1.30 이어야 한다(이것은 기존 API서버 버전보다 최신 버전이 아니고 새로운 API서버 버전의 마이너 1개의 버전 내에 있음을 보장한다).
• 모든 kubelet 인스턴스는 버전 1.30 또는 1.29 이어야 한다(이것은 기존 API서버 버전보다 최신 버전이 아니며, 새로운 API서버 버전의 2개의 마이너 버전 내에 있음을 보장한다).
• 등록된 어드미션 웹훅은 새로운 kube-apiserver 인스턴스가 전송하는 데이터를 처리할 수 있다:
  • ValidatingWebhookConfiguration 그리고 MutatingWebhookConfiguration 오브젝트는 1.31 에 추가된 REST 리소스의 새 버전을 포함하도록 업데이트한다(또는 v1.15 이상에서 사용 가능한 matchPolicy: Equivalent option 설정을 사용).
  • 웹훅은 자신에게 전송될 REST리소스의 새버전과 1.31 에서 기존 버전에 추가된 새로운 필드를 처리할 수 있다.

kube-apiserver를 1.31 으로 업그레이드

kube-controller-manager, kube-scheduler 그리고 cloud-controller-manager

사전 요구 사항:

• kube-apiserver 인스턴스는 1.31 이여야 한다(HA 클러스터에서 kube-apiserver 인스턴스와 통신할 수 있는 구성 요소를 업그레이드 전에 모든 kube-apiserver 인스턴스는 업그레이드되어야 한다).

kube-controller-manager, kube-scheduler 및 cloud-controller-manager 를 1.31 으로 업그레이드한다. kube-controller-manager, kube-scheduler 및 cloud-controller-manager 사이에는 업그레이드에 우선순위가 없다. 이 구성 요소들을 임의의 순서 또는 심지어 동시에 업그레이드해도 된다.

kubelet

사전 요구 사항

• kubelet과 통신하는 kube-apiserver 인스턴스는 1.31 이어야 한다.

필요에 따라서 kubelet 인스턴스를 1.31 으로 업그레이드할 수 있다(또는 1.30 아니면 1.29 으로 유지할 수 있음).

예시

kubelet 마이너 버전 업그레이드를 수행하기 전에, 해당 노드의 파드를 드레인(drain)해야 한다. 인플레이스(In-place) 마이너 버전 kubelet 업그레이드는 지원되지 않는다.

클러스터 안의 kubelet 인스턴스를 kube-apiserver의 버전보다 2단계 낮은 버전으로 실행하는 것을 권장하지 않는다:

• kube-apiserver를 업그레이드한다면 한 단계 낮은 버전으로 업그레이드해야 한다.
• 이것은 관리되고 있는 3단계의 마이너 버전보다 낮은 kubelet을 실행할 가능성을 높인다.

kube-proxy

• kube-proxy는 반드시 kubelet과 동일한 마이너 버전이어야 한다.
• kube-proxy는 반드시 kube-apiserver 보다 최신 버전이면 안 된다.
• kube-proxy는 kube-apiserver 보다 2단계 낮은 마이너 버전 이내여야 한다.

kube-proxy 버전이 1.29 인 경우:

• kubelet 버전도 반드시 1.29 와 동일한 마이너 버전이어야 한다.
• kube-apiserver 버전은 반드시 1.29 에서 1.31 사이 이어야 한다.

kubeadm 클러스터 업그레이드

HA 클러스터를 기준으로 다룬다. 
컨트롤플레인 -> 추가 컨트롤플레인 -> 워커노드 

공식문서: https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/

업그레이드할 버전 찾기 

OS 패키지 관리자를 사용하여 최신 패치 릴리스(Kubernetes 1.31)를 찾는다. 

# Find the latest 1.31 version in the list.
# It should look like 1.31.x-*, where x is the latest patch.
sudo apt update
sudo apt-cache madison kubeadm

 컨트롤 플레인 노드의 업그레이드는 한번에 한 노드씩 실행해야 한다. 

첫 번째 컨트롤 플레인 경우 

kubeadm 업그레이드

• 우분투, 데비안 또는 HypriotOS
• CentOS, RHEL 또는 Fedora

# replace x in 1.31.x-* with the latest patch version
sudo apt-mark unhold kubeadm && \
sudo apt-get update && sudo apt-get install -y kubeadm='1.31.x-*' && \
sudo apt-mark hold kubeadm

다운로드가 작동하고 예상된 버전인지 확인

kubeadm version

업그레이드 계획을 확인

sudo kubeadm upgrade plan

이 명령은 클러스터를 업그레이드할 수 있는지 확인하고 업그레이드할 수 있는 버전을 가져온다. 또한 구성 요소 구성 버전 상태가 있는 표도 표시한다. 

 

업그레이드할 버전을 선택하고 적절한 명령을 실행한다. 

# replace x with the patch version you picked for this upgrade
sudo kubeadm upgrade apply v1.31.x

명령이 완료되면 다음이 표시된다. 

[upgrade/successful] SUCCESS! Your cluster was upgraded to "v1.31.x". Enjoy!

[upgrade/kubelet] Now that your control plane is upgraded, please proceed with upgrading your kubelets if you haven't already done so.

CNI 공급자 플러그인을 수동으로 업그레이드한다.CNI 공급자가 DaemonSet으로 실행되는 경우 추가 제어 평면 노드에서는 이 단계가 필요하지 않는다.

컨테이너 네트워크 인터페이스(CNI) 제공자는 따라야 할 자체 업그레이드 지침을 가지고 있을 수 있다. 애드온 페이지를 확인하여 귀하의 CNI 제공자를 찾고 추가 업그레이드 단계가 필요한지 확인한다. 

다른 컨트롤 플레인 노드의 경우

첫 번째 제어 평면 노드와 동일하지만 다음을 사용합니다.

sudo kubeadm upgrade node

대신에

sudo kubeadm upgrade apply

kubeadm upgrade plan CNI 공급자 플러그인을 호출 하고 업그레이드하는 것도 더 이상 필요하지 않다.

노드 drain

노드를 예약 불가능으로 표시하고 작업 부하를 제거하여 유지 관리를 위해 준비한다. 

# replace <node-to-drain> with the name of your node you are draining
kubectl drain <node-to-drain> --ignore-daemonsets

kubelet 및 kubectl 업그레이드

전체 컨트롤 플레인 노드엣허 kubelet과 kubectl을 업그레이드한다. 

# replace x in 1.31.x-* with the latest patch version
sudo apt-mark unhold kubelet kubectl && \
sudo apt-get update && sudo apt-get install -y kubelet='1.31.x-*' kubectl='1.31.x-*' && \
sudo apt-mark hold kubelet kubectl

kubelet을 다시 시작한다. 

sudo systemctl daemon-reload
sudo systemctl restart kubelet

노드 uncordon

노드를 예약 가능으로 표시하여 다시 온라인 상태로 전환한다. 

# replace <node-to-uncordon> with the name of your node
kubectl uncordon <node-to-uncordon>

워커 노드 업그레이드

작업자 노드의 업그레이드 절차는 작업 부하를 실행하는 데 필요한 최소한의 용량을 손상하지 않으면서 한 번에 하나의 노드 또는 여러 노드씩 실행해야 한다. 

공식문서: https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/upgrading-linux-nodes/

kubeadm 업그레이드

kubeadm 업그레이드

• 우분투, 데비안 또는 HypriotOS
• CentOS, RHEL 또는 Fedora

# replace x in 1.31.x-* with the latest patch version
sudo apt-mark unhold kubeadm && \
sudo apt-get update && sudo apt-get install -y kubeadm='1.31.x-*' && \
sudo apt-mark hold kubeadm

작업자 노드의 경우 로컬 kubelet 구성이 업그레이드된다. 

sudo kubeadm upgrade node

노드 drain

노드를 예약 불가능으로 표시하고 작업 부하를 제거하여 유지 관리를 위해 준비한다. 

# execute this command on a control plane node
# replace <node-to-drain> with the name of your node you are draining
kubectl drain <node-to-drain> --ignore-daemonsets

kubelet 및 kubectl 업그레이드

우분투, 데비안 또는 HypriotOS

CentOS, RHEL 또는 Fedora

# replace x in 1.31.x-* with the latest patch version
sudo apt-mark unhold kubelet kubectl && \
sudo apt-get update && sudo apt-get install -y kubelet='1.31.x-*' kubectl='1.31.x-*' && \
sudo apt-mark hold kubelet kubectl

kubelet을 다시 시작한다. 

sudo systemctl daemon-reload
sudo systemctl restart kubelet

노드 uncordon

노드를 예약 가능으로 표시하여 다시 온라인 상태로 전환합니다.

# execute this command on a control plane node
# replace <node-to-uncordon> with the name of your node
kubectl uncordon <node-to-uncordon>

모든 노드에서 kubelet이 업그레이드된 후 kubectl이 클러스터에 액세스할 수 있는 모든 위치에서 다음 명령을 실행하여 모든 노드를 다시 사용할 수 있는지 확인한다.

kubectl get nodes

모든 노드에 대한 열이 표시되어야 하며 버전 번호도 업데이트되어야 합니다 STATUS.Ready

작동 원리

kubeadm upgrade apply다음을 수행한다.

• 클러스터가 업그레이드 가능한 상태인지 확인한다.
  • API 서버에 접속 가능하다.
  • 모든 노드가 Ready상태 에 있다.
  • 제어 평면이 정상이다.
• 버전 왜곡 정책을 시행한다.
• 제어 평면 이미지를 사용할 수 있거나 머신으로 가져올 수 있는지 확인한다. 
• 구성 요소 구성에 버전 업그레이드가 필요한 경우 대체 항목을 생성하거나 사용자가 제공한 덮어쓰기를 사용한다.
• 제어 평면 구성 요소를 업그레이드하거나, 이 중 하나라도 실패하면 롤백한다. 
• 새로운 매니페스트를 적용 CoreDNS하고 kube-proxy모든 필수 RBAC 규칙이 생성되었는지 확인한다.
• API 서버의 새로운 인증서와 키 파일을 만들고, 180일 후에 만료되는 경우 이전 파일을 백업한다. 

kubeadm upgrade node 추가 제어 평면 노드에서 다음을 수행한다.

• ClusterConfiguration클러스터에서 kubeadm을 가져온다.
• 선택적으로 kube-apiserver 인증서를 백업한다. 
• 제어 평면 구성 요소에 대한 정적 Pod 매니페스트를 업그레이드한다.
• 이 노드에 대한 kubelet 구성을 업그레이드한다.

kubeadm upgrade node 작업자 노드에서 다음을 수행한다.

• ClusterConfiguration클러스터에서 kubeadm을 가져온다.
• 이 노드에 대한 kubelet 구성을 업그레이드한다.