AnsibleのJinja2テンプレートとhandler設計｜設定ファイルの動的生成とサービス自動再起動の仕組み

この記事のポイント

・templateモジュールはJinja2で変数・条件分岐を埋め込める設定ファイル配布モジュール
・handlerはnotify時のみPlay終了後に1回だけ実行される通知型タスク
・flush_handlersでhandlerを即時実行でき、後続taskが再起動後サービスに依存する場合に使う
・listenで複数taskから1つのhandlerを疎結合に呼び出せる
・handler連鎖（Ansible 2.9以降）でhandlerが別のhandlerをnotifyできる

# httpd.conf.j2（変数展開の例）
ServerName {{ ansible_hostname }}
ServerAdmin {{ server_admin }}
Listen {{ http_port }}

# SSL設定を本番環境のみ有効化する例
{% if enable_ssl | default(false) %}
SSLEngine on
SSLCertificateFile {{ ssl_cert_path }}
SSLCertificateKeyFile {{ ssl_key_path }}
{% endif %}

site.yml
inventory/
  prod/           ← 本番環境インベントリ
  dev/            ← 開発環境インベントリ
group_vars/
  webservers.yml  ← 共通変数
  prod.yml        ← 本番環境変数（enable_ssl: true等）
roles/
  apache/
    tasks/
      main.yml
    templates/
      httpd.conf.j2  ← Jinja2テンプレート
    handlers/
      main.yml

# httpd.conf.j2 — Jinja2変数・条件分岐は実行時に展開される
ServerName {{ ansible_hostname }}
ServerAdmin {{ server_admin | default('webmaster@localhost') }}
Listen {{ http_port | default(80) }}

DocumentRoot {{ document_root | default('/var/www/html') }}


    Options Indexes FollowSymLinks
    AllowOverride {{ allow_override | default('None') }}
    Require all granted


{% if enable_ssl | default(false) %}
Listen 443

    ServerName {{ ansible_fqdn }}
    SSLEngine on
    SSLCertificateFile {{ ssl_cert_path }}
    SSLCertificateKeyFile {{ ssl_key_path }}

{% endif %}

---
- name: httpd.confをテンプレートから配布する
  ansible.builtin.template:
    src: httpd.conf.j2
    dest: /etc/httpd/conf/httpd.conf
    owner: root
    group: root
    mode: '0644'
    validate: '/usr/sbin/httpd -t -f %s'
  notify: Reload Apache

# ansible-playbook site.yml -i inventory/prod 実行時の出力
TASK [apache : httpd.confをテンプレートから配布する] **
changed: [web01.example.com]

RUNNING HANDLERS ************************************
TASK [apache : Reload Apache] ***********************
changed: [web01.example.com]

PLAY RECAP ******************************************
web01.example.com : ok=4  changed=2  unreachable=0  failed=0

---
- name: Reload Apache
  ansible.builtin.service:
    name: httpd
    state: reloaded

- name: Restart Apache
  ansible.builtin.service:
    name: httpd
    state: restarted

---
# httpd.confとssl.confを両方配布するタスク
- name: httpd.confを配布する
  ansible.builtin.template:
    src: httpd.conf.j2
    dest: /etc/httpd/conf/httpd.conf
    validate: '/usr/sbin/httpd -t -f %s'
  notify: Reload Apache

- name: ssl.confを配布する
  ansible.builtin.template:
    src: ssl.conf.j2
    dest: /etc/httpd/conf.d/ssl.conf
  notify: Reload Apache

- hosts: webservers
  tasks:
    - name: httpd.confを配布する
      ansible.builtin.template:
        src: httpd.conf.j2
        dest: /etc/httpd/conf/httpd.conf
        validate: '/usr/sbin/httpd -t -f %s'
      notify: Reload Apache

    - name: ssl.confを配布する
      ansible.builtin.template:
        src: ssl.conf.j2
        dest: /etc/httpd/conf.d/ssl.conf
      notify: Reload Apache

    # ここでhandlerを即時実行する
    - name: Flush handlers before health check
      ansible.builtin.meta: flush_handlers

    # この時点ではApacheが再起動済み
    - name: Check Apache health endpoint
      ansible.builtin.uri:
        url: http://localhost/health
        status_code: 200
        timeout: 10

  handlers:
    - name: Reload Apache
      ansible.builtin.service:
        name: httpd
        state: reloaded

