Ansible 변수와 Facts 완벽 가이드

Ansible에서 변수를 정의하고 활용하는 방법부터 시스템 정보를 자동 수집하는 Facts까지, 인프라 자동화의 핵심 개념을 실무 예제와 함께 쉽게 설명합니다.

---

목차

1. 변수_정의_및_사용법
2. 변수_우선순위_이해
3. Facts_수집_개념
4. setup_모듈로_시스템_정보_조회
5. 커스텀_Facts_생성
6. 변수_파일_분리하기

---

1. 변수 정의 및 사용법

입사 첫 주, 김개발 씨는 수십 대의 서버에 동일한 설정을 배포해야 하는 상황에 처했습니다. 서버마다 IP 주소와 포트 번호가 다른데, 일일이 수정하려니 막막하기만 합니다.

선배 박시니어 씨가 웃으며 한마디 합니다. "변수를 쓰면 한 번에 해결돼요."

변수는 값을 담아두는 상자와 같습니다. 마치 이사할 때 물건에 라벨을 붙여두는 것처럼, 자주 바뀌거나 재사용할 값에 이름을 붙여두면 관리가 훨씬 쉬워집니다.

Ansible에서 변수를 제대로 활용하면 하나의 플레이북으로 수백 대 서버를 유연하게 관리할 수 있습니다.

다음 코드를 살펴봅시다.

# playbook.yml - 변수 정의와 사용 예제
- name: 웹 서버 설정 배포
  hosts: webservers
  vars:
    http_port: 8080
    max_clients: 200
    server_name: "api.mycompany.com"
  tasks:
    - name: 설정 파일 생성
      template:
        src: nginx.conf.j2
        dest: /etc/nginx/nginx.conf

    - name: 포트 정보 출력
      debug:
        msg: "서버 {{ server_name }}이 {{ http_port }} 포트에서 실행됩니다"

김개발 씨는 입사 3개월 차 주니어 DevOps 엔지니어입니다. 오늘 팀장님으로부터 긴급 업무를 받았습니다.

"개발 서버 10대에 새로운 설정 파일을 배포해야 하는데, 서버마다 포트 번호가 달라요." 김개발 씨는 처음에 단순하게 생각했습니다. 플레이북 파일을 10개 만들어서 각각 다른 포트 번호를 넣으면 되지 않을까?

하지만 선배 박시니어 씨가 고개를 저었습니다. "그렇게 하면 나중에 유지보수가 지옥이 될 거예요." 그렇다면 변수란 정확히 무엇일까요?

쉽게 비유하자면, 변수는 마치 편지봉투에 붙이는 라벨과 같습니다. 봉투 안에 들어있는 내용물은 바뀔 수 있지만, 라벨을 보면 어떤 용도인지 바로 알 수 있습니다.

http_port라는 라벨을 붙여두면, 실제 값이 8080이든 3000이든 상관없이 같은 이름으로 참조할 수 있습니다. Ansible에서 변수를 정의하는 가장 기본적인 방법은 vars 블록을 사용하는 것입니다.

플레이북 안에서 vars 아래에 원하는 변수명과 값을 작성하면 됩니다. 이렇게 정의한 변수는 해당 플레이북 전체에서 사용할 수 있습니다.

변수를 사용할 때는 이중 중괄호 {{ }}를 씁니다. Jinja2 템플릿 문법이라고 부르는데, Ansible은 이 문법을 사용하여 변수 값을 치환합니다.

예를 들어 {{ http_port }}라고 쓰면 실행 시점에 8080으로 바뀝니다. 위의 코드를 살펴보겠습니다.

vars 블록에서 http_port, max_clients, server_name 세 개의 변수를 정의했습니다. 그 아래 tasks에서 이 변수들을 활용하고 있습니다.

debug 모듈의 msg에서 변수를 문자열 안에 넣어 사용하는 것을 볼 수 있습니다. 실제 현업에서는 어떻게 활용할까요?

개발 환경과 운영 환경의 설정이 다를 때 변수를 사용합니다. 개발 서버는 http_port가 8080이고, 운영 서버는 80일 수 있습니다.

