🔧

Ansible - K8s 클러스터 업그레이드 자동화

최민석·2026-03-30

ansible

K8s 클러스터 업그레이드 자동화

🔧 Ansible 실습 시리즈

지금까지 배운 Ansible 기능들을 총동원하여, Kubernetes 클러스터의 버전 업그레이드를 자동화하는 playbook을 구현합니다. 실제 K8s 클러스터는 없지만 Docker 환경의 node1~3으로 업그레이드 절차를 시뮬레이션하며, K8s 업그레이드의 핵심 개념과 순서를 함께 정리합니다.


K8s 업그레이드 순서

6대 노드(Control Plane 3 + Worker 3) 클러스터를 기준으로, 업그레이드는 반드시 다음 순서를 따릅니다:

CP 01 (init) → CP 02, 03 (join) → Worker 01, 02, 03

역순이나 동시 진행은 불가합니다.

Phase 1: 첫 번째 Control Plane (1대만)

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가 하는 일:

  • etcd, kube-apiserver, kube-controller-manager, kube-scheduler 업그레이드
  • CoreDNS, kube-proxy 업그레이드
  • 클러스터 전체에 1번만 실행 — 두 번째 CP부터는 apply가 아님

drain 안 하는 이유: CP에는 taint(node-role.kubernetes.io/control-plane:NoSchedule)가 걸려있어서 일반 Pod이 스케줄되지 않습니다. 퇴거시킬 워크로드가 없습니다.

Phase 2: 나머지 Control Plane (한 대씩)

apt repo 변경
→ kubeadm 업그레이드 + hold
→ kubeadm upgrade node        ← 로컬 컴포넌트만
→ kubelet, kubectl 업그레이드 + hold
→ systemctl restart kubelet
→ Ready 대기
→ 다음 노드

upgrade node가 하는 일:

  • 해당 노드의 로컬 etcd member 업그레이드
  • kubelet 설정 업데이트
  • 클러스터 레벨 컴포넌트는 Phase 1에서 이미 완료

한 대씩 하는 이유: etcd quorum 유지. 3대 중 과반수(2대)가 항상 정상이어야 합니다. 동시에 2대를 내리면 quorum을 잃고 클러스터가 먹통됩니다.

Phase 3: Worker 노드 (한 대씩)

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의 동작 범위

kubectl drain이 완료되었다는 것은:

  1. 해당 노드에 새 Pod 스케줄링 차단 (cordon)
  2. 기존 Pod에 퇴거 요청 (eviction) 전송
  3. 해당 노드에서 Pod이 모두 제거됨

여기까지입니다. 퇴거된 Pod이 다른 노드에 정상 배치되었는지는 drain이 관여하지 않습니다.

다른 노드에 재배치되는 건 별개 흐름입니다:

  • Deployment/ReplicaSet의 컨트롤러가 "원하는 replicas 수보다 부족하다"를 감지
  • 새 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에서 선택적으로 추가하는 안전 장치입니다.

hold가 필요한 이유

$ 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 구성

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 그룹으로 묶습니다.

inventory 확인

$ ansible-inventory -i inventory_kube.ini --graph
@all:
  |--@ungrouped:
  |--@control_plane:
  |  |--@control_plane_init:
  |  |  |--node1
  |  |--@control_plane_join:
  |  |  |--node2
  |--@workers:
  |  |--node3

playbook 구현

playbook/upgrade_k8s.yml — 3개의 play로 구성됩니다.

Phase 1: 첫 번째 Control Plane

---
- 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로 넘어갑니다.

Phase 2: 나머지 Control Plane

- 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 유지)

Phase 3: Worker 노드

- 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에 위임합니다.
  • rescue에서 uncordon — 업그레이드 중 실패하더라도 노드를 다시 스케줄링 가능하게 복구합니다. drain 상태로 방치되면 해당 노드에 Pod이 배치되지 않습니다.
  • task 순서가 안전을 보장 — drain이 실패하면 block이 즉시 중단되고 rescue로 빠지므로, drain 실패 상태에서 업그레이드가 진행되는 일은 없습니다.

실행

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 조건의 오타

처음 작성 시 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 조건은 문자열 비교이므로 오타에 주의해야 합니다.

block 구조 에러 — rescue를 task에 직접 붙임

# 잘못된 구조
- 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에 register 변수를 직접 전달

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"

사용된 Ansible 기능 총정리

이번 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 클러스터 업그레이드는 순서와 안전이 핵심입니다:

  • 순서: CP init → CP join → Worker (역순 불가)
  • serial: etcd quorum과 워크로드 가용성을 위해 한 대씩
  • delegate_to: kubectl 명령은 CP에서 실행, play 컨텍스트는 대상 노드 유지
  • block/rescue: 실패 시 uncordon으로 복구하여 노드가 drain 상태로 방치되지 않도록
  • drain의 범위: 해당 노드에서 Pod을 제거하는 것까지만 — 다른 노드에 재배치 확인은 별도 검증 필요
  • hold: 업그레이드 전후로 dpkg_selections hold/install을 관리하여 의도치 않은 버전 변경 방지

Ansible의 기본 기능들 — 변수, 조건문, 반복, 핸들러, 템플릿, Role, register, until, block/rescue, serial, delegate_to — 을 조합하면 이처럼 복잡한 운영 절차도 재현 가능하고 안전한 자동화로 만들 수 있습니다.

관련 포스트