클러스터 업그레이드

결론부터

클러스터 업그레이드는 버전 호환 범위 안에서 컨트롤 플레인부터 노드별로 진행한다.

모든 노드의 패키지를 한꺼번에 바꾸면 컴포넌트 간 버전이 어긋나거나 서비스가 중단될 수 있다. 버전 스큐의 이유와 첫 컨트롤 플레인·추가 컨트롤 플레인·워커의 절차 차이를 확인한다.

버전 스큐 규칙 — 업그레이드 순서의 근거

컴포넌트를 한 번에 다 올릴 수는 없다. 올리는 동안에는 필연적으로 새 버전과 옛 버전이 섞여 돈다. 그 섞임이 어디까지 허용되는지를 정한 것이 버전 스큐(version skew) 정책이고, 업그레이드 순서는 전부 여기서 따라 나온다.

모든 컴포넌트가 apiserver하고만 이야기하므로(아키텍처) apiserver가 기준점이고, 나머지는 그보다 낮을 수만 있다.

컴포넌트	허용 범위
kube-apiserver	기준점
controller-manager, scheduler	apiserver보다 1 마이너 낮은 것까지
kubelet	apiserver보다 3 마이너 낮은 것까지
kube-proxy	같은 노드의 kubelet과 동일
kubectl	apiserver ±1 마이너

여기서 두 가지 규칙이 나온다.

1. 컨트롤 플레인을 먼저, 워커를 나중에 올린다 — apiserver가 뒤처지면 kubelet이 허용 범위를 벗어난다
2. 마이너 버전을 건너뛸 수 없다. 1.33 → 1.35 는 불가. 1.33 → 1.34 → 1.35

함정

kubeadm upgrade apply는 두 단계 이상 점프를 거부한다. 시험에서 “1.34에서 1.35로” 처럼 한 단계만 요구하는 이유다.

업그레이드 — 노드 유형별 절차

마이너 업그레이드라면 먼저 공식 Changing The Kubernetes Package Repository에서 저장소 URL을 목표 마이너로 바꾼다. 이어서 Upgrading kubeadm clusters의 노드별 절차를 따라 kubeadm부터 uncordon까지 진행한다.

7단계가 똑같고, 3번만 다르다.

첫 컨트롤 플레인 노드

1. 저장소 URL의 마이너 버전을 바꾼다 — ★ 가장 많이 빠뜨리는 단계

   sudo sed -i 's/v1.34/v1.35/' /etc/apt/sources.list.d/kubernetes.list
   sudo apt-get update
   sudo apt-cache madison kubeadm | head          # 설치 가능한 버전 확인

2. kubeadm 먼저 업그레이드

   sudo apt-mark unhold kubeadm
   sudo apt-get install -y kubeadm=1.35.1-1.1
   sudo apt-mark hold kubeadm
   kubeadm version

3. kubeadm upgrade apply — 컨트롤 플레인 컴포넌트를 교체한다

   sudo kubeadm upgrade plan          # 무엇이 어떻게 바뀌는지 먼저 본다
   sudo kubeadm upgrade apply v1.35.1

4. 노드를 비운다

   kubectl drain controlplane --ignore-daemonsets

5. kubelet, kubectl 업그레이드

   sudo apt-mark unhold kubelet kubectl
   sudo apt-get install -y kubelet=1.35.1-1.1 kubectl=1.35.1-1.1
   sudo apt-mark hold kubelet kubectl

6. kubelet 재시작

   sudo systemctl daemon-reload
   sudo systemctl restart kubelet

7. 다시 스케줄 가능하게

   kubectl uncordon controlplane
   kubectl get nodes

나머지 노드 (컨트롤 플레인 · 워커 공통)

1. 저장소 URL의 마이너 버전을 바꾼다

   sudo sed -i 's/v1.34/v1.35/' /etc/apt/sources.list.d/kubernetes.list
   sudo apt-get update

2. kubeadm 먼저 업그레이드

   sudo apt-mark unhold kubeadm
   sudo apt-get install -y kubeadm=1.35.1-1.1
   sudo apt-mark hold kubeadm

3. kubeadm upgrade node — ★ apply가 아니다. 워커에서는 kubelet 설정만 갱신한다

   sudo kubeadm upgrade node

4. 노드를 비운다 — kubectl이 있는 곳(컨트롤 플레인)에서

   kubectl drain node01 --ignore-daemonsets

5. kubelet, kubectl 업그레이드 — 대상 노드에 ssh해서

   sudo apt-mark unhold kubelet kubectl
   sudo apt-get install -y kubelet=1.35.1-1.1 kubectl=1.35.1-1.1
   sudo apt-mark hold kubelet kubectl

6. kubelet 재시작

   sudo systemctl daemon-reload
   sudo systemctl restart kubelet

7. 다시 스케줄 가능하게 — 컨트롤 플레인 노드에서

   kubectl uncordon node01

• kubeadm upgrade apply는 kubelet을 올려주지 않는다. 별도 단계다
• systemctl daemon-reload를 빠뜨리면 새 설정이 반영되지 않는다

함정

1번을 안 하면 apt-get install kubeadm=1.35.x가 “버전을 찾을 수 없다”고 실패한다. 저장소가 여전히 1.34만 보고 있기 때문이다.

시험

drain/uncordon은 kubectl이 있는 곳에서, 패키지 설치는 대상 노드에 ssh해서 한다. 어디서 무엇을 치는지 헷갈리기 쉽다.

업그레이드 순서 요약 — 이것만 외우면 된다

차이는 3번 하나뿐이다. 첫 노드만 apply, 나머지는 전부 node.

kubectl get nodes          # 전부 새 VERSION 인지 확인 — 이게 채점 기준이다

요약

• 클러스터 업그레이드는 버전 호환 범위 안에서 컨트롤 플레인부터 노드별로 진행한다.
• 첫 컨트롤 플레인은 kubeadm upgrade apply, 나머지는 kubeadm upgrade node를 쓴다.
• 각 노드에서 drain → 업그레이드 → kubelet 재시작 → uncordon과 상태 확인을 수행한다.