플레이북은 하나만 유지하면서 변수 값만 바꿔주면 됩니다. 초보자들이 흔히 하는 실수 중 하나는 변수명에 하이픈(-)을 사용하는 것입니다.

Ansible 변수명은 언더스코어(_)를 사용해야 합니다. http-port가 아니라 http_port로 작성해야 합니다.

김개발 씨는 변수의 개념을 이해한 후 플레이북을 하나로 통합했습니다. 서버별로 다른 값만 별도로 관리하니 코드가 훨씬 깔끔해졌습니다.

박시니어 씨가 엄지를 치켜세웠습니다.

실전 팁

💡 - 변수명은 영문 소문자와 언더스코어만 사용하세요

• 자주 변경되는 값은 반드시 변수로 분리하세요

---

2. 변수 우선순위 이해

김개발 씨가 플레이북을 실행했는데 예상과 다른 값이 출력되었습니다. 분명히 변수를 8080으로 정의했는데 왜 80이 나오는 걸까요?

박시니어 씨가 설명합니다. "Ansible에는 변수 우선순위라는 게 있어요."

변수 우선순위는 같은 이름의 변수가 여러 곳에서 정의되었을 때 어떤 값이 최종적으로 사용될지 결정하는 규칙입니다. 마치 법률에서 상위법이 하위법보다 우선하는 것처럼, Ansible에서도 정해진 순서에 따라 변수가 덮어씌워집니다.

다음 코드를 살펴봅시다.

# inventory/host_vars/web01.yml
http_port: 8080  # 호스트 변수 (높은 우선순위)

# group_vars/webservers.yml
http_port: 80    # 그룹 변수 (중간 우선순위)

# playbook.yml
- name: 변수 우선순위 테스트
  hosts: web01
  vars:
    http_port: 3000  # 플레이북 변수
  tasks:
    - name: 현재 포트 확인
      debug:
        msg: "포트: {{ http_port }}"

    # 명령줄에서 실행: ansible-playbook playbook.yml -e "http_port=9000"
    # 결과: extra vars가 가장 높은 우선순위를 가짐

어느 날 김개발 씨가 당황한 표정으로 박시니어 씨에게 달려왔습니다. "선배님, 저 분명히 포트를 8080으로 설정했는데 자꾸 80으로 실행돼요.

플레이북이 고장 난 걸까요?" 박시니어 씨는 차분히 코드를 살펴보더니 웃으며 말했습니다. "플레이북은 멀쩡해요.

변수 우선순위를 모르면 이런 혼란을 겪게 되죠." 변수 우선순위란 무엇일까요? 마치 회사에서 지시가 중복될 때를 생각해보세요.

팀장님이 "오늘 회의는 3시"라고 하셨는데, 나중에 사장님이 "회의는 4시"라고 하셨다면 어떤 시간에 가야 할까요? 당연히 사장님 말씀을 따르겠죠.

Ansible에서도 마찬가지입니다. 더 높은 권한을 가진 곳에서 정의된 변수가 우선합니다.

Ansible의 변수 우선순위는 무려 22단계나 됩니다. 하지만 실무에서 자주 마주치는 것은 몇 가지로 압축됩니다.

가장 낮은 것부터 나열하면 role defaults, inventory group_vars, inventory host_vars, playbook vars, task vars, 그리고 가장 높은 extra vars입니다. extra vars는 명령줄에서 -e 옵션으로 전달하는 변수입니다.

이것은 왕중의 왕입니다. 어디에서 어떤 값을 정의했든, extra vars가 있으면 그 값이 최종 승자가 됩니다.

위의 코드를 보겠습니다. http_port가 세 곳에서 정의되어 있습니다.

host_vars에서 8080, group_vars에서 80, playbook vars에서 3000입니다. 만약 명령줄에서 -e "http_port=9000"을 전달하면 최종 값은 9000이 됩니다.

왜 이런 복잡한 구조가 필요할까요? 유연성 때문입니다.

기본값은 role defaults에 두고, 환경별 설정은 group_vars에, 특정 서버만의 예외는 host_vars에 둘 수 있습니다. 그리고 긴급 상황에서는 extra vars로 모든 것을 덮어쓸 수 있습니다.

