AnsibleでPythonカスタムモジュールを開発する方法｜べき等性を持つ独自操作をroleに組み込む設計入門

この記事のポイント

・AnsibleModuleクラスを使えばJSON入出力を抽象化してべき等性のある独自操作を設計できる
・changed=Trueを返す条件を明示することでdry-run（--check）が正しく動くモジュールになる
・library/ディレクトリへの配置だけでroleから透過的に呼び出せる
・shellモジュールのchanged_when地獄を卒業する設計方針が得られる

- name: confファイルに設定行を追記（shell版）
  shell: |
    for f in /opt/myapp/conf.d/*.conf; do
      grep -q "timeout=30" "$f" || echo "timeout=30" >> "$f"
    done
  changed_when: ???
  register: result

- name: confファイルに設定行を追記（カスタムモジュール版）
  my_conf_line:
    path: /opt/myapp/conf.d/
    line: "timeout=30"
    state: present

#!/usr/bin/python3
import json, sys

result = {"changed": False, "msg": "nothing to do"}
print(json.dumps(result))
sys.exit(0)

# Playbook と同じディレクトリに置く場合
.
├── site.yml
└── library/
    └── my_conf_line.py

# role に同梱する場合
roles/
└── myapp/
    ├── library/
    │   └── my_conf_line.py
    └── tasks/
        └── main.yml

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

from ansible.module_utils.basic import AnsibleModule
import os

def main():
    # ① 引数の定義
    module_args = dict(
        path=dict(type='str', required=True),
        line=dict(type='str', required=True),
        state=dict(type='str', default='present',
                   choices=['present', 'absent']),
    )

    # ② AnsibleModuleの初期化
    module = AnsibleModule(
        argument_spec=module_args,
        supports_check_mode=True,   # --checkフラグを有効にする
    )

    path  = module.params['path']
    line  = module.params['line']
    state = module.params['state']

    # ③ ファイルが存在しなければエラー
    if not os.path.exists(path):
        module.fail_json(msg=f"ファイルが見つかりません: {path}")

    # ④ 現在の状態を取得
    with open(path, 'r') as f:
        lines = f.readlines()

    line_exists = any(line.rstrip('\n') == l.rstrip('\n') for l in lines)

    # ⑤ 変更が不要なら即 exit
    if state == 'present' and line_exists:
        module.exit_json(changed=False, msg="行はすでに存在します")
    if state == 'absent' and not line_exists:
        module.exit_json(changed=False, msg="行は存在しません（対応不要）")

    # ⑥ check_mode では実際の変更をスキップ
    if module.check_mode:
        module.exit_json(changed=True, msg="[check] 変更が予定されています")

    # ⑦ 実際の変更処理
    if state == 'present':
        with open(path, 'a') as f:
            f.write(line + '\n')
        module.exit_json(changed=True, msg=f"行を追記しました: {line}")
    else:
        new_lines = [l for l in lines if l.rstrip('\n') != line]
        with open(path, 'w') as f:
            f.writelines(new_lines)
        module.exit_json(changed=True, msg=f"行を削除しました: {line}")

if __name__ == '__main__':
    main()

# site.yml
---
- hosts: webservers
  tasks:
    - name: タイムアウト設定を追記
      my_conf_line:
        path: /etc/myapp/app.conf
        line: "timeout=30"
        state: present

$ ansible-playbook -i hosts site.yml

PLAY [webservers] **********************

TASK [タイムアウト設定を追記] *****
changed: [web01.example.internal]

PLAY RECAP ***************************
web01.example.internal : ok=1  changed=1  unreachable=0  failed=0

$ ansible-playbook -i hosts site.yml

TASK [タイムアウト設定を追記] *****
ok: [web01.example.internal]

PLAY RECAP ***************************
web01.example.internal : ok=1  changed=0  unreachable=0  failed=0

roles/
└── myapp_config/
    ├── library/
    │   └── my_conf_line.py      # カスタムモジュール
    ├── tasks/
    │   └── main.yml
    ├── defaults/
    │   └── main.yml
    └── meta/
        └── main.yml

# roles/myapp_config/tasks/main.yml
---
- name: タイムアウト設定を反映
  my_conf_line:
    path: "{{ myapp_conf_path }}"
    line: "timeout={{ myapp_timeout }}"
    state: present
  notify: restart myapp

- name: 古い設定行を削除
  my_conf_line:
    path: "{{ myapp_conf_path }}"
    line: "old_setting=deprecated"
    state: absent

# roles/myapp_config/defaults/main.yml
---
myapp_conf_path: /etc/myapp/app.conf
myapp_timeout: 30

# ansible.cfg
[defaults]
library = ./library:~/.ansible/plugins/modules

$ ansible-playbook -i hosts site.yml -vvv

...
TASK [タイムアウト設定を追記] *****
task path: /home/ansible/site.yml:4
...
{"path": "/etc/myapp/app.conf", "line": "timeout=30", "state": "present"}
...
{"changed": true, "msg": "行を追記しました: timeout=30", ...}

# args.json（テスト用引数ファイル）
{"ANSIBLE_MODULE_ARGS": {
    "path": "/tmp/test.conf",
    "line": "timeout=30",
    "state": "present"
}}

# 実行
$ python3 library/my_conf_line.py args.json
{"changed": true, "msg": "行を追記しました: timeout=30", "invocation": {"module_args": {...}}}

# molecule/default/verify.yml（べき等性検証の例）
---
- name: Verify idempotency
  hosts: all
  tasks:
    - name: 2回目の実行（changed=0 になるはず）
      my_conf_line:
        path: /etc/myapp/app.conf
        line: "timeout=30"
        state: present
      register: result

    - name: changedがFalseであることを確認
      assert:
        that:
          - result.changed == false
        fail_msg: "べき等性が壊れています"

# NG: 末尾\nが食い違って毎回 changed=True になる
line_exists = line in lines

# OK: 正規化してから比較する
line_exists = any(line.rstrip('\n') == l.rstrip('\n') for l in lines)