tasks:
  - name: httpd.confを配布する
    ansible.builtin.template:
      src: httpd.conf.j2
      dest: /etc/httpd/conf/httpd.conf
    notify: apache config changed   # トピック名を通知

  - name: ssl.confを配布する
    ansible.builtin.template:
      src: ssl.conf.j2
      dest: /etc/httpd/conf.d/ssl.conf
    notify: apache config changed   # 同じトピック名

handlers:
  - name: Validate Apache config
    ansible.builtin.command: /usr/sbin/httpd -t
    listen: apache config changed   # トピックを購読

  - name: Reload Apache
    ansible.builtin.service:
      name: httpd
      state: reloaded
    listen: apache config changed   # 同じトピックを購読

handlers:
  - name: Restart Apache
    ansible.builtin.service:
      name: httpd
      state: restarted
    notify: Verify Apache Health   # handler連鎖：下流handlerを呼び出す

  - name: Verify Apache Health
    ansible.builtin.uri:
      url: http://127.0.0.1/health
      status_code: 200
    retries: 3
    delay: 5

# NG: notify名とhandler名が不一致（大文字・小文字が異なる）
notify: reload apache
handlers:
  - name: Reload Apache

# OK: 完全一致
notify: Reload Apache
handlers:
  - name: Reload Apache

# 常にchangedとして扱い、notifyを発動させる例
- name: 設定反映スクリプトを実行する
  ansible.builtin.command: /opt/app/bin/reload-config
  changed_when: true
  notify: Restart Apache

fatal: [web01.example.com]: FAILED! => {
    "msg": "AnsibleUndefinedVariable: 'ssl_cert_path' is undefined"
}

# テンプレート内でデフォルト値を指定する
SSLCertificateFile {{ ssl_cert_path | default('/etc/pki/tls/certs/localhost.crt') }}

# 変数が定義されている場合のみSSL設定を出力する
{% if ssl_cert_path is defined %}
SSLCertificateFile {{ ssl_cert_path }}
{% endif %}

- hosts: appservers
  force_handlers: true   # タスク失敗時もhandlerを実行する
  tasks:
    - name: 設定ファイルを配布する
      ansible.builtin.template:
        src: app.conf.j2
        dest: /etc/app/app.conf
      notify: Notify deploy result

    - name: データベースマイグレーションを実行する
      ansible.builtin.command: /opt/app/bin/migrate.sh
      # このタスクが失敗してもhandlerが実行される

  handlers:
    - name: Notify deploy result
      ansible.builtin.uri:
        url: https://hooks.example.internal/notify
        method: POST
        body_format: json
        body:
          text: "Deploy finished on {{ inventory_hostname }}"

# NG: handlerでregisterしても後続taskから参照できない
handlers:
  - name: Check service status
    ansible.builtin.command: systemctl is-active httpd
    register: service_result   # この変数は後続taskから見えない

# OK: task側でregisterを使い、handlerは再起動のみに限定する
tasks:
  - name: httpd.confを配布する
    ansible.builtin.template:
      src: httpd.conf.j2
      dest: /etc/httpd/conf/httpd.conf
    notify: Reload Apache
    register: template_result

  - name: 設定変更の結果を確認する
    ansible.builtin.debug:
      var: template_result.changed

# 全ホストへの適用完了後に1回だけ実行したい場合の例
handlers:
  - name: Notify all done
    ansible.builtin.uri:
      url: https://hooks.example.internal/notify
      method: POST
      body_format: json
      body:
        text: "Deploy complete"
    run_once: true    # 1ホストでchangedが出た時点で1回だけ実行
    delegate_to: localhost