kubeadm 클러스터 업그레이드

kubeadm 클러스터 업그레이드 (Upgrading kubeadm clusters)

이 페이지는 kubeadm으로 만든 Kubernetes 클러스터를 1.36.x에서 1.37.x로, 그리고 1.37.x에서 1.37.y(y > x)로 업그레이드하는 방법을 설명해요. 업그레이드할 때 MINOR 버전을 건너뛰는 것은 지원되지 않아요. 자세한 내용은 버전 스큐 정책을 참고해요.

더 오래된 버전의 kubeadm으로 만든 클러스터를 업그레이드하는 방법은 다음 페이지를 대신 참고해요.

Kubernetes 프로젝트는 최신 패치 릴리스로 신속하게 업그레이드하고, 지원되는 소수의 Kubernetes 릴리스(minor release)를 실행 중인지 확인할 것을 권장해요. 이 권장 사항을 따르면 안전하게 유지하는 데 도움이 돼요.

업그레이드 워크플로는 높은 수준에서 다음과 같아요.

  1. 주 컨트롤 플레인 노드 업그레이드
  2. 추가 컨트롤 플레인 노드 업그레이드
  3. 워커 노드 업그레이드

출처: 문서

본문

시작하기 전에

  • 릴리스 노트를 주의 깊게 읽었는지 확인해요.
  • 클러스터는 정적(static) 컨트롤 플레인과 etcd 파드 또는 외부 etcd를 사용해야 해요.
  • 데이터베이스에 저장된 앱 수준 상태 같은 중요한 컴포넌트를 백업했는지 확인해요. kubeadm upgrade는 워크로드를 건드리지 않고 Kubernetes 내부 컴포넌트만 건드리지만, 백업은 항상 모범 사례예요.
  • 스왑(swap)을 비활성화해야 해요.

추가 정보

  • 아래 지침은 업그레이드 과정에서 각 노드를 언제 drain할지 설명해요. kubelet에 대한 마이너 버전 업그레이드를 수행한다면 업그레이드하는 노드(또는 노드들)를 먼저 drain해야 해요. 컨트롤 플레인 노드의 경우 CoreDNS 파드나 다른 중요한 워크로드를 실행 중일 수 있어요. 자세한 내용은 노드 drain 참고.
  • Kubernetes 프로젝트는 kubelet과 kubeadm 버전을 일치시킬 것을 권장해요. 대신 지원되는 버전 범위 내에 있다면 kubeadm보다 오래된 kubelet 버전을 사용할 수도 있어요. 자세한 내용은 kubeadm과 kubelet의 스큐 참고.
  • 컨테이너 스펙 해시 값이 변경되므로 업그레이드 후 모든 컨테이너가 재시작돼요.
  • kubelet이 업그레이드된 후 kubelet 서비스가 성공적으로 재시작되었는지 확인하려면 systemctl status kubelet을 실행하거나 journalctl -xeu kubelet으로 서비스 로그를 볼 수 있어요.
  • kubeadm upgrade는 업그레이드 과정을 구성하는 데 사용할 수 있는 UpgradeConfiguration API 유형과 함께 --config를 지원해요.
  • kubeadm upgrade는 기존 클러스터의 재구성(reconfiguration)을 지원하지 않아요. kubeadm 클러스터 재구성의 단계를 대신 따라야 해요.

etcd 업그레이드 시 고려 사항

kube-apiserver 정적 파드는 (노드를 drain했더라도) 항상 실행 중이므로, etcd 업그레이드를 포함한 kubeadm upgrade를 수행하면 새 etcd 정적 파드가 재시작되는 동안 서버로의 진행 중 요청이 지연돼요. 해결 방법으로, kubeadm upgrade apply 명령을 시작하기 몇 초 전에 kube-apiserver 프로세스를 적극적으로 중지할 수 있어요. 이것은 진행 중 요청을 완료하고 기존 연결을 닫게 하여, etcd 다운타임의 영향을 최소화해요. 컨트롤 플레인 노드에서 다음과 같이 할 수 있어요.

killall -s SIGTERM kube-apiserver # trigger a graceful kube-apiserver shutdown
sleep 20 # wait a little bit to permit completing in-flight requests
kubeadm upgrade ... # execute a kubeadm upgrade command

패키지 저장소 변경

