Ansible 플레이북(Playbook)은 여러 서버에 대한 설정·배포·관리 작업을 자동화하는 YAML 스크립트다. 마스터 서버에서 플레이북을 한 번 작성해 두면, 인벤토리에 등록한 워커 서버 여러 대에 동일한 작업을 일관되게 반복 적용할 수 있다. 이 글에서는 Ansible 플레이북의 개념과 YAML 구조부터, 인벤토리 정의 → 플레이북 작성 → ansible-playbook 실행 → 출력 해석까지를, 워커 서버에 NginX를 설치하는 예제로 단계별로 정리한다.
목차
Ansible 플레이북이란
Ansible 플레이북은 Ansible이 어떤 작업을 해야 할지 정의하는 파일이다. 모든 내용은 YAML 형식으로 작성되며, 하나의 플레이북은 하나 이상의 플레이(play)로 이뤄진다. 각 플레이는 작업을 적용할 호스트 그룹을 지정하고, 그 안에 순서대로 실행되는 태스크(task)를 담는다.
각 태스크는 모듈(module)을 호출해 시스템에 명령을 보내고 상태를 변경한다. 예를 들어 패키지 설치에는 apt·yum·dnf 모듈을, 파일 배포에는 copy·template 모듈을, 서비스 제어에는 service 모듈을 쓴다. 이렇게 플레이북을 사용하면 Ad-hoc 명령을 일일이 입력하는 대신, 반복적인 작업을 재사용 가능한 형태로 자동화해 시간을 절약할 수 있다.
플레이의 주요 구성 요소
플레이북의 한 플레이는 보통 다음 요소로 구성된다.
- name: 플레이를 설명하는 이름. 실행 출력에 표시돼 어떤 작업이 도는지 한눈에 알 수 있다.
- hosts: 작업을 적용할 대상. 인벤토리에 정의한 그룹명(예:
webservers)이나 개별 호스트,all등을 지정한다. - become: 권한 상승(sudo) 여부.
yes면 관리자 권한으로 태스크를 실행한다. - tasks: 실제로 수행할 작업 목록. 각 태스크는 모듈을 호출하며 위에서 아래로 순서대로 실행된다.
인벤토리(hosts) 정의
플레이북을 작성하기 전에, 작업 대상 서버를 인벤토리에 등록해야 한다. 인벤토리는 Ansible이 관리할 노드 목록으로, 기본 파일 경로는 /etc/ansible/hosts다. NginX를 설치할 워커 서버를 webservers 그룹으로 묶고 IP를 추가한다.
vi /etc/ansible/hosts
[webservers]
192.168.111.100대괄호로 감싼 [webservers]가 그룹명이고, 그 아래 줄들이 그룹에 속한 호스트다. 한 그룹에 여러 서버를 넣으려면 IP나 호스트명을 줄마다 추가하면 된다. 이렇게 정의해 두면 플레이북의 hosts: webservers가 이 그룹 전체를 가리킨다.
플레이북 YAML 작성
이제 /opt 아래에 작업 디렉토리를 만들고, 그 안에 플레이북 yml 파일을 생성한다.
[root@localhost ~]# cd /opt/
[root@localhost opt]# mkdir AnsiblePlaybooks
[root@localhost opt]# cd AnsiblePlaybooks
[root@localhost AnsiblePlaybooks]# vi nginx_install.ymlNginX를 설치하는 가장 기본적인 플레이북 내용은 다음과 같다. YAML은 들여쓰기로 구조를 구분하므로 공백 정렬에 특히 주의해야 한다(탭 금지, 스페이스 사용).
- name: Install nginx on webservers
hosts: webservers
gather_facts: no
become: yes
tasks:
- name: install nginx web-server
yum:
name: nginx
state: present맨 앞의 -는 플레이가 목록의 한 항목임을 뜻한다. 이 플레이는 이름을 Install nginx on webservers로 설정하고, 앞서 인벤토리에서 정의한 webservers 그룹에 등록된 호스트에 NginX를 설치한다. tasks 아래의 태스크는 yum 모듈을 호출해 nginx 패키지를 present(설치된) 상태로 만든다.
주요 옵션 설명
gather_facts: no는 플레이북 실행 시 Ansible이 대상 호스트의 사전 정보(facts)를 수집하지 않도록 하는 옵션이다. 일반적으로 Ansible은 실행 전에 운영체제·하드웨어 같은 호스트 상태 정보를 수집하는데, 이를 “facts 수집”이라고 한다. 이 정보는 플레이북 안에서 변수로 쓸 수 있지만, 필요 없다면 no로 꺼서 실행 시간을 단축할 수 있다.
become: yes는 관리자 권한으로 작업을 실행하도록 하는 옵션이다. 패키지 설치 같은 작업은 관리자 권한이 필요하므로, 이 옵션을 추가하면 플레이북 안에서 sudo나 su를 따로 쓰지 않아도 권한 상승된 상태로 태스크가 실행된다.
패키지 모듈은 배포판에 따라 다르다. CentOS·RHEL 계열은 yum(또는 dnf), 데비안·우분투 계열은 apt를 쓴다. 배포판을 가리지 않는 일반 모듈인 package를 써도 된다.
플레이북 실행과 옵션
작성한 플레이북은 ansible-playbook 명령으로 실행한다. -i 옵션으로 사용할 인벤토리 파일을 명시할 수 있는데, 기본 인벤토리(/etc/ansible/hosts)를 쓴다면 생략해도 된다.
# 기본 인벤토리 사용
ansible-playbook nginx_install.yml
# 인벤토리 파일을 직접 지정
ansible-playbook -i /etc/ansible/hosts nginx_install.yml실제 서버에 적용하기 전에 변경 사항을 미리 점검하고 싶다면 --check(또는 -C) 옵션을 쓴다. 이른바 dry-run 모드로, 실제 시스템은 건드리지 않고 “무엇이 바뀔지”만 보고한다. 문법 오류나 의도치 않은 변경을 사전에 걸러낼 때 유용하다.
# dry-run: 실제 변경 없이 결과만 확인
ansible-playbook --check nginx_install.yml
# 상세 출력이 필요하면 -v (또는 -vv, -vvv)
ansible-playbook -v nginx_install.yml실행 출력(PLAY RECAP) 해석
플레이북을 실행하면 각 플레이·태스크의 진행 상황과 함께, 마지막에 호스트별 결과 요약인 PLAY RECAP이 출력된다.
[root@localhost AnsiblePlaybooks]# ansible-playbook nginx_install.yml
PLAY [Install nginx on webservers] *********************************
TASK [install nginx web-server] ***********************************
changed: [192.168.111.100]
PLAY RECAP ********************************************************
192.168.111.100 : ok=1 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0각 태스크 줄 앞의 상태와 RECAP의 카운터는 다음을 뜻한다.
| 상태 | 의미 |
|---|---|
| ok | 태스크가 정상 처리됨. 이미 원하는 상태라 바꿀 게 없었던 경우도 포함된다. |
| changed | 실제로 시스템 상태가 변경됨(여기서는 NginX가 새로 설치됨). |
| unreachable | 호스트에 접속 자체를 못 함(SSH·네트워크 문제). 0이어야 정상. |
| failed | 태스크 실행이 실패함. 0이 아니면 로그를 확인해야 한다. |
| skipped | 조건(when 등)에 맞지 않아 건너뛴 태스크. |
설치가 끝나면 워커 서버에서 systemctl로 NginX가 등록됐는지 확인할 수 있다. 설치 직후에는 서비스가 시작 전(inactive)일 수 있는데, 이는 정상이며 별도로 systemctl start nginx로 시작하면 된다.
[centos@localhost ~]$ systemctl status nginx.service
● nginx.service - The nginx HTTP and reverse proxy server
Loaded: loaded (/usr/lib/systemd/system/nginx.service; disabled; vendor preset: disabled)
Active: inactive (dead)또는 마스터 서버에서 Ad-hoc 명령으로 전체 호스트의 상태를 한 번에 확인할 수도 있다. -m은 사용할 모듈, -a는 모듈에 넘길 인자다.
ansible all -m shell -a "systemctl status nginx"멱등성과 작성 시 주의점
Ansible의 핵심 특성 중 하나가 멱등성(idempotency)이다. 대부분의 Ansible 모듈은 “목표 상태에 이미 도달했는지”를 먼저 확인하고, 이미 그 상태라면 아무 작업도 하지 않고 넘어간다. 그래서 같은 플레이북을 여러 번 실행해도 결과는 동일하고, 불필요한 변경이 일어나지 않는다.
예를 들어 위 플레이북을 처음 실행하면 NginX가 설치되며 changed로 표시되지만, NginX가 이미 설치된 상태에서 다시 실행하면 ok로만 표시되고 changed=0이 된다. 즉 changed 카운터를 보면 “이번 실행에서 실제로 무엇이 바뀌었는지”를 가늠할 수 있다.
YAML 작성 시 흔한 실수
- 들여쓰기 혼용: YAML은 들여쓰기로 계층을 구분한다. 탭과 스페이스를 섞으면 파싱 오류가 나므로 스페이스로 통일한다.
- 콜론 뒤 공백:
key: value처럼 콜론 뒤에 공백을 한 칸 둬야 한다. - 모듈 인자 정렬:
name·state같은 모듈 인자는 모듈명보다 한 단계 더 들여써야 한다. - 대상 모듈 확인: 배포판에 맞는 패키지 모듈(
yum/apt/dnf)을 써야 한다. 헷갈리면 범용package모듈을 쓴다.
자주 묻는 질문(FAQ)
플레이북과 Ad-hoc 명령은 어떻게 다른가?
Ad-hoc 명령은 ansible 도구로 한 줄짜리 작업을 즉석에서 빠르게 실행할 때 쓴다. 간단하지만 재사용이 어렵다. 반면 플레이북은 여러 작업을 YAML 파일로 정의해 두고 반복·재사용할 수 있어, 설정 관리나 다중 서버 배포처럼 구조화된 작업에 적합하다.
실행 전에 결과를 미리 확인할 수 있나?
ansible-playbook --check playbook.yml로 dry-run을 돌리면 실제 시스템을 바꾸지 않고 어떤 변경이 생길지만 미리 볼 수 있다. 운영 서버에 적용하기 전 안전 점검용으로 권장한다.
같은 플레이북을 여러 번 실행해도 괜찮나?
괜찮다. 대부분의 모듈이 멱등성을 보장하므로, 이미 원하는 상태라면 다시 실행해도 변경이 일어나지 않는다(changed=0). 다만 shell·command처럼 멱등성이 보장되지 않는 모듈은 매번 실행되므로 주의해야 한다.
정리
Ansible 플레이북은 인벤토리에 등록한 서버 그룹에 YAML로 정의한 작업을 일관되게 적용하는 자동화 도구다. 핵심 흐름은 인벤토리 정의 → 플레이북 작성(name·hosts·become·tasks·module) → ansible-playbook -i 실행 → PLAY RECAP 해석 순이다. 운영 서버라면 --check로 먼저 점검하고, 멱등성 덕분에 같은 플레이북을 안심하고 반복 실행할 수 있다는 점을 기억하자.
플레이북을 작성하기 전에 원격 서버 상태를 빠르게 점검하고 싶다면 Ansible 기본적인 Ad-hoc 명령어들 글을 함께 참고하면 좋다. 더 많은 모듈과 옵션은 Ansible 공식 문서에서 확인할 수 있다.
💬 댓글 0