Ansible 플레이북, 역할, 실행 스크립트를 추가하여 클러스터 시스템 업데이트 프로세스를 자동화했습니다.

cluster-admin: Ansible을 이용한 클러스터 업데이트 자동화 추가

Ansible 플레이북, 역할, 실행 스크립트를 추가하여 클러스터 시스템 업데이트 프로세스를 자동화했습니다.

요약

이번 커밋은 Ansible을 활용하여 클러스터의 시스템 업데이트 과정을 자동화하는 기능을 추가했습니다. ansible/playbooks/system-update.yml 파일에 시스템 업데이트 및 순차적 재부팅을 위한 플레이북을 작성했으며, 관련 작업은 ansible/roles/system-update와 ansible/roles/reboot-handler 역할에서 수행됩니다. 업데이트 실행 스크립트 ansible/run-update.sh도 함께 추가되었습니다. 총 189라인의 코드가 추가되었으며, 기존 코드는 삭제되지 않았습니다. 작업은 2026년 2월 25일에 완료되었습니다.

배경 및 목적

기존에는 클러스터 노드의 시스템 업데이트를 수동으로 진행해야 했습니다. 이는 시간 소모적이고 인적 오류의 가능성을 내포하고 있었습니다. 따라서 반복적인 업데이트 작업을 자동화하여 효율성을 높이고, 업데이트 후 필요한 경우 시스템을 순차적으로 재부팅하여 서비스 중단을 최소화하는 것이 목적입니다.

구현 내용

주요 변경 사항은 다음과 같습니다.

변경된 파일 목록

ansible/ansible.cfg
ansible/inventory/hosts.ini
ansible/logs/cluster_update_20260225_144454.log
ansible/playbooks/system-update.yml
ansible/roles/reboot-handler/tasks/main.yml
ansible/roles/system-update/tasks/main.yml
ansible/run-update.sh

추가/삭제 코드 라인 수

총 추가 라인: 189
총 삭제 라인: 0

주요 변경 사항 상세 설명

`ansible/playbooks/system-update.yml`

이 파일은 클러스터 전체 노드에 대한 시스템 업데이트 및 순차 재부팅을 정의합니다.

hosts: all: 모든 호스트에 플레이북을 적용합니다.
serial: 1: 한 번에 하나의 노드만 업데이트 및 재부팅하여 서비스 영향을 줄입니다.
tasks:
- Update apt cache: apt 패키지 관리자의 캐시를 업데이트합니다.
- Upgrade packages: apt upgrade dist 명령을 실행하여 패키지를 업그레이드합니다.
- Check if reboot is required: /var/run/reboot-required 파일 존재 여부를 확인하여 재부팅이 필요한지 판단합니다.
- Reboot if required: 재부팅이 필요할 경우 시스템을 재부팅합니다.
- Wait for k3s service to be ready (master): 마스터 노드의 k3s 서비스가 활성화될 때까지 기다립니다.
- Wait for k3s-agent service to be ready (workers): 워커 노드의 k3s-agent 서비스가 활성화될 때까지 기다립니다.

---
- name: System Update and Sequential Reboot
  hosts: all
  gather_facts: yes
  serial: 1
  tasks:
    - name: Update apt cache
      apt:
        update_cache: yes
      become: yes

    - name: Upgrade packages
      apt:
        upgrade: dist
      become: yes

    - name: Check if reboot is required
      stat:
        path: /var/run/reboot-required
      register: reboot_required

    - name: Reboot if required
      reboot:
        msg: "System reboot initiated by Ansible"
        connect_timeout: 5
        reboot_timeout: 300
        pre_reboot_delay: 0
        post_reboot_delay: 30
      become: yes
      when: reboot_required.stat.exists

    - name: Wait for k3s service to be ready (master)
      systemd:
        name: k3s
        state: started
      become: yes
      register: k3s_service
      until: k3s_service.status.ActiveState == 'active'
      retries: 60
      delay: 10
      when: inventory_hostname in groups['master']

    - name: Wait for k3s-agent service to be ready (workers)
      systemd:
        name: k3s-agent
        state: started
      become: yes
      register: k3s_agent_service
      until: k3s_agent_service.status.ActiveState == 'active'
      retries: 60
      delay: 10
      when: inventory_hostname in groups['workers']

`ansible/roles/system-update/tasks/main.yml`

시스템 업데이트 작업을 담당하는 역할입니다. update_cache, upgrade 기능을 수행하고 재부팅 필요 여부를 system_reboot_needed 팩트로 설정합니다.