초보자들이 자주 겪는 문제는 어디서 변수가 정의되었는지 추적하지 못하는 것입니다. 디버깅할 때는 ansible-playbook에 -v 옵션을 붙여서 변수 값을 확인하세요.

김개발 씨는 group_vars에 정의된 값이 자신의 플레이북 변수를 덮어쓰고 있었다는 것을 알게 되었습니다. 파일 위치를 확인하니 금방 해결할 수 있었습니다.

실전 팁

💡 - 우선순위를 외우기 어려우면 "구체적인 것이 일반적인 것보다 우선한다"고 기억하세요

• 디버깅할 때는 ansible-playbook -v로 실제 사용되는 변수 값을 확인하세요

---

3. Facts 수집 개념

김개발 씨가 새 서버를 추가했는데 운영체제가 Ubuntu인지 CentOS인지에 따라 다른 패키지 관리자를 써야 합니다. 일일이 확인해서 조건문을 걸어야 할까요?

박시니어 씨가 말합니다. "Ansible이 알아서 수집해주는 정보가 있어요.

Facts라고 해요."

Facts는 Ansible이 원격 서버에 접속할 때 자동으로 수집하는 시스템 정보입니다. 마치 의사가 진료 전에 환자의 기본 정보를 확인하는 것처럼, Ansible도 작업 전에 서버의 운영체제, 메모리, 네트워크 정보 등을 미리 파악해둡니다.

다음 코드를 살펴봅시다.

# Facts를 활용한 조건부 작업
- name: 운영체제별 패키지 설치
  hosts: all
  tasks:
    - name: Ubuntu에서 nginx 설치
      apt:
        name: nginx
        state: present
      when: ansible_os_family == "Debian"

    - name: CentOS에서 nginx 설치
      yum:
        name: nginx
        state: present
      when: ansible_os_family == "RedHat"

    - name: 시스템 정보 출력
      debug:
        msg: "호스트명: {{ ansible_hostname }}, OS: {{ ansible_distribution }}"

신입 개발자 김개발 씨에게 새로운 미션이 주어졌습니다. 회사의 서버 50대에 모니터링 에이전트를 설치해야 합니다.

문제는 서버마다 운영체제가 다르다는 것입니다. Ubuntu도 있고, CentOS도 있고, Amazon Linux도 있습니다.

김개발 씨는 처음에 엑셀 파일을 열어 서버 목록을 정리하려 했습니다. 하지만 박시니어 씨가 말렸습니다.

"그럴 필요 없어요. Ansible이 알아서 파악해요." Facts란 무엇일까요?

병원에 가면 간호사가 먼저 체온, 혈압, 몸무게를 측정합니다. 의사는 이 기본 정보를 바탕으로 진료를 시작하죠.

Ansible의 Facts도 똑같은 역할을 합니다. 플레이북을 실행하면 가장 먼저 모든 대상 서버에 접속해서 시스템 정보를 수집합니다.

Facts에는 어떤 정보가 담겨 있을까요? ansible_os_family는 운영체제 계열을, ansible_distribution은 정확한 배포판 이름을, ansible_memtotal_mb는 전체 메모리 용량을, ansible_default_ipv4는 기본 네트워크 정보를 담고 있습니다.

이 외에도 수백 가지 정보가 자동으로 수집됩니다. 위의 코드를 살펴보겠습니다.

when 조건문에서 ansible_os_family를 확인하고 있습니다. Debian 계열(Ubuntu)이면 apt를 사용하고, RedHat 계열(CentOS)이면 yum을 사용합니다.

하나의 플레이북으로 모든 서버를 처리할 수 있는 것입니다. Facts 수집은 기본적으로 활성화되어 있습니다.

하지만 서버가 수백 대라면 수집 시간이 꽤 걸릴 수 있습니다. 이럴 때는 gather_facts: no로 수집을 비활성화할 수 있습니다.

물론 그러면 Facts 변수는 사용할 수 없습니다. 실무에서 Facts는 정말 유용합니다.

메모리가 4GB 이상인 서버에만 특정 작업을 하거나, 특정 커널 버전 이상인 서버만 업데이트하는 등 세밀한 조건 분기가 가능합니다. 김개발 씨는 Facts를 활용해서 50대 서버에 조건별로 다른 설치 스크립트를 적용했습니다.

