Red Hat Certified Engineer (RHCE) #12 Collection: Galaxy, Automation Hub

#11 Role 작성과 사용에서 task와 변수, handler를 role 단위로 묶어 재사용하는 법을 익혔습니다. 그런데 Ansible에는 role보다 한 단계 위의 묶음이 있습니다. 바로 collection입니다. 이번 글에서는 collection이 무엇이며, ansible-galaxy로 collection과 role을 어떻게 내려받는지, 그리고 시험에서 자주 나오는 requirements.yml 일괄 설치 흐름을 실기 관점에서 정리하겠습니다.

Collection이란 무엇인가 #

collection은 module과 role, plugin을 하나로 묶은 배포 단위입니다. 과거에는 Ansible 본체에 모든 module이 함께 들어 있었지만, 지금은 본체(ansible-core)와 콘텐츠(collection)가 분리되어 있습니다. firewalld나 selinux 관련 module도 본체가 아니라 별도 collection에 들어 있어서, 필요하면 해당 collection을 내려받아 사용합니다.

collection 하나에는 다음 콘텐츠가 들어갈 수 있습니다.

• module. task에서 직접 호출하는 작업 단위. 예를 들어 ansible.posix collection의 firewalld module
• role. task와 변수, handler를 묶은 재사용 단위. #11에서 다룬 그 role
• plugin. filter, lookup, connection 등 Ansible 동작을 확장하는 코드

collection은 보통 community.general, ansible.posix, redhat.rhel_system_roles처럼 namespace.collection 형식의 이름을 가집니다. 앞쪽이 namespace(제작 주체)이고 뒤쪽이 collection 이름입니다.

FQCN: namespace.collection.module #

collection 시대의 핵심 규칙이 FQCN(Fully Qualified Collection Name)입니다. module을 부를 때 짧은 이름이 아니라 namespace.collection.module 전체 경로로 부르는 방식입니다.

# 짧은 이름 (권장하지 않음, 모호함)
- name: firewall 설정
  firewalld:
    service: https
    state: enabled

# FQCN (권장)
- name: firewall 설정
  ansible.posix.firewalld:
    service: https
    state: enabled

ansible.posix.firewalld는 ansible.posix collection의 firewalld module이라는 뜻입니다. 같은 이름의 module이 여러 collection에 있을 수 있으므로, FQCN을 쓰면 어느 collection의 module인지 모호함 없이 지정됩니다. 시험에서는 FQCN으로 작성하는 습관을 권장합니다. 채점 환경의 collection 구성과 무관하게 정확히 의도한 module이 실행되기 때문입니다.

본체에 기본 포함되는 module(예 copy, template, service)은 사실 ansible.builtin namespace에 속합니다. 따라서 ansible.builtin.copy, ansible.builtin.service처럼 쓰는 것이 정확한 FQCN입니다. 짧은 이름으로도 동작하지만 FQCN이 명시적입니다.

collection 설치: ansible-galaxy collection install #

collection은 ansible-galaxy collection install 명령으로 설치합니다.

# 단일 collection 설치
ansible-galaxy collection install ansible.posix

# 특정 버전 지정
ansible-galaxy collection install ansible.posix:1.5.4

# 설치된 collection 목록 확인
ansible-galaxy collection list

설치된 collection이 어디에 들어가는지가 시험에서 중요합니다. 기본값으로는 사용자 홈의 ~/.ansible/collections에 설치되지만, 프로젝트 안에 격리해 두는 방식을 권장합니다. -p 옵션으로 설치 경로를 직접 지정합니다.

# 프로젝트 디렉터리 안 collections 경로에 설치
ansible-galaxy collection install ansible.posix -p collections

이렇게 프로젝트 루트의 collections 디렉터리에 설치하면, 같은 디렉터리에서 플레이북을 실행할 때 Ansible이 그 경로를 자동으로 인식합니다. 시험에서 작업 디렉터리가 정해져 있다면 이 방식이 안전합니다.

requirements.yml로 일괄 설치 #

collection이 여러 개일 때 명령을 하나씩 치는 대신, requirements.yml 파일에 의존성을 적어 두고 한 번에 설치하는 방식이 표준입니다. 이 흐름이 RHCE 시험의 단골 유형입니다. 문제에서 특정 collection이나 role을 내려받아 사용하라고 지시하면, requirements.yml에 적고 일괄 설치한 뒤 FQCN으로 호출하는 패턴을 씁니다.

