Ansible 모듈 형식 및 문서 작성 방법

이 게시글에서는 Ansible 모듈 형식 및 문서에 대한 내용을 안내드리는 글입니다. Ansible 모듈을 Python으로 작성하여 프로젝트에 기여하고자 한다면, 여기 소개된 형식을 엄격히 따라야 합니다. 또한, 제출 체크리스트, Python 2와 3 호환성 유지 전략, 테스트 정보 등을 참고해야 합니다. 이 글에서는 Ansible 모듈 형식의 주요 항목과 각 항목을 작성하는 방법에 대해 상세히 설명합니다.

1. 모듈 파일의 기본 구성 요소

모든 Ansible 모듈은 정해진 형식을 따라야 합니다. Python으로 작성된 모듈 파일은 반드시 아래의 순서로 구성된 항목을 포함해야 하며, 이들은 코드 작성 전에 위치해야 합니다. 이는 모듈이 다른 도구와 호환되도록 하며 Ansible이 모듈을 제대로 인식하고 작동할 수 있도록 합니다.

1.1 Shebang 및 UTF-8 코딩 설정

모든 Ansible 모듈은 파일의 시작 부분에 shebang 구문과 UTF-8 코딩 설정이 필요합니다. 이는 다음과 같이 작성됩니다:

#!/usr/bin/python# -*- coding: utf-8 -*-

이 설정을 통해 ansible_python_interpreter의 실행이 가능하며, UTF-8 인코딩을 명시하여 모든 텍스트가 유니코드로 처리되도록 합니다.

1.2 저작권 및 라이선스 선언

파일의 첫 부분에 저작권 및 라이선스를 명시해야 하며, 이를 위해 하나의 간단한 줄을 사용합니다. 예를 들어:

# Copyright: (c) 2023, Hong Gil-dong

# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)@example.com>

이처럼 모든 저작권 정보는 간략히 작성되어야 하며, GPL v3.0+ 라이선스를 준수해야 합니다. 추가 기여자가 발생할 경우 최신 기여자가 위에 오도록 추가할 수 있습니다.

2. ANSIBLE_METADATA 블록

이 항목은 모듈의 메타데이터 정보를 포함합니다. Ansible의 다른 도구에서 모듈을 인식하고 활용할 수 있도록 도와줍니다. 새로운 모듈의 경우 다음과 같이 설정할 수 있습니다:

ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'community'}

metadata_version은 메타데이터의 형식 버전이며, status는 모듈의 상태를 나타내며 기본적으로 'preview'로 설정됩니다. 지원 주체는 'community'로 지정합니다.

3. DOCUMENTATION 블록

DOCUMENTATION 블록은 모듈의 상세한 설명을 YAML 형식으로 포함하며, Ansible의 공식 문서에서 참고됩니다. 주의할 점은 모든 문서 필드는 소문자이며 YAML 형식을 유지해야 한다는 점입니다.

DOCUMENTATION 블록을 작성한 후 로컬에서 모듈의 문서화를 테스트할 수 있습니다. 예를 들어 터미널에서 다음 명령을 실행할 수 있습니다:

ansible-doc -t module my_module_name

해당 명령을 실행하면 모듈의 문서가 명령줄에서 확인됩니다. 구문 오류가 발생할 경우 상세한 오류 메시지를 확인하려면 -vvv 옵션을 추가하면 됩니다.

4. EXAMPLES 블록

EXAMPLES 블록은 사용자에게 모듈의 사용 예시를 제공하여 모듈을 이해하는 데 도움을 줍니다. 예시는 복사해서 플레이북에 바로 사용할 수 있어야 하며, 실제 상황에서의 사용법을 보여줍니다.

EXAMPLES = r'''- name: Ensure foo is installedmodulename:name: foostate: present'''

예시를 작성할 때는 boolean 옵션을 사용할 경우 yes/no 값을 사용하여 문서와 일관성을 유지하는 것이 좋습니다.

5. RETURN 블록

RETURN 블록은 모듈의 결과값에 대해 설명하며, 다른 모듈에서 사용할 수 있는 반환 정보를 포함합니다. 모든 반환 필드는 필요하며, 반환 필드마다 description, returned, type, sample과 같은 상세 항목을 포함해야 합니다.

RETURN = r'''dest:description: Destination file/path.returned: successtype: strsample: /path/to/file.txt'''

이처럼 반환 값의 각 필드는 필요 시 자세한 설명을 추가하여 사용자가 반환 데이터를 쉽게 이해할 수 있도록 해야 합니다.

6. Python Imports

마지막으로, Python imports는 모듈 파일의 가장 아래에 위치해야 합니다. 이를 통해 필요한 라이브러리를 불러와 모듈이 기능하도록 합니다. wild card(*)를 사용하는 import는 허용되지 않으며, 아래와 같이 기본 import를 사용해야 합니다:

from module_utils.basic import AnsibleModule

이 import 구문은 모듈이 Ansible에서 실행될 수 있도록 필수적으로 포함되어야 합니다.

이와 같은 형식으로 Ansible 모듈을 작성하면, 문서화와 코드 유지보수가 훨씬 쉬워집니다. Ansible 모듈을 기여하거나 작성하는 경우, 이 블로그 글의 내용과 각 목차의 항목을 숙지하고, 실제 코드 작성 시 주의하여 작성하시기 바랍니다.