Ansible Molecule과 Docker로 Ansible 역할 자동 테스트하기

소개

Ansible Molecule은 Ansible 역할(Role)과 플레이북(Playbook)을 다양한 시나리오에서 테스트하고 검증하기 위한 도구입니다. Molecule을 사용하면 역할이 타깃 서버에 적용될 때 의도한 대로 동작하는지 자동으로 확인할 수 있습니다. Molecule은 Docker, Podman, Vagrant 같은 컨테이너/가상화 드라이버와 AWS, Azure, GCP 같은 클라우드 제공자도 지원합니다.

이 문서는 다음을 안내합니다.

• Ansible, Docker, Molecule 설치 방법
• Molecule로 역할 보일러플레이트 생성하기
• Docker 인스턴스를 이용한 converge, verify, destroy 워크플로
• pytest-testinfra로 역할 상태를 검사하는 테스트 스크립트 작성

중급 사용자 관점에서 설명하므로 Ansible 기본 개념(플레이북, 역할, 태스크)에 대한 이해가 필요합니다.

준비 조건

• Linux 시스템: 이 예제는 Ubuntu 22.04 서버(호스트명 ansible-test)를 기준으로 합니다. 로컬 개발 환경이나 CI 러너에서도 동일한 원칙이 적용됩니다.
• 비루트 사용자: sudo 권한이 있는 사용자(예: alice)
• Ansible 기본 지식: 역할, 태스크, 변수 사용법을 알고 있어야 합니다.

Important: Molecule은 테스트 대상에 Python이 설치되어 있어야 작동합니다. 테스트 이미지에 Python이 포함되어 있는지 확인하세요.

1. 의존성 설치 개요

이 섹션에서는 Python3, pip, virtualenv, Ansible, Docker CE를 설치합니다. 명령은 Ubuntu/Debian 계열을 기준으로 합니다.

먼저 패키지 인덱스를 갱신합니다.

sudo apt update

그다음 Python3, pip3, virtualenv와 Ansible 관련 패키지를 설치합니다.

sudo apt install python3 python3-pip python3-venv ansible ca-certificates curl gnupg lsb-release

설치 중에 y를 입력하여 진행합니다.

Docker CE는 공식 Docker 저장소를 추가해 설치합니다. 키 저장 디렉터리를 만들고 GPG 키를 가져옵니다.

sudo mkdir -m 0755 -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

저장소를 추가합니다.

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

패키지 인덱스를 다시 갱신한 뒤 Docker CE를 설치합니다.

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

현재 사용자를 docker 그룹에 추가하면 sudo 없이 docker 명령을 실행할 수 있습니다.

sudo usermod -aG docker $USER

설치 검증을 위해 hello-world 이미지를 실행해 보세요.

docker run hello-world

정상적으로 실행되면 다음과 비슷한 출력이 나옵니다.

설치가 완료되면 다음 단계로 가상환경을 만들고 Molecule을 설치합니다.

2. Molecule 설치 및 가상환경 구성

개발 환경용으로 Python 가상환경을 만들어 Molecule과 관련 플러그인을 격리해 설치합니다.

python3 -m venv ansible-venv
source ansible-venv/bin/activate
cd ansible-venv/
pip3 install wheel molecule 'molecule-plugins[docker]'

설치 중 출력 예시는 다음과 같습니다.

가상환경을 사용하면 시스템 파이썬과 충돌 없이 여러 프로젝트를 관리할 수 있습니다.

Note: CI 환경에서는 시스템 가상환경 대신 컨테이너 기반 빌드 이미지를 사용하거나, 동일한 가상환경을 재현하는 스크립트를 저장소에 포함시키세요.

3. Molecule로 Ansible 역할 초기화

이제 Molecule로 역할 템플릿을 생성합니다. 이 예제에서는 LEMP 스택(Nginx, MariaDB, PHP-FPM)을 설치하는 역할을 만듭니다.

molecule init role test.lemp --driver-name docker

