社内コレクションを作り、版を固定して配布する

목표

롤 여러 개를 컬렉션 하나로 묶어 판을 붙이고, 빌드한 묶음을 설치해 FQCN 으로 부르고, 고정 파일로 설치판을 잠그는 한 바퀴를 직접 돌 수 있게 됩니다.

왜 중요한가

롤은 재사용 단위이고 컬렉션은 배포 단위입니다. 팀이 늘어나면 문제는 '이 롤을 어떻게 쓰나' 에서 '지금 저 서버에서 도는 롤이 어느 판인가' 로 옮겨 갑니다. 컬렉션은 그 질문에 답하려고 세 가지를 도입했습니다. 이름에 출처를 적고(FQCN), 묶음에 판을 붙이고(SemVer), 설치할 판을 파일에 적습니다(requirements.yml). 이 세 가지가 없으면 검색 경로의 순서가 무엇이 실행될지를 정하는데, 그 순서는 사람이 아니라 환경이 정합니다. 여기에 롤 인자 명세를 더하면 잘못된 값이 태스크를 돌기 전에 막힙니다 — 남이 쓸 코드를 내보낼 때 문서보다 먼저 갖춰야 할 것입니다. 이 실습은 그 한 바퀴를 인터넷 없이 로컬 묶음만으로 돕니다.

단계

1. ansible-galaxy collection init 으로 acme.platform 컬렉션의 뼈대를 /root/ans/coll/src 아래에 만드세요. 그리고 /root/ans/inventory/hosts.ini 에 web1·web2·db1 을 적은 인벤토리를 만드세요(ansible_host=127.0.0.1, ansible_port=2222, ansible_user=root).
2. /root/ans/coll/src/acme/platform/galaxy.yml 의 version 을 1.2.0 으로, description·authors·repository 를 사내 값으로 채우고 license 에 MIT, tags 에 infrastructure 와 linux 를 넣으세요. 그리고 같은 컬렉션의 meta/runtime.yml 에 requires_ansible 를 범위 표기로 적으세요.
3. 컬렉션 안 roles/motd/ 에 롤을 만드세요. defaults/main.yml 에 motd_banner(기본 acme-platform)·motd_owner(기본 platform)·motd_path(기본 /root/ans/coll/out/motd.txt)를 두고, tasks/main.yml 은 motd_path 에 banner=<motd_banner> 와 owner=<motd_owner> 두 줄을 쓰는 이름 붙은 태스크 하나로 채우세요. 모듈은 FQCN 으로 부릅니다.
4. roles/motd/meta/argument_specs.yml 을 만들어 main 진입점에 short_description 과 세 인자를 적으세요. 셋 다 type: str 이고 description 이 있어야 하며, motd_owner 에는 choices 로 platform 과 sre 두 값만 허용하세요.
5. 컬렉션을 빌드해 /root/ans/coll/dist/acme-platform-1.2.0.tar.gz 를 만들고, 묶음 안에 MANIFEST.json·FILES.json 과 롤 파일들이 들어 있는지 확인하세요.
6. 만든 묶음을 /root/ans/coll/collections 에 설치하고, 그 경로에서 acme.platform 이 1.2.0 으로 보이는지, ansible-doc 으로 acme.platform.motd 롤의 인자가 조회되는지 확인하세요.
7. /root/ans/coll/use.yml 을 만들어 acme.platform.motd 롤을 FQCN 으로 부르되 motd_banner 를 acme-platform in production 으로, motd_owner 를 sre 로 넘기세요. 인벤토리의 web1 을 대상으로 실행해 /root/ans/coll/out/motd.txt 를 남기세요.
8. 소스의 galaxy.yml 판을 1.3.0 으로 올려 다시 빌드하고(묶음이 둘이 됩니다), /root/ans/coll/requirements.yml 에 1.2.0 묶음을 type: file 로 고정해 그 파일로 설치하세요. 그리고 설치된 판을 /root/ans/coll/out/pinned.txt 에 한 줄로 남기세요.

참고

• 이 파드에는 인터넷이 없습니다. Galaxy 에서 내려받는 것과 galaxy.yml 의 dependencies 자동 해결은 이 환경에서 재현할 수 없어 실습에서 뺐습니다. init·build·로컬 묶음 install 은 모두 정상 동작합니다.
• 배포판 컬렉션이 이미 수백 개 깔려 있습니다. 목록을 볼 때는 ansible-galaxy collection list acme.platform -p <경로> 처럼 이름과 경로를 함께 주세요.
• -p 로 설치하면 'pip 가 관리하는 자리일 수 있다' 는 경고가 나옵니다. 설치는 정상입니다.
• 흔한 실수: 설치는 해 놓고 실행할 때 검색 경로를 주지 않는 것. 설치한 자리와 실행할 때 보는 자리가 같아야 합니다.
• 흔한 실수: galaxy.yml 의 version 을 두 자리로 적는 것. 빌드가 그 자리에서 거절합니다.
• Collections Guide · Collection structure · Distributing collections · Installing collections