수작업으로 분류할 필요가 전혀 없었습니다.

실전 팁

💡 - Facts 수집이 불필요하면 gather_facts: no로 실행 속도를 높이세요

• ansible_facts 딕셔너리로도 접근 가능합니다 (ansible_facts['os_family'])

---

4. setup 모듈로 시스템 정보 조회

김개발 씨가 특정 서버의 상세 정보를 알고 싶어졌습니다. IP 주소, 디스크 용량, CPU 코어 수까지 한눈에 보고 싶은데 어떻게 해야 할까요?

박시니어 씨가 터미널을 열며 말합니다. "setup 모듈을 써보세요."

setup 모듈은 Facts를 수동으로 조회할 수 있게 해주는 Ansible 내장 모듈입니다. 마치 서버에게 "너 자신을 소개해봐"라고 말하는 것과 같습니다.

플레이북 없이 명령 한 줄로 서버의 모든 정보를 확인할 수 있어 디버깅에 매우 유용합니다.

다음 코드를 살펴봅시다.

# 명령줄에서 Facts 전체 조회
# ansible webserver -m setup

# 특정 Facts만 필터링
# ansible webserver -m setup -a "filter=ansible_distribution*"

# 플레이북에서 setup 모듈 활용
- name: 시스템 정보 수집 및 출력
  hosts: all
  tasks:
    - name: 수동으로 Facts 수집
      setup:
        filter: "ansible_*"
      register: system_facts

    - name: 메모리 정보만 확인
      setup:
        filter: "ansible_memory_mb"

    - name: 디스크 정보 출력
      debug:
        var: ansible_devices

어느 날 장애가 발생했습니다. 특정 서버에서만 애플리케이션이 느리게 동작한다는 보고가 들어왔습니다.

김개발 씨는 해당 서버의 메모리와 디스크 상태를 확인해야 했습니다. SSH로 접속해서 free -m, df -h 명령어를 하나씩 실행할 수도 있습니다.

하지만 박시니어 씨는 더 빠른 방법을 알려주었습니다. "Ansible setup 모듈을 쓰면 한 번에 다 볼 수 있어요." setup 모듈은 Facts 수집을 담당하는 내장 모듈입니다.

플레이북을 실행하면 맨 처음에 "Gathering Facts..."라는 메시지가 뜨는데, 바로 이때 setup 모듈이 자동으로 실행되는 것입니다. 하지만 우리가 직접 setup 모듈을 호출할 수도 있습니다.

터미널에서 ansible webserver -m setup을 실행하면 어떻게 될까요? 엄청나게 많은 정보가 JSON 형태로 쏟아져 나옵니다.

운영체제 정보, 커널 버전, 네트워크 인터페이스, 마운트된 디스크, CPU 정보, 메모리 정보까지 서버에 대한 거의 모든 것이 담겨 있습니다. 정보가 너무 많아서 원하는 것만 보고 싶다면 filter 옵션을 사용합니다.

ansible webserver -m setup -a "filter=ansible_memory*"라고 하면 메모리 관련 Facts만 출력됩니다. 와일드카드(*)를 지원하기 때문에 유연하게 검색할 수 있습니다.

위의 코드에서 플레이북 안에서 setup 모듈을 사용하는 방법도 볼 수 있습니다. register를 사용하면 수집된 Facts를 변수에 저장해서 나중에 활용할 수 있습니다.

자주 사용하는 Facts 필터를 정리해보겠습니다. ansible_distribution*은 OS 배포판 정보, ansible_memory_mb는 메모리 정보, ansible_devices는 디스크 장치 정보, ansible_default_ipv4는 기본 IP 주소 정보를 보여줍니다.

김개발 씨는 setup 모듈로 문제 서버의 메모리 사용량을 확인했습니다. 예상대로 메모리가 거의 고갈 상태였습니다.

원인을 빠르게 파악할 수 있었습니다.

실전 팁

💡 - 전체 Facts를 파일로 저장하려면 ansible host -m setup > facts.json 사용

• gather_subset 옵션으로 수집할 Facts 범위를 제한할 수 있습니다

---

5. 커스텀 Facts 생성

