6장. ansible에서 모듈 사용하기

모듈의 기본 개념

ansible에서 모듈이란, 1장에서 소개한 것처럼 간단하게 ansible에서 사용하는 "명령어" 라고 이해할 수 있다. 이러한 모듈은 하나의 작은 프로그램이므로, 모두 사용법을 배워야 한다. 이러한 사용법은 아주 자세히 확인할 수 있고, 친절하게 사용하는 예시 등도 잘 나와 있다.

 

더자세한 설명은 http://docs.ansible.com/ansible/2.7/modules/modules_by_category.html 에서 확인한다.

Module Index — Ansible Documentation

 

모듈 관련 가이드와 문서 사용 명령

* ansible-doc -l

- ansible host에서 사용할 수 있는 모든 모듈을 나열한다.

- 아래와 같이 엄청난 양의 모듈들의 리스트와 간단한 설명이 나온다.

 

* ansible-doc 모듈명

- 해당 모듈의 상세 메뉴얼을 확인한다.

- 만약 어떤 키워드가 모듈인지 아닌지 판단하려면 ansible-doc 키워드를 썼을 때 뭔가 나오지 않는다면 해당 키워드는 모듈이 아니다.

- 아래와 같이 해당 모듈의 상세 설명들을 확인한다. 더 자세한 사항은 아래에서 설명한다.

- ansible-doc yum, ansible-doc ping, ansible-doc parted 등등 한번 입력해보자.

 

* ansible-doc -s 모듈명

- 해당 모듈을 사용할 플레이북 구문의 템플릿 역할도 할 수 있고, 한눈에 알아보기 쉽게 상세 설명을 해주는 방식으로 보여준다.

- 아래 캡쳐에서 - name: , ping: data 이런 부분이 템플릿 처럼 사용할 수 있는 부분이다.

 

ansible-doc 명령 상세하게 띁어보기

ansible-doc 명령은 일반적으로 모듈이름, 옵션, 노트, 요구사항, 저자, 예시 로 이루어진다. 물론 일부가 빠질 수도 있다. 이러한 doc는 전적으로 개발자가 개인의 재량으로 만드는 것이다. ansible-doc yum 명령 예시를 확인해보자.

 

모듈 이름

- 관련 기본 설명과 개요

 

OPTIONS

- 해당 모듈에서 쓰는 옵션들

 

NOTES

- 기타 알아야 할 것들.

약간 구구절절하지만 개발자 입장에서 팁 등을 명시한다. 위 내용의 번역은 아래와 같다.

 

* 'loop'와 함께 사용하는 경우 : 각 패키지는 개별적으로 처리되므로 목록을`name` 옵션에 직접 전달하는 것이 훨씬 더 효율적입니다.

* 1.9.2 이전 버전에서이 모듈은 yum 모듈에 제공된 각 패키지를 별도로 설치하고 제거했습니다. 이로 인해 파일 이름 또는 URL로 지정된 패키지를 함께 설치하거나 제거해야 할 때 문제가 발생했습니다. 1.9.2에서는 패키지가 하나의 yum 트랜잭션에 설치되도록 수정되었습니다. 그러나 패키지 중 하나가 다른 패키지 (예 : epel-release)에서 가져온 새 yum 저장소를 추가하는 경우 해당 패키지를 별도의 작업에 설치해야합니다. 이것은 yum의 명령 줄 동작을 모방합니다.

* Yum 자체에는 두 가지 유형의 그룹이 있습니다. "패키지 그룹"은 rpm 자체에 지정되고 "환경 그룹"은 별도의 파일 (일반적으로 배포판)에 지정됩니다. 안타깝게도 ansible은 단일 트랜잭션으로 패키지 그룹에서 작동해야하고 yum에서는 그런 방식으로 사용할 때 다른 방식으로 그룹을 지정해야하므로 ansible 사용자에게는이 구분이 분명해집니다. 패키지 그룹은 "@ development-tools"로 지정되고 환경 그룹은 "@ ^ gnome-desktop-environment"로 지정됩니다. "yum group list hidden ids"명령을 사용하여 설치하려는 그룹이 속하는 그룹 범주를 확인하십시오.

* yum 모듈은 멱등성 방식으로 yum 캐시 지우기를 지원하지 않으므로 구현하지 않기로 결정했습니다. 유일한 방법은 명령을 사용하고 yum 명령을 직접 호출하는 것입니다. "command : yum clean all"  https://github.com/ansible/ansible/pull/31450#issuecomment-352889579

 

 

REQUIREMENTS

- 해당 모듈을 사용하기 위해 필요사항

 

AUTHOR

- 해당 모듈 제작자, 그리고 METADATA에 status가 있는데 해당 모듈의 개발 상태를 말함.

 

EXAMPLES

- 플레이북 사용 시 예시들. ansible-doc -s 옵션과 함께 같이 보면서 플레이북을 만들 수 있다.

 

모듈 유지 관리