컬렉션 뼈대 만들기

ansible-galaxy collection init 으로 acme.platform 컬렉션의 뼈대를 /root/ans/coll/src 아래에 만드세요. 그리고 /root/ans/inventory/hosts.ini 에 web1·web2·db1 을 적은 인벤토리를 만드세요(ansible_host=127.0.0.1, ansible_port=2222, ansible_user=root).

컬렉션 이름은 <네임스페이스>.<이름> 한 덩어리로 줍니다. 만들 자리는 --init-path 로 지정하고, 뼈대는 그 아래에 네임스페이스/이름 두 단계로 생깁니다.

galaxy.yml 채우고 최소 ansible 판 못 박기

/root/ans/coll/src/acme/platform/galaxy.yml 의 version 을 1.2.0 으로, description·authors·repository 를 사내 값으로 채우고 license 에 MIT, tags 에 infrastructure 와 linux 를 넣으세요. 그리고 같은 컬렉션의 meta/runtime.yml 에 requires_ansible 를 범위 표기로 적으세요.

뼈대가 넣어 둔 예시 문구(your name, your collection description)가 남아 있으면 빌드는 되지만 배포물로는 쓸 수 없습니다. runtime.yml 은 거의 전부가 주석이니 필요한 키만 새로 적는 편이 빠릅니다.

컬렉션 안에 롤 넣기

컬렉션 안 roles/motd/ 에 롤을 만드세요. defaults/main.yml 에 motd_banner(기본 acme-platform)·motd_owner(기본 platform)·motd_path(기본 /root/ans/coll/out/motd.txt)를 두고, tasks/main.yml 은 motd_path 에 banner=<motd_banner> 와 owner=<motd_owner> 두 줄을 쓰는 이름 붙은 태스크 하나로 채우세요. 모듈은 FQCN 으로 부릅니다.

컬렉션 안의 롤도 디렉터리 규약은 기존 롤과 똑같습니다. 값을 하드코딩하면 롤이 재사용되지 않으니 세 값 모두 변수로 받으세요. 두 줄을 한 번에 쓰려면 여러 줄 문자열(|)을 content 로 넘기면 됩니다.

인자 명세로 잘못된 값 막기

roles/motd/meta/argument_specs.yml 을 만들어 main 진입점에 short_description 과 세 인자를 적으세요. 셋 다 type: str 이고 description 이 있어야 하며, motd_owner 에는 choices 로 platform 과 sre 두 값만 허용하세요.

명세는 문서가 아니라 검증입니다. 목록에 없는 값을 넣어 롤을 불러 보고, 첫 태스크가 돌기 전에 멈추는지 직접 확인하세요.

묶음으로 빌드하고 내용물 확인하기

컬렉션을 빌드해 /root/ans/coll/dist/acme-platform-1.2.0.tar.gz 를 만들고, 묶음 안에 MANIFEST.json·FILES.json 과 롤 파일들이 들어 있는지 확인하세요.

빌드는 컬렉션 소스 디렉터리 안에서 돌립니다. 결과를 둘 자리는 --output-path 로 지정합니다. 묶음 안을 보려면 풀지 말고 목록만 봐도 됩니다.

로컬 경로에 설치하고 문서로 확인하기

만든 묶음을 /root/ans/coll/collections 에 설치하고, 그 경로에서 acme.platform 이 1.2.0 으로 보이는지, ansible-doc 으로 acme.platform.motd 롤의 인자가 조회되는지 확인하세요.

설치 경로는 -p 로 줍니다. 조회할 때는 ansible 이 그 경로를 보게 해야 하는데, 검색 경로를 정하는 환경 변수가 따로 있습니다. 배포판 컬렉션이 수백 개 깔려 있으니 목록은 이름을 지정해 보세요.

FQCN 으로 불러 실행하기

/root/ans/coll/use.yml 을 만들어 acme.platform.motd 롤을 FQCN 으로 부르되 motd_banner 를 acme-platform in production 으로, motd_owner 를 sre 로 넘기세요. 인벤토리의 web1 을 대상으로 실행해 /root/ans/coll/out/motd.txt 를 남기세요.

롤을 부를 때 넘긴 값은 롤의 defaults 를 이깁니다. 컬렉션을 못 찾는다고 하면 검색 경로부터 확인하세요 — 설치한 자리와 실행할 때 보는 자리가 같아야 합니다.

소스는 앞서 나가도 설치판은 고정하기

소스의 galaxy.yml 판을 1.3.0 으로 올려 다시 빌드하고(묶음이 둘이 됩니다), /root/ans/coll/requirements.yml 에 1.2.0 묶음을 type: file 로 고정해 그 파일로 설치하세요. 그리고 설치된 판을 /root/ans/coll/out/pinned.txt 에 한 줄로 남기세요.

로컬 묶음 파일을 가리킬 때는 이름에 경로를 적고 종류를 따로 밝힙니다. 설치된 판은 손으로 적지 말고 collection list 의 출력에서 뽑아 적으세요.