명령을 실행하면 현재 디렉터리에 lemp 디렉터리가 생성됩니다.

생성된 디렉터리로 이동합니다.

cd lemp

tasks/main.yml 파일을 열어 패키지 설치와 서비스 활성화 태스크를 정의합니다.

nano tasks/main.yml

다음 내용을 추가합니다.

---
- name: "Installing LEMP Stack"
  apt:
    name: "{{ pkg_list }}"
    state: present

- name: "Ensure LEMP Services is running"
  service:
    name: "{{ item }}"
    state: started
    enabled: true
  with_items: "{{ svc_list }}"

저장 후 vars/main.yml에 패키지 목록과 서비스 목록 변수를 정의합니다.

nano vars/main.yml

---
pkg_list:
  - nginx
  - mariadb-server
  - php-fpm
  - php-cli
svc_list:
  - nginx
  - mariadb
  - php8.1-fpm

이 시점에서 역할이 설치할 패키지와 활성화할 서비스가 명확히 정의되어 있습니다.

4. 테스트 인스턴스 설정

Molecule은 테스트 플랫폼(인스턴스)을 molecule/default/molecule.yml에서 정의합니다. 이 예제는 Python이 미리 설치된 Docker 이미지 mipguerrero26/ubuntu-python3를 사용합니다.

먼저 이미지를 로컬로 풀합니다.

docker pull mipguerrero26/ubuntu-python3

이미지 목록에서 다운로드 여부를 확인합니다.

docker images

컨테이너에 접속해 Python과 OS 정보를 확인할 수 있습니다.

docker run -it mipguerrero26/ubuntu-python3 /bin/bash
python3 --version
cat /etc/lsb-release
exit

molecule/default/molecule.yml의 platforms 섹션을 편집하여 테스트 인스턴스 이름과 이미지를 지정하고 privileged 옵션을 설정합니다.

nano molecule/default/molecule.yml

다음처럼 수정합니다.

platforms:
  - name: instance-ubuntu22.04
    image: mipguerrero26/ubuntu-python3
    privileged: true

설정 후 molecule list로 인스턴스를 확인할 수 있습니다.

molecule list

5. converge로 역할 적용

molecule converge를 실행하면 Molecule이 정의된 플랫폼을 생성하고 역할을 해당 인스턴스에 적용합니다.

molecule converge

실행하면 Docker 컨테이너가 생성되고, Ansible이 역할을 적용합니다.

컨테이너가 실행 중인지 docker ps로 확인하고, 컨테이너 내부에 접속해 포트와 서비스 상태를 점검합니다.

docker ps
docker exec -it instance-ubuntu22.04 /bin/bash
ss -tulpn
ss -pl | grep php

포트 80(Nginx), 3306(MariaDB), PHP-FPM 소켓(/run/php/php8.1-fpm.sock)이 있는지 확인하면 역할이 올바르게 적용되었는지 판단할 수 있습니다.

작업이 끝나면 molecule destroy로 인스턴스를 정리합니다.

molecule destroy

6. testinfra로 자동화된 검증 스크립트 작성

Molecule의 verifier로 pytest-testinfra를 사용하면 인스턴스 상태(패키지 설치 여부, 서비스 실행 상태 등)를 코드로 검증할 수 있습니다.

먼저 pytest-testinfra를 설치합니다.

pip3 install pytest-testinfra

테스트 디렉터리를 만들고 기본 테스트 파일을 생성합니다.

mkdir -p molecule/default/tests/
nano molecule/default/tests/test_default.py

다음 파이썬 스크립트는 패키지와 서비스 상태를 검사합니다.

import os
import pytest
import testinfra.utils.ansible_runner

testinfra_hosts = testinfra.utils.ansible_runner.AnsibleRunner(
    os.environ['MOLECULE_INVENTORY_FILE']).get_hosts('all')

@pytest.mark.parametrize('pkg', [
  'nginx',
  'mariadb-server',
  'php-fpm'
])
def test_pkg(host, pkg):
    package = host.package(pkg)

    assert package.is_installed

