kubeadm upgrade
원문: kubeadm upgrade · The Kubernetes Authors · CC BY 4.0
이 문서는 원문을 학습 목적으로 재구성하고 역자 주와 다이어그램을 더했다. 두괄식 종합 결론을 선두에 두고 대응 도형 없는 다이어그램을 실었다. 문서 본문은 CC BY 4.0을 따른다. 비공식 번역이며 원저작자와 프로젝트의 공인을 받지 않았다. 원문과 번역이 어긋날 경우 원문이 우선한다.
원문 시점 2024-08-17 · 번역 2026-07-09
결론
kubeadm upgrade는 복잡한 업그레이드 로직을 한 명령으로 감싼 사용자 친화 명령이다. 업그레이드 계획과 실제 수행을 모두 지원한다. 네 개의 하위 명령으로 나뉜다. plan은 업그레이드 가능한 버전을 확인하고 클러스터가 업그레이드 가능한지 검증한다. apply는 컨트롤 플레인을 지정 버전으로 업그레이드한다. diff는 정적 Pod 매니페스트에 적용될 변경을 미리 보여준다. node는 노드 단위로 업그레이드한다.
핵심 동작은 다음과 같다. plan과 apply는 admin.conf가 있는 컨트롤 플레인 노드에서만 실행된다. Kubernetes v1.15.0부터 apply와 node는 kubeadm이 관리하는 인증서(kubeconfig에 저장된 것 포함)를 자동 갱신하며, --certificate-renewal=false로 끌 수 있다. apply와 node는 프리플라이트, 컨트롤 플레인 업그레이드, 설정 업로드, kubelet 설정, 애드온, 후처리 순의 페이즈로 진행되고, --skip-phases로 페이즈를 건너뛸 수 있다.
kubeadm upgrade는 복잡한 업그레이드 로직을 한 명령 뒤로 감춘 사용자 친화 명령으로, 업그레이드 계획 수립과 실제 수행을 모두 지원한다.
kubeadm upgrade 안내
kubeadm으로 업그레이드를 수행하는 단계는 이 문서에 정리되어 있다. 구버전 kubeadm은 Kubernetes 웹사이트의 이전 문서 세트를 참조한다.
kubeadm upgrade diff로 정적 Pod 매니페스트에 적용될 변경을 볼 수 있다.
Kubernetes v1.15.0 이상에서 kubeadm upgrade apply와 kubeadm upgrade node는 이 노드에서 kubeadm이 관리하는 인증서(kubeconfig 파일에 저장된 것 포함)도 자동 갱신한다. 이를 원치 않으면 --certificate-renewal=false 플래그를 전달할 수 있다. 인증서 갱신에 대한 자세한 내용은 인증서 관리 문서를 참조한다.
참고:
kubeadm upgrade apply와kubeadm upgrade plan명령에는 레거시--config플래그가 있어, 해당 컨트롤 플레인 노드의 계획 수립이나 업그레이드를 수행하면서 클러스터를 재구성할 수 있다. 다만 업그레이드 워크플로는 이 시나리오를 염두에 두고 설계되지 않았으며, 예상치 못한 결과가 보고된 바 있다.
역자 주 · 검증 원문 최종 수정은 2024-08-17이지만, 하위 명령(plan/apply/diff/node) 구조와 페이즈는 번역 시점(2026-07-09)에도 유효하다. 패키지 v1.36.2 매뉴얼이 동일한
apply페이즈와-y, --yes플래그를 보여준다.kubeadm upgrade node의addon·post-upgrade페이즈는 v1.32에 추가되었고(원문 dump에도 반영),post-upgrade는 현재 no-op으로 릴리스별 후처리를 담는 자리다. 앞서 확인한 대로 현재 안정 버전은 v1.36이다. 출처: kubeadm upgrade phases 문서, Upgrading kubeadm clusters.
kubeadm upgrade plan
개요
업그레이드할 수 있는 버전을 확인하고 현재 클러스터가 업그레이드 가능한지 검증한다. 이 명령은 kubeconfig 파일 admin.conf가 있는 컨트롤 플레인 노드에서만 실행할 수 있다. 인터넷 확인을 건너뛰려면 선택적 [version] 파라미터를 전달한다.
kubeadm upgrade plan [version] [flags]플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--allow-experimental-upgrades | Kubernetes의 불안정 버전을 업그레이드 대안으로 표시하고 alpha/beta/RC(release candidate) 버전으로의 업그레이드를 허용한다. | |
--allow-missing-template-keys | true | true면 템플릿에서 필드나 맵 키가 없을 때 오류를 무시한다. golang과 jsonpath 출력 형식에만 적용된다. |
--allow-release-candidate-upgrades | Kubernetes의 RC 버전을 업그레이드 대안으로 표시하고 RC 버전으로의 업그레이드를 허용한다. | |
--config string | kubeadm 설정 파일 경로. | |
--etcd-upgrade | true | etcd 업그레이드를 수행한다. |
-h, --help | plan 도움말. | |
--ignore-preflight-errors strings | 오류를 경고로 표시할 검사 목록. 예: IsPrivilegedUser,Swap. 값이 all이면 모든 검사의 오류를 무시한다. | |
--kubeconfig string | /etc/kubernetes/admin.conf | 클러스터와 통신할 때 쓸 kubeconfig 파일. 미설정 시 기존 kubeconfig 파일을 표준 위치들에서 탐색할 수 있다. |
-o, --output string | text | 출력 형식. text|json|yaml|kyaml|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-as-json|jsonpath-file 중 하나. |
--print-config | 업그레이드에 쓰일 설정 파일을 출력할지 여부를 지정한다. | |
--show-managed-fields | true면 JSON 또는 YAML 형식으로 오브젝트를 출력할 때 managedFields를 유지한다. |
상위 명령 상속 플래그
| 플래그 | 설명 |
|---|---|
--rootfs string | '실제' 호스트 루트 파일시스템 경로. kubeadm이 지정한 경로로 chroot하게 만든다. |
kubeadm upgrade apply
개요
Kubernetes 클러스터를 지정한 버전으로 업그레이드한다.
apply [version] 명령은 다음 페이즈를 실행한다.
preflight: 업그레이드 전 프리플라이트 검사 실행control-plane: 컨트롤 플레인 업그레이드upload-config: kubeadm·kubelet 설정을 ConfigMap에 업로드/kubeadm: kubeadmClusterConfiguration을 ConfigMap에 업로드/kubelet: kubelet 설정을 ConfigMap에 업로드
kubelet-config: 이 노드의 kubelet 설정 업그레이드bootstrap-token: 부트스트랩 토큰과cluster-infoRBAC 규칙 구성addon: 기본 kubeadm 애드온 업그레이드/coredns: CoreDNS 애드온 업그레이드/kube-proxy: kube-proxy 애드온 업그레이드
post-upgrade: 업그레이드 후 작업 실행
kubeadm upgrade apply [version]
node는 apply에서 upload-config와 bootstrap-token을 제외한 부분집합이다. 두 페이즈는 클러스터 설정 업로드와 부트스트랩 토큰·RBAC 구성이라 첫 컨트롤 플레인 업그레이드에서만 필요하다(논리적 추론에 따른 배치).
플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--allow-experimental-upgrades | Kubernetes의 불안정 버전을 업그레이드 대안으로 표시하고 alpha/beta/RC 버전으로의 업그레이드를 허용한다. | |
--allow-release-candidate-upgrades | Kubernetes의 RC 버전을 업그레이드 대안으로 표시하고 RC 버전으로의 업그레이드를 허용한다. | |
--certificate-renewal | true | 업그레이드 중 변경되는 컴포넌트가 쓰는 인증서의 갱신을 수행한다. |
--config string | kubeadm 설정 파일 경로. | |
--dry-run | 어떤 상태도 바꾸지 않고 수행될 작업만 출력한다. | |
--etcd-upgrade | true | etcd 업그레이드를 수행한다. |
-f, --force | 일부 요구 사항이 충족되지 않아도 강제로 업그레이드한다. 이는 비대화형 모드도 함의한다. | |
-h, --help | apply 도움말. | |
--ignore-preflight-errors strings | 오류를 경고로 표시할 검사 목록. 예: IsPrivilegedUser,Swap. 값이 all이면 모든 검사의 오류를 무시한다. | |
--kubeconfig string | /etc/kubernetes/admin.conf | 클러스터와 통신할 때 쓸 kubeconfig 파일. 미설정 시 기존 kubeconfig 파일을 표준 위치들에서 탐색할 수 있다. |
--patches string | target[suffix][+patchtype].extension 형식의 파일을 담은 디렉터리 경로. 예: kube-apiserver0+merge.yaml 또는 단순히 etcd.json. target은 kube-apiserver, kube-controller-manager, kube-scheduler, etcd, kubeletconfiguration, corednsdeployment 중 하나다. patchtype은 strategic, merge, json 중 하나이며 kubectl이 지원하는 패치 포맷과 대응한다. 기본 patchtype은 strategic이다. extension은 json 또는 yaml이어야 한다. suffix는 패치 적용 순서를 알파벳·숫자순으로 정하는 선택적 문자열이다. | |
--print-config | 업그레이드에 쓰일 설정 파일을 출력할지 여부를 지정한다. | |
--skip-phases strings | 건너뛸 페이즈 목록. | |
-y, --yes | 확인 프롬프트 없이 업그레이드를 수행한다(비대화형 모드). |
상위 명령 상속 플래그
| 플래그 | 설명 |
|---|---|
--rootfs string | '실제' 호스트 루트 파일시스템 경로. kubeadm이 지정한 경로로 chroot하게 만든다. |
kubeadm upgrade diff
개요
기존 정적 Pod 매니페스트에 적용될 차이를 보여준다. 참고: kubeadm upgrade apply --dry-run.
kubeadm upgrade diff [version] [flags]플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--config string | kubeadm 설정 파일 경로. | |
-c, --context-lines int | 3 | diff에 표시할 컨텍스트 줄 수. |
-h, --help | diff 도움말. | |
--kubeconfig string | /etc/kubernetes/admin.conf | 클러스터와 통신할 때 쓸 kubeconfig 파일. 미설정 시 기존 kubeconfig 파일을 표준 위치들에서 탐색할 수 있다. |
상위 명령 상속 플래그
| 플래그 | 설명 |
|---|---|
--rootfs string | '실제' 호스트 루트 파일시스템 경로. kubeadm이 지정한 경로로 chroot하게 만든다. |
kubeadm upgrade node
개요
클러스터 내 노드를 위한 업그레이드 명령.
node 명령은 다음 페이즈를 실행한다.
preflight: 노드 업그레이드 프리플라이트 검사 실행control-plane: 이 노드에 배포된 컨트롤 플레인 인스턴스가 있으면 업그레이드kubelet-config: 이 노드의 kubelet 설정 업그레이드addon: 기본 kubeadm 애드온 업그레이드/coredns: CoreDNS 애드온 업그레이드/kube-proxy: kube-proxy 애드온 업그레이드
post-upgrade: 업그레이드 후 작업 실행
kubeadm upgrade node [flags]플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--certificate-renewal | true | 업그레이드 중 변경되는 컴포넌트가 쓰는 인증서의 갱신을 수행한다. |
--config string | kubeadm 설정 파일 경로. | |
--dry-run | 어떤 상태도 바꾸지 않고 수행될 작업만 출력한다. | |
--etcd-upgrade | true | etcd 업그레이드를 수행한다. |
-h, --help | node 도움말. | |
--ignore-preflight-errors strings | 오류를 경고로 표시할 검사 목록. 예: IsPrivilegedUser,Swap. 값이 all이면 모든 검사의 오류를 무시한다. | |
--kubeconfig string | /etc/kubernetes/admin.conf | 클러스터와 통신할 때 쓸 kubeconfig 파일. 미설정 시 기존 kubeconfig 파일을 표준 위치들에서 탐색할 수 있다. |
--patches string | target[suffix][+patchtype].extension 형식의 파일을 담은 디렉터리 경로. 예: kube-apiserver0+merge.yaml 또는 단순히 etcd.json. target은 kube-apiserver, kube-controller-manager, kube-scheduler, etcd, kubeletconfiguration, corednsdeployment 중 하나다. patchtype은 strategic, merge, json 중 하나이며 kubectl이 지원하는 패치 포맷과 대응한다. 기본 patchtype은 strategic이다. extension은 json 또는 yaml이어야 한다. suffix는 패치 적용 순서를 알파벳·숫자순으로 정하는 선택적 문자열이다. | |
--skip-phases strings | 건너뛸 페이즈 목록. |
상위 명령 상속 플래그
| 플래그 | 설명 |
|---|---|
--rootfs string | '실제' 호스트 루트 파일시스템 경로. kubeadm이 지정한 경로로 chroot하게 만든다. |
역자 주 · 적용
원문 정보와 원문이 링크한 업그레이드 가이드에서 도출되는, 일반 독자 누구에게나 성립하는 실습·활용 안내다.
이 그림은 레퍼런스 본문이 아니라 원문이 링크한 Upgrading kubeadm clusters 절차를 시각화한 것이다(논리적 추론에 따른 배치).
- 클러스터 전체 업그레이드 순서가 정해져 있다. 첫 컨트롤 플레인 노드는
kubeadm upgrade apply <버전>으로, 이후 추가 컨트롤 플레인 노드와 워커 노드는kubeadm upgrade node로 올린다. 한 번에 한 노드씩 진행한다. - 버전 스큐(version skew) 정책상 kubelet은 자신이 통신하는 kube-apiserver보다 최신일 수 없다. 그래서 컨트롤 플레인의 업그레이드를 끝낸 뒤 kubelet을 올린다. 마이너 버전은 건너뛸 수 없다(예: 1.35 → 1.36만 가능, 1.34 → 1.36 불가).
- 실제 변경 전에
--dry-run또는kubeadm upgrade diff로 정적 Pod 매니페스트에 적용될 변경을 먼저 확인한다. kubeadm upgrade는 멱등(idempotent)이다. 실패했는데 롤백되지 않았다면(예: 실행 중 예기치 못한 종료) 다시 실행하면 선언한 목표 상태로 수렴한다.- 이 문서는 init(부트스트랩)·join(합류)에 이은 운영 명령이다.
apply·node가 업그레이드하는 컨트롤 플레인 컴포넌트는 정적 Pod로 떠 있으므로,kubeadm upgrade diff가 보여주는 변경이 바로/etc/kubernetes/manifests의 매니페스트 변경이다. 네 문서(init·join·upgrade·정적 Pod)가 부트스트랩부터 운영까지 한 줄로 이어진다.
참고 출처
원문이 링크한 출처:
역자 검증 출처(번역 시점 사실 확인에 사용):
다음 단계
- kubeadm config: kubeadm v1.7.x 이하로 클러스터를 초기화했다면,
kubeadm upgrade를 위해 클러스터를 구성