# collections/requirements.yml
---
collections:
  - name: ansible.posix
  - name: community.general
    version: 6.0.0

이 파일을 기준으로 collection을 일괄 설치합니다.

ansible-galaxy collection install -r collections/requirements.yml -p collections

-r은 requirements 파일을 읽어 들이는 옵션이고, -p collections로 설치 경로를 프로젝트 안으로 고정합니다. 시험 환경이 인터넷에 직접 닿지 못하고 사내 저장소나 Automation Hub를 가리키도록 설정되어 있을 수 있으니, 설치 명령이 실패하면 source 설정부터 확인하겠습니다.

role도 requirements로 설치 #

requirements.yml은 collection뿐 아니라 role도 함께 설치할 수 있습니다. role과 collection을 한 파일에 적되, 각각 roles와 collections 키 아래에 둡니다.

# roles/requirements.yml
---
roles:
  - name: geerlingguy.nginx
  - src: https://github.com/example/my-role.git
    scm: git
    name: my_role

collections:
  - name: ansible.posix

role은 ansible-galaxy role install로, collection은 ansible-galaxy collection install로 설치하지만, 두 콘텐츠가 섞인 requirements 파일은 ansible-galaxy install로 한 번에 처리할 수 있습니다.

# role만 설치
ansible-galaxy role install -r roles/requirements.yml -p roles

# role과 collection을 한 번에 설치
ansible-galaxy install -r roles/requirements.yml

role의 기본 설치 경로는 ~/.ansible/roles이며, -p roles로 프로젝트 안 roles 디렉터리에 격리할 수 있습니다.

Galaxy vs Automation Hub #

collection을 내려받는 출처는 크게 두 곳입니다.

Ansible Galaxy는 커뮤니티 collection이 모이는 공개 저장소입니다. community.general 같은 collection이 여기에서 배포됩니다. 반면 Automation Hub는 Red Hat이 품질과 지원을 보증하는 인증 콘텐츠를 제공하는 저장소입니다. 기업이 지원받는 안정적인 collection을 쓰려면 Automation Hub를 출처로 설정합니다.

어느 출처를 쓸지는 ansible.cfg의 [galaxy] 섹션에서 server 목록으로 지정합니다.

# ansible.cfg
[galaxy]
server_list = automation_hub, galaxy

[galaxy_server.automation_hub]
url = https://console.redhat.com/api/automation-hub/content/published/
auth_url = https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token = <your-token>

[galaxy_server.galaxy]
url = https://galaxy.ansible.com/

server_list에 적힌 순서대로 출처를 탐색합니다. 시험에서는 출처가 미리 설정되어 있는 경우가 많으므로, 새로 구성하기보다 주어진 설정을 읽고 그대로 활용하는 편이 빠릅니다.

collections_path와 ansible.cfg #

설치한 collection을 Ansible이 어디에서 찾는지는 ansible.cfg의 collections_path 설정이 결정합니다(과거 이름은 collections_paths이며 둘 다 인식됩니다).

# ansible.cfg
[defaults]
inventory = inventory
collections_path = ./collections:~/.ansible/collections

콜론(:)으로 여러 경로를 구분하며, 앞쪽 경로부터 우선 탐색합니다. 위 설정은 프로젝트 안 collections를 먼저 찾고, 없으면 사용자 홈을 봅니다. 한 가지 편의가 있는데, 프로젝트 디렉터리 바로 아래에 collections 디렉터리가 있으면 collections_path를 굳이 지정하지 않아도 Ansible이 자동으로 인식합니다. 그래서 -p collections로 내려받는 관례가 시험에서 안전한 선택입니다.

role의 탐색 경로는 별도로 roles_path가 담당합니다.

[defaults]
roles_path = ./roles:~/.ansible/roles

예제: requirements로 설치 후 FQCN으로 사용 #

collection을 내려받아 FQCN으로 호출하는 전체 흐름을 한 번에 보겠습니다. 먼저 프로젝트 구조입니다.

project/
├── ansible.cfg
├── inventory
├── collections/
│   └── requirements.yml
└── site.yml