업스트림에서는 매우 활동적으로 모듈을 개발하고 있다. ansible-doc 령의 AUTHOR 섹션에는 업스트림 ansible 커뮤니티에서 누가 해당 모듈을 유지관리하는지, 현재 개발 상태는 어떤지 등의 상세 정보를 확인할 수 있다.

 

* status 항목 - 모듈의 개발 상태를 기록

stableinterface	모듈의 키워드가 안정적이고, 키워드를 제거하거나 의미를 변경하지 않도록 모든 노력을 기울인다. (모듈의 인터페이스가 안정적임으 나타내는 것이지, 모듈의 코드 품질을 평가한 것은 아님)
preview	모듈이 기술 프리뷰에 있고, 불안정할 수 있고, 키워드가 변경되는 등의 문제가 발생할 수 있다. 즉 베타버전이라고 볼 수 있다.
deprecated	현재 이 모듈은 사용되지 않으며, 일부는 향후 릴리스에서 더 이상 사용할 수 없다.
removed	모듈이 릴리즈에서 제거되었으나, 이전 사용자가 같은 기능의 다른 새 모듈을 사용할 때 도움이 되도록 설명서 용도로 존재한다.

 

* supported_by 항목 - 업스트림 ansible 커뮤니티에서 모듈을 유지관리하는 단체(또는 사람)을 기록

core	"핵심" ansible 개발자 업스트림에서 유지 관리하며 항상 앤서블에 포함된다. 즉 ansible official 모듈이다.
curated	커뮤니티의 파트너 또는 회사에서 만들고 유지관리하는 모듈. 이 모듈의 유지관리자는 보고된 모든 문제를 관찰하거나 모듈에 대해 제기된 요청을 가져와야 한다. 커뮤니티 유지 관리자가 변경 사항을 승인한 후에는 업스트림 core 개발자가 큐레이션된 모듈에 제안된 변경 사항을 검토한다. 또한 핵심 commiter가 ansible 엔진의 변경으로 인해 이러한 모듈의 모든 문제가 해결되었는지를 확인한다. 이러한 모듈은 현재 앤서블에 포함되어 있지만 향후 특정 시점에 별도의 패키지로 제공될 수 있다.
community	core 업스트림 개발자, 파트너 또는 회사에서 지원하는것은 아니다. 그냥 일반 오픈소스 커뮤니티에서 전적으로 유지관리하는 모듈이다. 사용 자체는 잘 쓸 수 있으나, 문제 발생시 feedback은 전적으로 해당 커뮤니티에 달려있다. 이러한 모듈은 현재 ansible에 포함되어 있지만 향후 특정 시점에 별도의 패키지로 제공될 가능성이 있다.

 

멱등성 (冪等性, idempotent)

module은 기본적으로 멱등성을 가진다. 또한 가져야만 한다. 멱등성이란 수학에서 연산의 한 성질을 의미하는 것으로, 연산을 여러번 적용해도 결과가 달라지지 않는 성질을 의미한다. 즉 ansible에서 수행하는 task, ad-hoc, playbook 등에 있는 모듈은 멱등성을 가지므로, 이러한 작업들은 안전하게 실행된다.

 

다시말해 ansible의 모든 작업은, 예를들어 A -> B 의 작업을 했으면 현재 B일텐데, 이 상태에서 또 작업을 해도 이미 상태가 B이므로 작업을 하지 않는다. 이는 ad-hoc, playbook 등을 안전하게 여러 번 실행할 수 있고, 시스템이 이미 올바른 상태에 있으면 아무 작업도 하지 않는다는 것이다.

 

Ansible은 "상태"를 만드는 것이므로, 패키지를 설치하는 것을 install이라고 표현하지 않고 present 라는 식으로 표현한다. 반대는 물론 delete가 아니라 absent 이런식으로 된다.

 

 

대부분의 모듈들은 멱등성을 가지지만, 예외적으로 멱등성을 가지지 않는 모듈이 있다. 이는 아래에 몇가지를 소개할 것이다.

 

멱등성 확인 예시

 

최초 실행하는 ad-hoc 명령은, 아래와 같이 chagned가 true인 것을 볼 수 있다. 이것은 변경이 되었다는 의미이다.

동일한 명령을 다시 실행하면, 아래와 같이 changed가 false가 나오는 것을 볼 수 있다. 동일한 명령을 수행했지만 변경은 되지 않았다는 의미이다.

 

멱등성이 제대로 작동하지 않는 모듈 3가지

대부분의 모듈은 멱등성을 가진다. 시스템의 상태를 확인하고 시스템이 올바르면 아무것도 하지 않는다. 하지만 아래에서 소개하는 command, shell, raw 3가지의 "run command" 모듈들은 멱등성이 제대로 작동하지 않는다. 아예 안 되는 것이 아니고, 좀 애매하다. 아무튼 이 명령어들은 매우 간편해서 자주 쓸 수 있는데, 이에 의존하면 애드혹 명령이나 플레이북 재실행으로 예기치 않은 오류가 발생할 수 있다.  또한, 멱등성이 없는 이 3가지 명령은 실행할 때 마다 무조건 changed를 반환한다.

 