김개발 씨의 회사에는 자체 개발한 애플리케이션이 있습니다. 이 앱의 버전 정보를 Ansible에서 활용하고 싶은데, 기본 Facts에는 당연히 없습니다.

어떻게 해야 할까요? 박시니어 씨가 답합니다.

"커스텀 Facts를 만들면 돼요."

커스텀 Facts는 사용자가 직접 정의하는 Facts입니다. 기본 Facts에 없는 회사 고유의 정보나 애플리케이션 상태를 Ansible에서 변수처럼 사용할 수 있게 해줍니다.

원격 서버의 특정 경로에 스크립트나 파일을 배치하면 자동으로 수집됩니다.

다음 코드를 살펴봅시다.

# /etc/ansible/facts.d/company.fact (원격 서버에 배치)
[application]
name = inventory-service
version = 2.3.1
environment = production

# 또는 실행 가능한 스크립트로 작성
#!/bin/bash
# /etc/ansible/facts.d/app_status.fact
echo '{"app": {"status": "running", "uptime": "'$(uptime -p)'"}}'

# 플레이북에서 커스텀 Facts 사용
- name: 커스텀 Facts 활용
  hosts: appservers
  tasks:
    - name: 애플리케이션 정보 출력
      debug:
        msg: "앱: {{ ansible_local.company.application.name }} v{{ ansible_local.company.application.version }}"

    - name: 버전이 낮으면 업데이트 알림
      debug:
        msg: "업데이트가 필요합니다!"
      when: ansible_local.company.application.version is version('3.0.0', '<')

김개발 씨의 팀에서는 자체 개발한 마이크로서비스가 10개 넘게 돌아가고 있습니다. 각 서비스의 버전을 확인해서 특정 버전 이하면 자동으로 업데이트하는 플레이북을 만들고 싶었습니다.

하지만 Ansible 기본 Facts에는 이런 정보가 없습니다. 박시니어 씨가 해결책을 제시했습니다.

"우리만의 Facts를 만들면 돼요. Ansible은 그것도 지원해요." 커스텀 Facts는 어떻게 작동할까요?

원격 서버의 /etc/ansible/facts.d/ 디렉토리가 마법의 장소입니다. 이 경로에 .fact 확장자를 가진 파일을 두면 Ansible이 Facts 수집 시 자동으로 읽어들입니다.

파일 형식은 INI 또는 JSON을 사용할 수 있습니다. 위 코드의 첫 번째 예제는 INI 형식입니다.

[application] 섹션 아래에 name, version, environment를 정의했습니다. 이렇게 하면 ansible_local.company.application.name으로 접근할 수 있습니다.

company는 파일명(company.fact)에서 가져옵니다. 두 번째 예제는 실행 가능한 스크립트입니다.

스크립트에 실행 권한이 있으면 Ansible은 이를 실행하고 출력 결과를 JSON으로 파싱합니다. 동적으로 값을 생성해야 할 때 유용합니다.

예를 들어 현재 실행 중인 프로세스 수나 가동 시간 같은 정보를 실시간으로 수집할 수 있습니다. 커스텀 Facts를 사용할 때는 반드시 ansible_local을 통해 접근해야 합니다.

일반 Facts는 ansible_로 시작하지만, 커스텀 Facts는 ansible_local 아래에 모입니다. 실무에서 커스텀 Facts는 다양하게 활용됩니다.

애플리케이션 버전 관리, 라이선스 정보 확인, 배포 환경 구분, 마지막 배포 시각 기록 등에 사용할 수 있습니다. 주의할 점이 있습니다.

커스텀 Facts 파일은 Ansible이 실행되기 전에 미리 서버에 배치되어 있어야 합니다. 보통 서버 초기 프로비저닝 단계에서 함께 배포합니다.

김개발 씨는 각 마이크로서비스 서버에 버전 정보를 담은 커스텀 Facts 파일을 배포했습니다. 이제 버전 기반 조건부 업데이트가 가능해졌습니다.

실전 팁

💡 - 스크립트형 Facts는 반드시 실행 권한(chmod +x)을 부여해야 합니다

• ansible_local이 비어있다면 facts.d 디렉토리가 없거나 파일 형식이 잘못된 것입니다

---

6. 변수 파일 분리하기