@pytest.mark.parametrize('svc', [
  'nginx',
  'mariadb',
  'php8.1-fpm'
])
def test_svc(host, svc):
    service = host.service(svc)

    assert service.is_running
    assert service.is_enabled

molecule/default/molecule.yml의 verifier 섹션을 testinfra로 지정합니다.

nano molecule/default/molecule.yml

verifier:
  name: testinfra
  directory: tests

molecule test 명령은 create → converge → verify → destroy 전체 시나리오를 실행합니다.

molecule test

실행 과정 중 기존 인스턴스가 있으면 먼저 destroy하고 새로 생성합니다.

성공하면 pytest 출력처럼 collected N items - N passed 를 확인할 수 있습니다.

테스트가 끝나면 Molecule이 인스턴스를 파괴합니다.

7. 개발 중 프로세스 권장 흐름

일반적으로 역할 개발에서는 다음 사이클을 반복합니다.

1. molecule init로 역할 생성
2. tasks, handlers, templates, vars 등 역할 구성
3. molecule converge로 역할 적용(빠른 수동 확인)
4. tests 디렉터리에 testinfra 테스트 추가
5. molecule verify로 테스트 실행
6. 실패 시 역할 수정 → 3 반복
7. 모든 테스트 통과 시 molecule destroy로 정리

명령 요약:

molecule converge
molecule verify
molecule destroy
molecule test
molecule --help

이 워크플로는 로컬 개발 환경과 CI 파이프라인 모두에 동일하게 적용할 수 있어 역할의 신뢰성과 일관성을 높입니다.

8. 실무에서 유용한 추가 정보 및 팁

8.1 대안 접근법

• Podman 드라이버: 시스템에 Podman을 선호하면 Molecule의 Podman 드라이버를 사용해 무루트(rootless) 테스트를 고려하세요.
• Vagrant: 완전한 VM(예: VirtualBox)을 테스트 대상으로 사용하면 컨테이너에서 발생하지 않는 OS 레벨 이슈를 검증할 수 있습니다.
• 클라우드 인스턴스: AWS/Azure/GCP 드라이버를 사용하면 실제 클라우드 런타임 환경에서 역할을 검증할 수 있지만 비용과 시간 측면의 오버헤드가 큽니다.

8.2 실패 케이스와 원인 진단

• 패키지 설치 실패: apt 캐시, 미러, 패키지 이름 불일치, 요구되는 apt-transport-http/https 누락
• 서비스가 시작되지 않음: 구성 파일 오류, 포트 충돌, 종속 서비스 미구동
• testinfra에서 호스트 접속 실패: MOLECULE_INVENTORY_FILE 환경 변수가 올바르지 않거나 python 미설치

진단 팁: molecule converge –debug 혹은 molecule –debug test를 사용해 상세 로그를 확인하세요.

8.3 보안 강화 권장 사항

• 테스트 이미지 신뢰성: 퍼블릭 이미지를 사용할 때는 베이스 이미지의 출처를 확인하고, CI에서는 사내/검증된 이미지 레지스트리를 사용하세요.
• 권한 최소화: 가능하면 privileged 옵션을 사용하지 않는 방향으로 역할을 설계하세요. 테스트 환경에서만 privileged가 필요하면 문서화해 두세요.
• 비밀 관리: 테스트에서 사용하는 민감한 데이터(비밀번호, 토큰 등)는 환경 변수나 secret 매니저로 관리하고 저장소에 하드코딩하지 마세요.

8.4 CI 통합 예시 (간단한 개념)

다음은 Molecule을 CI에서 실행할 때의 간단한 단계입니다.

• 단계 1: 환경 준비 (Docker 데몬 활성화, Python 가상환경 생성)
• 단계 2: 종속성 설치 (pip install molecule ‘molecule-plugins[docker]’ pytest-testinfra)
• 단계 3: docker pull (필요한 테스트 이미지)
• 단계 4: molecule test 실행