커뮤니티 소유 패키지 저장소(pkgs.k8s.io)를 사용한다면 원하는 Kubernetes minor 릴리스에 대한 패키지 저장소를 활성화해야 해요. 이것은 Kubernetes 패키지 저장소 변경 문서에 설명되어 있어요.

업그레이드할 버전 결정

OS 패키지 관리자로 Kubernetes 1.37의 최신 패치 릴리스를 찾아요.

  • Ubuntu, Debian 또는 HypriotOS
  • CentOS, RHEL 또는 Fedora

DNF4(Fedora < 41, RHEL/CentOS < 10) 시스템:

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

# Find the latest 1.37 version in the list.
# It should look like 1.37.x-*, where x is the latest patch.
sudo dnf list --showduplicates kubeadm --disableexcludes=kubernetes

DNF5 시스템:

# Find the latest 1.37 version in the list.
# It should look like 1.37.x-*, where x is the latest patch.
sudo dnf list --showduplicates kubeadm --setopt=disable_excludes=kubernetes

업그레이드할 것으로 기대하는 버전이 보이지 않으면, Kubernetes 패키지 저장소가 사용되는지 확인해요.

컨트롤 플레인 노드 업그레이드

컨트롤 플레인 노드의 업그레이드 절차는 한 번에 노드 하나씩 실행해야 해요. 먼저 업그레이드하고 싶은 컨트롤 플레인 노드를 고르세요. 그것은 /etc/kubernetes/admin.conf 파일이 있어야 해요.

"kubeadm upgrade" 호출

첫 컨트롤 플레인 노드의 경우

  1. kubeadm 업그레이드: Ubuntu, Debian 또는 HypriotOS / CentOS, RHEL 또는 Fedora. DNF4 시스템의 경우: / DNF5 시스템의 경우:
  2. 다운로드가 동작하고 예상된 버전인지 확인해요.
  3. 업그레이드 계획을 확인해요. 이 명령은 클러스터를 업그레이드할 수 있는지 확인하고, 업그레이드할 수 있는 버전을 가져와요. 컴포넌트 구성 버전 상태가 있는 표도 보여줘요. 참고: kubeadm upgrade는 이 노드에서 관리하는 인증서도 자동으로 갱신해요. 인증서 갱신을 원하지 않으면 --certificate-renewal=false 플래그를 사용할 수 있어요. 자세한 내용은 인증서 관리 가이드 참고.
  4. 업그레이드할 버전을 선택하고 적절한 명령을 실행해요. 명령이 끝나면 다음을 볼 수 있어요. 참고: v1.28보다 이전 버전의 경우 kubeadm은 다른 업그레이드되지 않은 컨트롤 플레인 인스턴스가 있는지와 무관하게 kubeadm upgrade apply 중에 즉시 애드온(CoreDNS와 kube-proxy 포함)을 업그레이드하는 모드로 기본 설정되었어요. 이것은 호환성 문제를 일으킬 수 있어요. v1.28부터 kubeadm은 모든 컨트롤 플레인 인스턴스가 업그레이드되었는지 확인한 후 애드온 업그레이드를 시작하는 모드로 기본 설정됩니다. 컨트롤 플레인 인스턴스 업그레이드를 순차적으로 수행하거나, 적어도 다른 모든 컨트롤 플레인 인스턴스가 완전히 업그레이드될 때까지 마지막 컨트롤 플레인 인스턴스 업그레이드를 시작하지 않도록 하고, 애드온 업그레이드는 마지막 컨트롤레 플레인 인스턴스가 업그레이드된 후 수행되도록 해야 해요.
  5. CNI 프로바이더 플러그인을 수동으로 업그레이드해요. Container Network Interface(CNI) 프로바이더는 따라야 할 자체 업그레이드 지침이 있을 수 있어요. 애드온 페이지를 확인해 CNI 프로바이더를 찾고 추가 업그레이드 단계가 필요한지 보세요. CNI 프로바이더가 DaemonSet으로 실행된다면 추가 컨트롤 플레인 노드에서는 이 단계가 필요하지 않아요.

다른 컨트롤 플레인 노드의 경우 첫 컨트롤 플레인 노드와 같지만, 다음을 사용해요.

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 업그레이드