플레이북이 점점 길어지고 있습니다. 변수 정의만 50줄이 넘어가니 코드 읽기가 힘들어졌습니다.

김개발 씨가 한숨을 쉬자 박시니어 씨가 조언합니다. "변수는 별도 파일로 분리하는 게 정석이에요."

변수 파일 분리는 플레이북의 가독성과 유지보수성을 높이는 핵심 기법입니다. vars_files로 외부 YAML 파일을 불러오거나, group_vars와 host_vars 디렉토리 구조를 활용하면 역할별로 변수를 깔끔하게 관리할 수 있습니다.

다음 코드를 살펴봅시다.

# vars/database.yml - 데이터베이스 관련 변수
db_host: "mysql.internal.company.com"
db_port: 3306
db_name: "inventory_db"
db_user: "app_user"

# vars/application.yml - 애플리케이션 관련 변수
app_port: 8080
app_log_level: "INFO"
app_max_connections: 100

# playbook.yml - 변수 파일 불러오기
- name: 애플리케이션 배포
  hosts: appservers
  vars_files:
    - vars/database.yml
    - vars/application.yml
  tasks:
    - name: 설정 확인
      debug:
        msg: "DB: {{ db_host }}:{{ db_port }}, App Port: {{ app_port }}"

# 디렉토리 구조 예시
# inventory/
#   group_vars/
#     all.yml          # 모든 호스트 공통 변수
#     webservers.yml   # webservers 그룹 변수
#   host_vars/
#     web01.yml        # web01 호스트 전용 변수

김개발 씨의 플레이북은 어느새 500줄을 넘어섰습니다. 그중 절반 가까이가 vars 블록이었습니다.

데이터베이스 연결 정보, 애플리케이션 설정, 환경별 구분값 등이 뒤섞여 있어서 필요한 변수를 찾기가 점점 어려워졌습니다. 박시니어 씨가 화면을 보더니 말했습니다.

"이건 리팩토링이 필요하네요. 변수를 역할별로 파일을 나눠야 해요." 변수 파일 분리는 왜 필요할까요?

서류를 생각해보세요. 모든 문서를 한 폴더에 넣으면 처음에는 괜찮지만, 문서가 100개, 1000개가 되면 찾기 힘들어집니다.

인사 서류, 회계 서류, 계약 서류로 폴더를 나누면 관리가 쉬워지죠. 변수도 마찬가지입니다.

Ansible에서 변수를 분리하는 방법은 크게 두 가지입니다. 첫째는 vars_files 지시어를 사용하는 것이고, 둘째는 디렉토리 규칙을 따르는 것입니다.

vars_files를 사용하면 원하는 YAML 파일을 명시적으로 불러올 수 있습니다. 위 코드처럼 vars/database.yml과 vars/application.yml을 각각 불러오면, 두 파일에 정의된 모든 변수를 플레이북에서 사용할 수 있습니다.

디렉토리 규칙은 더 자동화된 방식입니다. inventory 디렉토리 안에 group_vars와 host_vars 디렉토리를 만들면, Ansible이 자동으로 해당 그룹이나 호스트에 변수를 적용합니다.

예를 들어 group_vars/webservers.yml에 정의한 변수는 webservers 그룹의 모든 호스트에 적용됩니다. 실무에서 권장하는 구조가 있습니다.

group_vars/all.yml에는 모든 서버에 공통인 변수를, group_vars/{그룹명}.yml에는 그룹별 변수를, host_vars/{호스트명}.yml에는 특정 호스트만의 예외 변수를 둡니다. 민감한 정보는 어떻게 할까요?

비밀번호나 API 키 같은 값은 ansible-vault로 암호화한 별도 파일에 저장합니다. vars_files로 암호화된 파일도 불러올 수 있습니다.

김개발 씨는 500줄짜리 플레이북을 리팩토링했습니다. 변수는 역할별로 5개 파일로 나누고, 플레이북 본문은 100줄로 줄었습니다.

코드 리뷰에서 팀원들의 찬사를 받았습니다.

실전 팁

💡 - group_vars/all.yml은 모든 호스트에 적용되는 기본값을 넣기 좋은 곳입니다

• 민감한 변수는 vault_로 시작하는 별도 파일로 분리하고 암호화하세요

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!