GitHub Actions, GitLab CI, Jenkins 등에서 각 단계에 맞는 러너/에이전트를 구성하면 됩니다.

8.5 역할 기반 체크리스트

개발자와 리뷰어가 사용할 수 있는 간단한 체크리스트:

• 역할 구조가 표준화되어 있는가? (tasks, handlers, defaults, vars, templates)
• idempotent한가? 반복 실행 시 변경이 없음을 보장하는가?
• 필요한 변수가 defaults 또는 vars에 정의되어 있는가?
• 서비스 상태와 포트가 테스트로 검증되는가?
• 불필요한 권한 상승을 요구하지 않는가?

이 체크리스트는 코드 리뷰와 CI 통과 전 검증에 유용합니다.

8.6 테스트 케이스 및 수락 기준

예: LEMP 역할의 핵심 테스트 케이스

• 테스트 케이스 1: nginx 패키지가 설치되어 있어야 한다.
  • 수락 기준: testinfra에서 package.is_installed가 True여야 함.
• 테스트 케이스 2: mariadb 서비스가 실행되고 활성화되어 있어야 한다.
  • 수락 기준: service.is_running 및 service.is_enabled가 True여야 함.
• 테스트 케이스 3: php-fpm이 php 소켓을 생성해야 한다.
  • 수락 기준: ss 또는 testinfra 파일 검사로 소켓/포트를 확인.

테스트가 실패하면 역할 태스크, 핸들러, 변수 값을 검토하고 다시 실행합니다.

8.7 마이그레이션 팁

• 기존 Vagrant 기반 역할을 Molecule로 전환할 때는 molecule init로 역할을 재생성하고 기존 tasks/vars를 새 역할로 옮긴 뒤 molecule.yml 플랫폼만 Vagrant로 설정하면 점진적으로 전환할 수 있습니다.
• 클라우드 테스트를 도입할 경우 인프라 프로비저닝 속성을 infrastructure-as-code(IaC)로 분리해 비용 통제를 적용하세요.

9. 미니 방법론: Molecule로 신뢰할 수 있는 역할 만들기(요약 가이드)

1. 역할 템플릿 생성: molecule init role
2. 기능 단위 태스크 작성: 각 패키지/서비스에 대해 idempotent 태스크 작성
3. 변수 및 defaults 정의: 역할 재사용성을 위해 입력 변수 정리
4. 테스트 작성: testinfra로 패키지/서비스/파일/포트 검사 작성
5. 로컬 반복 테스트: molecule test로 반복 실행하며 안정화
6. CI 통합: PR마다 molecule test를 실행해 회귀를 방지

이 방법론은 역할의 신뢰성을 향상시키고 운영 환경 배포 시 예기치 못한 실패를 줄입니다.

10. 1줄 용어집

• Molecule: Ansible 역할 테스트 프레임워크
• testinfra: pytest 기반 서버 상태 검사 라이브러리
• converge: 역할을 인스턴스에 적용하는 단계
• verify: 테스트(검증) 단계

결론

이 튜토리얼에서는 Ubuntu 환경에서 Docker 드라이버를 사용해 Ansible Molecule을 설치하고, 역할 보일러플레이트를 생성한 뒤 testinfra로 자동화된 검증을 수행하는 전체 과정을 설명했습니다. Molecule을 사용하면 로컬 환경과 CI에서 역할을 반복적으로 테스트해 역할의 안정성과 일관성을 확보할 수 있습니다.

요약:

• Molecule은 다양한 드라이버에서 Ansible 역할을 테스트할 수 있는 표준화된 툴입니다.
• Docker 드라이버와 pytest-testinfra를 결합하면 빠르고 자동화된 검증이 가능합니다.
• 개발 → 테스트 → CI 통합으로 역할 신뢰성을 높이세요.

추가 학습: 공식 Ansible Molecule 문서를 참조해 고급 드라이버, 플러그인, CI 통합 예시를 확인하세요.