Linux 노드에서 kubelet은 기본적으로 cgroups v2만 지원해요. Kubernetes 1.37의 경우 FailCgroupV1 kubelet 구성 옵션이 기본으로 true로 설정돼요. 더 배우려면 Kubernetes cgroup v1 사용 중단 문서를 참고해요.

  1. kubelet과 kubectl 업그레이드: Ubuntu, Debian 또는 HypriotOS / CentOS, RHEL 또는 Fedora. DNF4 시스템의 경우: / DNF5 시스템의 경우:
  2. kubelet 재시작:

노드 uncordon

노드를 스케줄 가능으로 표시해 다시 온라인으로 전환해요.

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

워커 노드 업그레이드

워커 노드의 업그레이드 절차는 워크로드를 실행하는 데 필요한 최소 용량을 손상시키지 않으면서 한 번에 노드 하나씩 또는 몇 개씩 실행해야 해요.

다음 페이지들이 Linux와 Windows 워커 노드를 업그레이드하는 방법을 보여줘요.

클러스터 상태 확인

모든 노드에서 kubelet이 업그레이드된 후, kubectl이 클러스터에 접근할 수 있는 어디서든 다음 명령을 실행해 모든 노드가 다시 가용한지 확인해요.

kubectl get nodes

STATUS 열이 모든 노드에 대해 Ready를 보여주고, 버전 번호가 업데이트되어야 해요.

실패 상태에서 복구

kubeadm upgrade가 실패하고 롤백되지 않으면, 예를 들어 실행 중 예기치 않은 종료가 발생한 경우, kubeadm upgrade를 다시 실행할 수 있어요. 이 명령은 멱등적이며, 결국 실제 상태를 선언한 원하는 상태로 만드는 것을 보장해요.

나쁜 상태에서 복구하려면, 클러스터가 실행 중인 버전을 변경하지 않고 sudo kubeadm upgrade apply --force를 실행할 수도 있어요.

업그레이드 중 kubeadm은 /etc/kubernetes/tmp 아래에 다음 백업 폴더를 써요.

  • kubeadm-backup-etcd-<date>-<time>
  • kubeadm-backup-manifests-<date>-<time>

kubeadm-backup-etcd는 이 컨트롤 플레인 노드의 로컬 etcd 멤버 데이터 백업을 포함해요. etcd 업그레이드 실패 시 자동 롤백이 동작하지 않으면 이 폴더의 내용을 /var/lib/etcd에 수동으로 복원할 수 있어요. 외부 etcd를 사용하는 경우 이 백업 폴더는 비어 있을 거예요.

kubeadm-backup-manifests는 이 컨트롤 플레인 노드의 정적 파드 매니페스트 파일 백업을 포함해요. 업그레이드 실패 시 자동 롤백이 동작하지 않으면 이 폴더의 내용을 /etc/kubernetes/manifests에 수동으로 복원할 수 있어요. 어떤 이유로 특정 컴포넌트의 업그레이드 전·후 매니페스트 파일 사이에 차이가 없다면, 그 컴포넌트의 백업 파일은 작성되지 않아요.

작동 방식

kubeadm upgrade apply는 다음을 수행해요.

  • 클러스터가 업그레이드 가능한 상태인지 확인: API 서버에 접근 가능, 모든 노드가 Ready 상태, 컨트롤 플레인이 건강함
  • 버전 스큐 정책 강제
  • 컨트롤 플레인 이미지가 사용 가능하거나 머신으로 가져올 수 있는지 확인
  • 컴포넌트 구성이 버전 업그레이드를 요구하면 대체물 생성 및/또는 사용자 제공 덮어쓰기 사용
  • 컨트롤 플레인 컴포넌트 업그레이드, 또는 하나라도 올라오지 못하면 롤백
  • 새 CoreDNS와 kube-proxy 매니페스트 적용 및 필요한 모든 RBAC 규칙이 생성되는지 확인
  • API 서버의 새 인증서·키 파일 생성 및 180일 내에 만료될 예정이면 기존 파일 백업

kubeadm upgrade node는 추가 컨트롤 플레인 노드에서 다음을 수행해요.

  • 클러스터에서 kubeadm ClusterConfiguration 가져오기
  • 선택적으로 kube-apiserver 인증서 백업
  • 컨트롤 플레인 컴포넌트의 정적 파드 매니페스트 업그레이드
  • 이 노드의 kubelet 구성 업그레이드

kubeadm upgrade node는 워커 노드에서 다음을 수행해요.

  • 클러스터에서 kubeadm ClusterConfiguration 가져오기
  • 이 노드의 kubelet 구성 업그레이드

더 알아보기 (Learn more)