클러스터 업그레이드

kubeadm 기반 Kubernetes 클러스터의 무중단 업그레이드 절차

kubeadm 기반 Kubernetes 클러스터의 무중단 업그레이드 절차

목표: 프로덕션 환경에서 안전하게 업그레이드할 수 있는 수준

🔄 업그레이드 전략

버전 정책

Kubernetes: 마이너 버전 1개씩 (1.28 → 1.29)
컴포넌트: kubelet은 API Server보다 최대 2버전 낮을 수 있음
순서: Control Plane → Worker Node

업그레이드 순서

[백업] ──> [CP 1] ──> [CP 2,3] ──> [Workers]
   │         │           │            │
   │         ▼           ▼            ▼
   │      drain      uncordon      drain
   │      upgrade    upgrade       upgrade
   │      uncordon   uncordon      uncordon
   │
   └──> etcd, 설정, 인증서

📋 사전 준비

백업

# 1. etcd 백업
sudo ETCDCTL_API=3 etcdctl snapshot save etcd-backup-$(date +%Y%m%d).db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

# 2. 설정 백업
sudo cp -r /etc/kubernetes /etc/kubernetes.backup

# 3. 현재 버전 확인
kubectl version
kubeadm version

업그레이드 계획

# 업그레이드 가능한 버전 확인
sudo kubeadm upgrade plan

# 출력 예시:
# Components that must be upgraded manually after you have upgraded the control plane with 'kubeadm upgrade apply':
# COMPONENT   CURRENT       AVAILABLE
# kubelet     1.28.2        1.29.0
# 
# Upgrade to the latest stable version:
# COMPONENT                 CURRENT   AVAILABLE
# kube-apiserver            1.28.2    1.29.0
# kube-controller-manager   1.28.2    1.29.0
# kube-scheduler            1.28.2    1.29.0
# kube-proxy                1.28.2    1.29.0

🎛️ Control Plane 업그레이드

1단계: 첫 번째 Control Plane

# 1. drain
kubectl drain cp-1 --ignore-daemonsets --delete-emptydir-data

# 2. 패키지 업데이트
sudo apt-mark unhold kubeadm kubectl && \
sudo apt-get update && \
sudo apt-get install -y kubeadm=1.29.0-00 kubectl=1.29.0-00 && \
sudo apt-mark hold kubeadm kubectl

# 3. 업그레이드 적용
sudo kubeadm upgrade apply v1.29.0

# 4. kubelet 업그레이드
sudo apt-mark unhold kubelet && \
sudo apt-get update && \
sudo apt-get install -y kubelet=1.29.0-00 && \
sudo apt-mark hold kubelet

sudo systemctl daemon-reload
sudo systemctl restart kubelet

# 5. uncordon
kubectl uncordon cp-1

2단계: 추가 Control Plane (HA)

# 1. drain
kubectl drain cp-2 --ignore-daemonsets --delete-emptydir-data

# 2. 패키지 업데이트
sudo apt-mark unhold kubeadm kubectl kubelet && \
sudo apt-get update && \
sudo apt-get install -y kubeadm=1.29.0-00 kubectl=1.29.0-00 kubelet=1.29.0-00 && \
sudo apt-mark hold kubeadm kubectl kubelet

# 3. node 업그레이드
sudo kubeadm upgrade node

# 4. kubelet 재시작
sudo systemctl daemon-reload
sudo systemctl restart kubelet

# 5. uncordon
kubectl uncordon cp-2

👷 Worker Node 업그레이드

# 1. drain
kubectl drain worker-1 --ignore-daemonsets --delete-emptydir-data

# 2. SSH 접속
ssh worker-1

# 3. 패키지 업데이트
sudo apt-mark unhold kubeadm kubectl kubelet && \
sudo apt-get update && \
sudo apt-get install -y kubeadm=1.29.0-00 kubectl=1.29.0-00 kubelet=1.29.0-00 && \
sudo apt-mark hold kubeadm kubectl kubelet

# 4. node 업그레이드
sudo kubeadm upgrade node

# 5. kubelet 재시작
sudo systemctl daemon-reload
sudo systemctl restart kubelet

# 6. uncordon
exit
kubectl uncordon worker-1

✅ 업그레이드 확인

# 버전 확인
kubectl version
kubectl get nodes

# 컴포넌트 확인
kubectl get pods -n kube-system

# 기능 테스트
kubectl run test --image=nginx
kubectl get pod test
kubectl delete pod test

🐛 문제 해결

업그레이드 실패

# kubeadm 상태 확인
sudo kubeadm upgrade plan

# 로그 확인
sudo journalctl -u kubelet -f

# 인증서 문제
sudo kubeadm certs check-expiration
sudo kubeadm certs renew all

# 되돌리기 (백업에서)
sudo cp -r /etc/kubernetes.backup /etc/kubernetes
sudo systemctl restart kubelet

📋 체크리스트

🔗 관련 노트

02-01-kubeadm-클러스터-설치 — 초기 설치
02-12-클러스터-장애-복구 — 장애 대응
CKA-기출문제 — 시험 문제

마지막 업데이트: 2026-06-01