ansible.cfg에서 작업 디렉터리를 정돈합니다.

# ansible.cfg
[defaults]
inventory = inventory
collections_path = ./collections
remote_user = devops

[privilege_escalation]
become = true

설치할 collection을 requirements.yml에 적고, 일괄 설치한 뒤 결과를 확인합니다.

# collections/requirements.yml
---
collections:
  - name: ansible.posix

ansible-galaxy collection install -r collections/requirements.yml -p collections
ansible-galaxy collection list | grep ansible.posix

이제 플레이북에서 FQCN으로 module을 호출합니다.

# site.yml
---
- name: web server 방화벽 구성
  hosts: webservers
  tasks:
    - name: httpd 설치
      ansible.builtin.dnf:
        name: httpd
        state: present

    - name: httpd 서비스 활성화
      ansible.builtin.service:
        name: httpd
        state: started
        enabled: true

    - name: https 서비스 방화벽 허용
      ansible.posix.firewalld:
        service: https
        permanent: true
        immediate: true
        state: enabled

플레이북을 실행합니다.

ansible-navigator run site.yml -m stdout
# 또는
ansible-playbook site.yml

ansible.posix.firewalld가 별도 collection의 module이므로, 사전에 collection을 설치하지 않으면 module을 찾지 못한다는 오류가 납니다. 따라서 설치 먼저, 사용 나중이라는 순서가 채점에서 점수를 가릅니다.

시험 포인트 #

• FQCN으로 작성합니다. module은 namespace.collection.module 형식으로 부릅니다. 예를 들어 ansible.posix.firewalld, ansible.builtin.copy로 씁니다. 짧은 이름은 모호하므로 시험에서는 FQCN을 권장합니다.
• requirements.yml로 일괄 설치합니다. 여러 collection이나 role이 필요하면 collections/requirements.yml에 적고 ansible-galaxy collection install -r ... -p collections로 한 번에 내려받습니다. 이 흐름이 시험 단골입니다.
• 설치 경로를 프로젝트 안으로 고정합니다. -p collections로 내려받으면 같은 디렉터리에서 플레이북을 실행할 때 자동으로 인식됩니다. role은 -p roles로 격리합니다.
• collections_path를 확인합니다. ansible.cfg의 collections_path와 roles_path가 어느 경로를 보는지 확인하고, 설치 경로와 맞추겠습니다.
• 설치 먼저, 사용 나중. collection을 내려받기 전에 FQCN을 호출하면 module을 찾지 못합니다. 플레이북 실행 전에 설치를 완료하겠습니다.
• 출처 설정을 그대로 활용합니다. Galaxy와 Automation Hub 출처가 미리 구성된 경우, 새로 만들기보다 ansible.cfg의 [galaxy] 설정을 읽고 활용하는 편이 빠릅니다.

정리 #

이번 글에서 잡은 것:

• collection은 module과 role, plugin을 묶은 배포 단위이며, 본체(ansible-core)와 콘텐츠가 분리되어 있습니다.
• FQCN(namespace.collection.module)으로 module을 호출하면 모호함이 없습니다. 시험에서는 FQCN을 권장합니다.
• ansible-galaxy collection install로 설치하며, -r requirements.yml로 일괄 설치하고 -p collections로 경로를 고정합니다.
• requirements.yml은 collection과 role을 함께 적을 수 있고, ansible-galaxy install로 한 번에 처리할 수 있습니다.
• Galaxy는 커뮤니티 공개 저장소, Automation Hub는 Red Hat 인증 콘텐츠 저장소입니다.
• 탐색 경로는 ansible.cfg의 collections_path와 roles_path가 결정합니다.

다음: system roles #

collection으로 외부 콘텐츠를 가져오는 법을 익혔습니다. 이제 Red Hat이 RHEL 시스템 관리용으로 직접 제공하는 인증 role 묶음인 rhel-system-roles로 들어갑니다.

#13 system roles (rhel-system-roles)에서는 redhat.rhel_system_roles collection의 설치, timesync와 firewall, selinux 같은 대표 role의 변수 구조, 그리고 시험에서 자주 나오는 “system role로 이 설정을 적용하라” 유형까지 직접 작성하며 정리하겠습니다.