그렇다고 해서 이러한 명령어들을 완전히 피해야 한다는 것은 아니다. 이러한 "run command" 모듈들은 중요한 도구이자 문제에 대한 좋은 해결책이 될 수도 있다. 따라서 상황과 환경에 맞게 조심해서 사용해야 한다. 참고로 가능하면 playbook에서는 사용하지 않는 것을 권고한다.

 

* command 모듈

- ansible 클라이언트들의 명령줄에서 임의의 명령을 실행한다. 

- 이 모듈은 ansible 클라이언트에 python이 설치되어 있어야 사용이 가능하다.

- 예시 : ansible all -m command -a '/usr/bin/hostname'

 

 

* shell 모듈

- command 모듈은 클라이언트의 쉘에서 실행되는게 아니다. 따라서 파이프도 못쓰고, 리디렉션도 할 수 없다. 즉 쉘작업은 할 수 없다.

     - ansible all -m command -a 'ps -e | grep rsyslog' : 작동하지 않음

     - ansible all -m shell -a 'ps -e | grep rsyslog' : 잘 작동함

- shell 모듈은 쉘을 통해 명령어가 처리된다. 쉘 환경변수에도 액세스할수 있고, 리디렉션, 파이프 등도 다 쓸 수 있다.

- 이 모듈은 ansible 클라이언트에 python이 설치되어 있어야 사용이 가능하다.

- 예시 : ansible all -m shell -a 'set | grep PWD' ( set 명령은 환경변수를 보는 명령어이다)

 

# shell 모듈의 사용을 다른 모듈로 대체하기

- 예를 들어, 다음 명령은 멱등성이 없어서 다시 반복하면 /etc/resolv.conf에 nameserver 192.0.2.1 이라는 내용이 계속 아래에 추가되게 된다.

ansible web.example.com -m shell -a 'echo "nameserver 192.0.2.1" >> /etc/resolv.conf'

- 이것 대신 아래처럼 copy 명령을 쓰면, 멱등성이 있고 여러번 반복해도 상관없다.

ansible web.example.com -m copy -a 'dest=/etc/resolv.conf content="nameserver 192.0.2.1\n"'

 

* raw 모듈

- 모듈 하위 시스템을 거치지 않고 원격 쉘을 사용하여 직접 명령을 실행할 수 있다.

- 이는 파이썬을 설치할 수 없는 시스템 (예 : 네트워크 라우터 등)을 관리할 때 유용하다. 즉 윈도우, 네트워크 장치 등의 리눅스가 아닌 시스템에서 자주 사용할 수 있다.

- 또한 호스트에 파이썬을 설치하는 데에도 사용할 수 있다.

- 보통으로 리눅스의 기본적인 조건을 만족하지 못할 때나, 아니면 ssh가 없는 등의 환경에서 사용된다.

- 이 강의에서는 사용하지 않으므로 더 이상 자세한 설명은 생략한다.

 

 

# 참고

당연한 이야기지만, 멱등성이 없는 모듈은 반복하면 문제가 발생할 수 있다. 예를들어, 유저 생성하는 명령을 command 모듈로 하고, 다시한번 하면 "이미 있는 유저이다" 이런식으로 에러가 발생할 것이다. 이것은 리턴코드가 0이 아니므로 playbook상에서는 error로 인식된다.

 

# 참고 : 변경되지 않았는데 왜 CHANGED?

shell 또는 command 모듈이 실행될 때 일반적으로 쉘이 시스템 상태에 영향을 미쳤다고 판단하는지 여부에 따라 CHANGED라고상태를 보고한다. 실제로 변경되지 않았지만 CHANGED 라고 결과가 나오는 것이다. 오해할 수 있으므로 참고할 것.

 

 

 

 

참고사항

ansible(1)

 

도움이 되는 링크

 

모듈 색인: ansible 문서

http://docs.ansible.com/ansible/2.7/modules/modules_by_category.html

Module Index — Ansible Documentation

명령 - 원격 노드에서 명령 실행 모듈: ansible 문서

http://docs.ansible.com/ansible/2.7/modules/command_module.html

command – Executes a command on a remote node — Ansible Documentation

 쉘 - 노드에서 명령 실행 모듈: ansible 문서

http://docs.ansible.com/ansible/2.7/modules/shell_module.html

shell – Execute commands in nodes. — Ansible Documentation

모듈 개발 ansible 설명서

https://docs.ansible.com/ansible/2.7/user_guide/developing_modules.html

모듈 지원 ansible 설명서

https://docs.ansible.com/ansible/2.7/user_guide/modules_support.html 

Module Maintenance & Support — Ansible Documentation

 

업스트림 ansible 커뮤니티에는 앤서블 및 해당 통합 모듈에 대한 이슈 트래커가 있다. 아래 링크를 참고한다.

https://github.com/ansible/ansible/issue

ansible/ansible