---
- name: Update apt cache
  apt:
    update_cache: yes
  become: yes

- name: Upgrade packages
  apt:
    upgrade: dist
  become: yes
  register: upgrade_result

- name: Check if reboot is required
  stat:
    path: /var/run/reboot-required
  register: reboot_required

- name: Set reboot flag
  set_fact:
    system_reboot_needed: "{{ reboot_required.stat.exists }}"

`ansible/roles/reboot-handler/tasks/main.yml`

system_reboot_needed 팩트가 참일 경우 시스템을 재부팅하는 역할입니다.

---
- name: Reboot system if required
  reboot:
    msg: "System reboot initiated by Ansible"
    connect_timeout: 5
    reboot_timeout: 300
    pre_reboot_delay: 0
    post_reboot_delay: 30
  when: system_reboot_needed | default(false)
  become: yes

`ansible/run-update.sh`

이 스크립트는 Ansible 플레이북 실행을 위한 쉘 스크립트입니다.

스크립트 실행 시점의 타임스탬프를 생성하고, 해당 타임스탬프를 포함하는 로그 파일을 ansible/logs 디렉토리에 생성합니다.
ansible-playbook 명령을 사용하여 system-update.yml 플레이북을 실행하고, 실행 결과를 로그 파일에 기록합니다.

#!/bin/bash
cd " $(d i r nam e "$ 0")"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
LOG_DIR="logs"
mkdir -p "$LOG_DIR"
LOG_FILE=" $LOG_DIR/cluster_update_$ TIMESTAMP.log"
echo "=== [ $(d a t e)] Cl u s t er U p d a t e St a r t e d === "∣ t ee "$ LOG_FILE"
ansible-playbook -i inventory/hosts.ini playbooks/system-update.yml >> "$LOG_FILE" 2>&1
echo "=== [ $(d a t e)] Cl u s t er U p d a t e C o m pl e t e d === "∣ t ee - a "$ LOG_FILE"

기술적 의사결정

이 작업에서는 Ansible을 클러스터 관리 도구로 선택했습니다. Ansible은 에이전트리스(agentless) 방식으로 SSH를 통해 서버에 접속하여 작업을 수행하므로, 관리 대상 서버에 별도의 에이전트 설치가 필요 없습니다. 이는 초기 설정 및 유지보수 부담을 줄여줍니다. 또한, YAML 기반의 플레이북은 사람이 읽고 이해하기 쉬우며, 역할(roles) 기능을 통해 코드 재사용성을 높일 수 있다는 장점이 있습니다. 다른 대안으로 Chef나 Puppet이 있을 수 있으나, Ansible의 간결성과 에이전트리스 방식이 프로젝트의 요구사항과 학부 수준에서의 학습 용이성을 고려했을 때 더 적합하다고 판단했습니다.

배운 점 및 개선점

이번 작업을 통해 Ansible의 기본 문법과 플레이북, 역할 작성 방법을 익힐 수 있었습니다. 또한, 시스템 업데이트 후 재부팅 필요성을 자동으로 감지하고 순차적으로 재부팅하는 로직을 구현하는 과정에서 클러스터 환경에서의 안정적인 서비스 운영에 대한 이해를 높였습니다.

향후 개선점으로는 다음과 같은 사항들을 고려할 수 있습니다.

오류 처리 강화: 현재는 기본적인 로그 기록만 포함되어 있습니다. 업데이트 실패 시 알림 기능이나 롤백 로직을 추가하여 안정성을 더욱 높일 수 있습니다.
다양한 OS 지원: 현재는 apt 기반의 시스템을 가정하고 있습니다. CentOS, RHEL 등 다른 배포판을 지원하기 위한 로직을 추가할 수 있습니다.
정교한 재부팅 관리: serial 옵션을 사용하여 순차 재부팅을 구현했지만, 서비스 종류에 따라 더 정교한 상태 확인 및 복구 로직이 필요할 수 있습니다.
인벤토리 관리: hosts.ini 파일을 직접 수정하는 대신, 동적 인벤토리 소스(예: 클라우드 API)를 연동하여 관리의 편의성을 높일 수 있습니다.

다음 단계로는 자동화된 업데이트 과정을 주기적으로 실행하고, 실제 운영 환경에서의 안정성을 검증하는 작업을 진행할 예정입니다.

참고 자료

Ansible Documentation: https://docs.ansible.com/
Ansible System Update Role: (직접 작성한 내용)