
지금까지 배운 Ansible 기능들을 총동원하여, Kubernetes 클러스터의 버전 업그레이드를 자동화하는 playbook을 구현합니다. 실제 K8s 클러스터는 없지만 Docker 환경의 node1~3으로 업그레이드 절차를 시뮬레이션하며, K8s 업그레이드의 핵심 개념과 순서를 함께 정리합니다.
6대 노드(Control Plane 3 + Worker 3) 클러스터를 기준으로, 업그레이드는 반드시 다음 순서를 따릅니다:
CP 01 (init) → CP 02, 03 (join) → Worker 01, 02, 03
역순이나 동시 진행은 불가합니다.
apt repo 변경 (v1.30 → v1.31)
→ kubeadm 업그레이드 + hold
→ kubeadm upgrade plan ← 사전 확인 (dry-run 성격)
→ kubeadm upgrade apply v1.31 ← 클러스터 레벨 업그레이드
→ kubelet, kubectl 업그레이드 + hold
→ systemctl restart kubelet
→ Ready 대기
upgrade apply가 하는 일:
apply가 아님drain 안 하는 이유: CP에는 taint(node-role.kubernetes.io/control-plane:NoSchedule)가 걸려있어서 일반 Pod이 스케줄되지 않습니다. 퇴거시킬 워크로드가 없습니다.
apt repo 변경
→ kubeadm 업그레이드 + hold
→ kubeadm upgrade node ← 로컬 컴포넌트만
→ kubelet, kubectl 업그레이드 + hold
→ systemctl restart kubelet
→ Ready 대기
→ 다음 노드
upgrade node가 하는 일:
한 대씩 하는 이유: etcd quorum 유지. 3대 중 과반수(2대)가 항상 정상이어야 합니다. 동시에 2대를 내리면 quorum을 잃고 클러스터가 먹통됩니다.
kubectl drain <node> ← CP에서 실행 (Pod 퇴거)
→ apt repo 변경
→ kubeadm 업그레이드 + hold
→ kubeadm upgrade node
→ kubelet, kubectl 업그레이드 + hold
→ systemctl restart kubelet
→ kubectl uncordon <node> ← CP에서 실행 (스케줄링 재개)
→ Ready 대기
→ 다음 노드
drain이 필요한 이유: Worker에는 실제 워크로드(Pod)가 돌고 있습니다. drain으로 Pod을 퇴거시킨 뒤 업그레이드해야 서비스 중단이 없습니다.
한 대씩 하는 이유: 동시에 여러 Worker를 drain하면 Pod을 받아줄 노드가 부족해져서 서비스 장애가 발생합니다.
kubectl drain이 완료되었다는 것은:
여기까지입니다. 퇴거된 Pod이 다른 노드에 정상 배치되었는지는 drain이 관여하지 않습니다.
다른 노드에 재배치되는 건 별개 흐름입니다:
따라서 안전하게 하려면 drain 후에 워크로드 정상 여부를 별도로 확인해야 합니다:
- name: drain
shell: kubectl drain {{ inventory_hostname }} --ignore-daemonsets --delete-emptydir-data
delegate_to: node1
- name: wait for workload ready
shell: kubectl get pods -A --field-selector spec.nodeName!={{ inventory_hostname }} | grep -v Running
register: pod_check
until: pod_check.stdout_lines | length <= 1
retries: 10
delay: 10
delegate_to: node1
drain 자체의 동작은 아니고, playbook에서 선택적으로 추가하는 안전 장치입니다.
$ dpkg --get-selections | grep kube
kubeadm hold
kubectl hold
kubelet hold
K8s 컴포넌트에 hold를 걸어두면 apt upgrade 시 실수로 버전이 올라가는 것을 방지합니다. 업그레이드 절차에서 unhold → 설치 → hold 순서로 관리합니다.
hold 해제 시 selection: unhold는 존재하지 않으며, selection: install로 설정합니다 (Chap 7에서 다룸).
| Phase | 대상 | 명령 | drain | serial | 이유 |
|---|---|---|---|---|---|
| 1 | CP 01 (1대) | upgrade apply |
X | - | 클러스터 레벨 업그레이드 (1회) |
| 2 | CP 02~03 | upgrade node |
X | 1대씩 | etcd quorum 유지 |
| 3 | Worker 01~03 | upgrade node |
O | 1대씩 | 워크로드 가용성 유지 |
실제 K8s 클러스터가 없으므로, Docker 환경의 node1~3으로 시뮬레이션합니다.
| 실제 K8s | Docker 환경 | 역할 |
|---|---|---|
| control-plane01 | node1 | kubeadm upgrade apply 실행 노드 |
| control-plane02 | node2 | kubeadm upgrade node 실행 노드 |
| worker-node01 | node3 | drain → upgrade → uncordon |
inventory_kube.ini:
[control_plane_init]
node1
[control_plane_join]
node2
[control_plane:children]
control_plane_init
control_plane_join
[workers]
node3
[all:vars]
ansible_user=ansible
ansible_password=ansible
ansible_become=yes
children 키워드로 control_plane_init과 control_plane_join을 control_plane 그룹으로 묶습니다.
$ ansible-inventory -i inventory_kube.ini --graph
@all:
|--@ungrouped:
|--@control_plane:
| |--@control_plane_init:
| | |--node1
| |--@control_plane_join:
| | |--node2
|--@workers:
| |--node3
playbook/upgrade_k8s.yml — 3개의 play로 구성됩니다.
---
- name: Phase1
hosts: control_plane_init
become: true
gather_facts: false
serial: 1
tasks:
- name: start msg
debug:
msg: "Phase 1: 첫 번째 CP 업그레이드 시작 ({{ target_version }})"
- name: apt upgrade
shell: "echo 'apt repo changed to v{{ target_version }}'"
register: apt_repo_result
- name: kubeadm upgrade
shell: "echo 'kubeadm upgrade apply v{{ target_version }}'"
register: kubeadm_result
- name: debug
debug:
msg: "{{ apt_repo_result.stdout }}\n{{ kubeadm_result.stdout }}"
- name: kubelet restart
shell: "echo 'kubelet restarted'"
- name: node ready
shell: "echo '{{ inventory_hostname }} Ready'"
register: node_ready
retries: 3
delay: 2
until: "'Ready' in node_ready.stdout"
target_version은 CLI에서 -e target_version=1.31.6으로 전달합니다. until로 Ready 상태를 확인한 뒤 다음 Phase로 넘어갑니다.
- name: Phase2
hosts: control_plane_join
become: true
gather_facts: false
serial: 1
tasks:
- name: phase2 block
block:
- name: start msg
debug:
msg: "Phase 2: CP 업그레이드 ({{ inventory_hostname }})"
- name: apt upgrade
shell: "echo 'apt repo changed to v{{ target_version }}'"
register: apt_repo_result
- name: kubeadm upgrade
shell: "echo 'kubeadm upgrade node'"
register: kubeadm_result
- name: debug
debug:
msg: "{{ apt_repo_result.stdout }}\n{{ kubeadm_result.stdout }}"
- name: kubelet restart
shell: "echo 'kubelet restarted'"
- name: node_ready
shell: "echo '{{ inventory_hostname }} Ready'"
register: node_ready
retries: 3
delay: 2
until: "'Ready' in node_ready.stdout"
rescue:
- name: rescue
debug:
msg: "업그레이드 실패: {{ inventory_hostname }}"
Phase 1과의 차이점:
kubeadm upgrade apply → kubeadm upgrade node (로컬 컴포넌트만 업그레이드)block/rescue로 감싸서 실패 시 에러 메시지 출력serial: 1로 한 대씩 처리 (etcd quorum 유지)- name: Phase3
hosts: workers
become: true
gather_facts: false
serial: 1
tasks:
- name: phase3 block
block:
- name: start msg
debug:
msg: "Phase 3: Worker 업그레이드 ({{ inventory_hostname }})"
- name: kubectl drain
shell: "echo 'kubectl drain {{ inventory_hostname }}'"
register: kubectl_drain_result
delegate_to: node1
- name: apt upgrade
shell: "echo 'apt repo changed to v{{ target_version }}'"
register: apt_repo_result
- name: kubeadm upgrade
shell: "echo 'kubeadm upgrade node'"
register: kubeadm_result
- name: debug
debug:
msg: "{{ kubectl_drain_result.stdout }}\n{{ apt_repo_result.stdout }}\n{{ kubeadm_result.stdout }}"
- name: kubelet restart
shell: "echo 'kubelet restarted'"
- name: kubectl uncordon
shell: "echo 'kubectl uncordon {{ inventory_hostname }}'"
delegate_to: node1
- name: node ready
shell: "echo '{{ inventory_hostname }} Ready'"
register: node_ready
retries: 3
delay: 2
until: "'Ready' in node_ready.stdout"
rescue:
- name: failed
debug:
msg: "업그레이드 실패, uncordon 실행: {{ inventory_hostname }}"
- name: uncordon
shell: "echo 'kubectl uncordon {{ inventory_hostname }}'"
delegate_to: node1
Phase 3의 핵심:
delegate_to: node1 — drain과 uncordon은 kubectl 명령이므로 CP(node1)에서 실행해야 합니다. play 컨텍스트는 worker(node3)지만, task 실행만 node1에 위임합니다.ansible-playbook -i inventory_kube.ini playbook/upgrade_k8s.yml -e target_version=1.31.6
PLAY [Phase1] ************************************************************************
TASK [start msg] *********************************************************************
ok: [node1] => {
"msg": "Phase 1: 첫 번째 CP 업그레이드 시작 (1.13.6)"
}
TASK [apt upgrade] *******************************************************************
changed: [node1]
TASK [kubeadm upgrade] ***************************************************************
changed: [node1]
TASK [debug] *************************************************************************
ok: [node1] => {
"msg": "apt repo changed to v1.13.6\nkubeadm upgrade apply v1.13.6"
}
TASK [kubelet restart] ***************************************************************
changed: [node1]
TASK [node ready] ********************************************************************
changed: [node1]
PLAY [Phase2] ************************************************************************
TASK [start msg] *********************************************************************
ok: [node2] => {
"msg": "Phase 2: CP 업그레이드 (node2)"
}
TASK [apt upgrade] *******************************************************************
changed: [node2]
TASK [kubeadm upgrade] ***************************************************************
changed: [node2]
TASK [debug] *************************************************************************
ok: [node2] => {
"msg": "apt repo changed to v1.13.6\nkubeadm upgrade node"
}
TASK [kubelet restart] ***************************************************************
changed: [node2]
TASK [node_ready] ********************************************************************
changed: [node2]
PLAY [Phase3] ************************************************************************
TASK [start msg] *********************************************************************
ok: [node3] => {
"msg": "Phase 3: Worker 업그레이드 (node3)"
}
TASK [kubectl drain] *****************************************************************
changed: [node3 -> node1]
TASK [apt upgrade] *******************************************************************
changed: [node3]
TASK [kubeadm upgrade] ***************************************************************
changed: [node3]
TASK [debug] *************************************************************************
ok: [node3] => {
"msg": "kubectl drain node3\napt repo changed to v1.13.6\nkubeadm upgrade node"
}
TASK [kubelet restart] ***************************************************************
changed: [node3]
TASK [kubectl uncordon] **************************************************************
changed: [node3 -> node1]
TASK [node ready] ********************************************************************
changed: [node3]
PLAY RECAP ***************************************************************************
node1 : ok=6 changed=4 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
node2 : ok=6 changed=4 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
node3 : ok=8 changed=6 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
node3 -> node1 표시는 delegate_to가 동작한 증거입니다. drain과 uncordon이 node1(CP)에서 실행되었습니다.
처음 작성 시 until: "'Reday' in node_ready.stdout"로 오타를 넣었더니, stdout에 "Ready"가 있음에도 조건이 매칭되지 않아 3회 재시도 후 실패했습니다:
FAILED - RETRYING: [node1]: node ready (3 retries left).
FAILED - RETRYING: [node1]: node ready (2 retries left).
FAILED - RETRYING: [node1]: node ready (1 retries left).
fatal: [node1]: FAILED!
해결: 'Reday' → 'Ready'로 수정. until 조건은 문자열 비교이므로 오타에 주의해야 합니다.
# 잘못된 구조
- name: node_ready
shell: ...
rescue: # ← shell task의 속성으로 들어감
- name: rescue
debug: ...
'shell' is not a valid attribute for a Block
원인: rescue를 개별 task 아래에 넣으면 Ansible이 해당 task를 block으로 해석하려다 실패합니다.
해결: block:으로 task 리스트를 감싸고, rescue:는 block:과 같은 레벨에 위치시킵니다:
# 올바른 구조
- name: phase block
block:
- name: node_ready
shell: ...
rescue:
- name: rescue
debug: ...
until: uncordon_complete # ← dict를 bool로 평가하려 함
Conditional result (True) was derived from value of type 'dict'. Conditionals must have a boolean result.
원인: until에 register 변수 자체를 넣으면 dict → bool 변환을 시도하여 에러가 발생합니다.
해결: 변수의 특정 필드를 비교하는 표현식으로 작성합니다:
until: "'Ready' in node_ready.stdout"
이번 playbook에 사용된 기능과 해당 챕터를 매핑합니다:
| 기능 | 챕터 | 이 playbook에서의 역할 |
|---|---|---|
| inventory 그룹, children | Chap 1, 8 | CP init/join/workers 분리 |
변수 (-e) |
Chap 2 | target_version 전달 |
| 멀티 play | Chap 5 | Phase 1, 2, 3 분리 |
| serial: 1 | Chap 5 | CP, Worker 한 대씩 순차 처리 |
| delegate_to | Chap 5 | drain/uncordon을 CP에서 실행 |
| register + until | Chap 6 | Ready 대기 |
| block/rescue | Chap 7 | 업그레이드 실패 시 복구 (uncordon) |
K8s 클러스터 업그레이드는 순서와 안전이 핵심입니다:
Ansible의 기본 기능들 — 변수, 조건문, 반복, 핸들러, 템플릿, Role, register, until, block/rescue, serial, delegate_to — 을 조합하면 이처럼 복잡한 운영 절차도 재현 가능하고 안전한 자동화로 만들 수 있습니다.