Ansibleのrole設計入門｜ディレクトリ構造とtasks・handlers・defaultsで再利用可能なコードを作る方法

この記事のポイント

・ansible roleはPlaybookを機能単位に分割・再利用する仕組み
・ansible-galaxy initコマンドでディレクトリ雛形を一瞬で生成できる
・handlers/notifyでサービス再起動を冪等に管理できる（changedの時だけ発火）
・handlerはフェーズ（pre_tasks/roles/tasks/post_tasks）の末尾でまとめて発火する
・listenキーワードで複数roleから1つのhandlerをまとめて呼べる
・defaultsは外部から上書き可能、varsは上書きを抑制する役割
・meta/main.ymlのdependenciesでrole間の依存関係をコードで宣言できる

roles/
└── webserver/          # role名
    ├── tasks/
    │   └── main.yml    # メインのタスクリスト（必須）
    ├── handlers/
    │   └── main.yml    # notifyで呼び出されるハンドラ
    ├── defaults/
    │   └── main.yml    # 上書き可能なデフォルト変数（最低優先度）
    ├── vars/
    │   └── main.yml    # 上書きを想定しない変数（高優先度）
    ├── files/           # copyモジュールで配布するファイル
    ├── templates/       # templateモジュールで使うJinja2テンプレート
    └── meta/
        └── main.yml    # roleのメタ情報・依存関係の定義

# webserverという名前のroleを作成する
ansible-galaxy init webserver

[ansible@ctrl01 roles]$ ansible-galaxy init webserver
- Role webserver was created successfully

[ansible@ctrl01 roles]$ find webserver -type f
webserver/README.md
webserver/defaults/main.yml
webserver/handlers/main.yml
webserver/meta/main.yml
webserver/tasks/main.yml
webserver/tests/inventory
webserver/tests/test.yml
webserver/vars/main.yml
webserver/.travis.yml

# roles/webserver/meta/main.yml
galaxy_info:
  author: your_name
  description: Webサーバーをセットアップするrole
  license: MIT
  min_ansible_version: "2.14"
  platforms:
    - name: EL
      versions:
        - "9"

dependencies:
  - role: os_base   # webserver実行前にos_baseを自動実行する

# site.yml（dependenciesを使うとこれだけでOK）
- hosts: webservers
  roles:
    - webserver   # os_baseはAnsibleが自動で先行実行する

# roles/webserver/tasks/main.yml
---
- name: httpd をインストールする
  ansible.builtin.dnf:
    name: httpd
    state: present

- name: httpd.conf を配置する
  ansible.builtin.template:
    src: httpd.conf.j2
    dest: /etc/httpd/conf/httpd.conf
    owner: root
    group: root
    mode: '0644'
  notify: restart httpd   # 変更があった場合はhandlerを呼ぶ

- name: httpd を起動・自動起動有効化
  ansible.builtin.service:
    name: httpd
    state: started
    enabled: true

# roles/webserver/handlers/main.yml
---
- name: restart httpd
  ansible.builtin.service:
    name: httpd
    state: restarted

# 複数タスクが同じhandlerをnotifyしても1回だけ実行される例
- name: httpd.conf を配置する
  ansible.builtin.template:
    src: httpd.conf.j2
    dest: /etc/httpd/conf/httpd.conf
  notify: restart httpd

- name: conf.d/vhost.conf を配置する
  ansible.builtin.template:
    src: vhost.conf.j2
    dest: /etc/httpd/conf.d/vhost.conf
  notify: restart httpd   # 同じhandlerをnotify

# → handlerの「restart httpd」は1回だけ実行される

# roles/webserver/defaults/main.yml
# 外部から上書き可能なデフォルト値（推奨）
---
http_port: 80
server_name: "{{ ansible_hostname }}"
document_root: /var/www/html

# roles/webserver/vars/main.yml
# 上書きを抑制したいrole内部変数
---
httpd_config_path: /etc/httpd/conf/httpd.conf
httpd_package: httpd

# roles/webserver/meta/main.yml
dependencies:
  - role: os_base
    vars:
      timezone: "Asia/Tokyo"
      ntp_server: "ntp.nict.jp"

# roles/webserver/handlers/main.yml
- name: restart httpd
  ansible.builtin.service:
    name: httpd
    state: restarted
  listen: "httpd restart"    # listenキーワードで受け取り名を定義

# roles/ssl_cert/tasks/main.yml
- name: SSL証明書を更新する
  ansible.builtin.copy:
    src: "{{ cert_file }}"
    dest: /etc/httpd/ssl/server.crt
  notify: "httpd restart"    # listenの名前でnotify（別roleから呼べる）

# roles/vhost/tasks/main.yml
- name: バーチャルホスト設定を配置する
  ansible.builtin.template:
    src: vhost.conf.j2
    dest: /etc/httpd/conf.d/vhost.conf
  notify: "httpd restart"    # 別roleからも同じlistenでnotify

# roles/webserver/tasks/main.yml
- name: httpd.conf を配置する
  ansible.builtin.template:
    src: httpd.conf.j2
    dest: /etc/httpd/conf/httpd.conf
  notify: restart httpd

- name: handlerをここで即時実行させる
  ansible.builtin.meta: flush_handlers    # このタイミングでhandlerを実行

- name: httpdの起動確認
  ansible.builtin.uri:
    url: http://localhost/healthz
    status_code: 200
    # この時点でhttpdは再起動済みのためヘルスチェックが成功する

# site.yml
---
- name: Webサーバーをセットアップする
  hosts: webservers
  become: true

  roles:
    - webserver          # roles/webserver/ を呼び出す

# 条件付きでroleを適用する例
- name: 本番環境でのみセキュリティroleを適用する
  ansible.builtin.include_role:
    name: security_hardening
  when: env == 'production'

[ansible@ctrl01 ~]$ ansible-playbook -i inventory/hosts site.yml

PLAY [Webサーバーをセットアップする] ************************************

TASK [Gathering Facts] ****************************************************
ok: [web01.example.internal]

TASK [webserver : httpd をインストールする] ********************************
changed: [web01.example.internal]

TASK [webserver : httpd.conf を配置する] ***********************************
changed: [web01.example.internal]

TASK [webserver : httpd を起動・自動起動有効化] ****************************
changed: [web01.example.internal]

RUNNING HANDLERS [webserver : restart httpd] ********************************
changed: [web01.example.internal]

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

# site.yml — 実行順序を意識したPlaybook設計
---
- name: Rocky Linux 9.4 に Apache を構築する
  hosts: webservers
  become: true

  pre_tasks:
    - name: OSバージョンを確認する（前提条件チェック）
      ansible.builtin.assert:
        that:
          - ansible_distribution in ["RedHat", "Rocky", "AlmaLinux"]
          - ansible_distribution_major_version | int >= 9
        fail_msg: "Rocky/RHEL 9以上が必要です（現在: {{ ansible_distribution_version }}）"

    - name: DBサーバーが応答しているか確認する
      ansible.builtin.wait_for:
        host: db01.example.internal
        port: 3306
        timeout: 10
      delegate_to: localhost

  roles:
    - role: security      # SELinux・firewalld設定
    - role: webserver     # Apache インストール・設定

  tasks:
    - name: バーチャルホスト設定を配置する
      ansible.builtin.template:
        src: vhost.conf.j2
        dest: /etc/httpd/conf.d/myapp.conf
        mode: '0644'
      notify: restart httpd

  post_tasks:
    - name: ポート80がLISTENになるまで待機する
      ansible.builtin.wait_for:
        host: "{{ ansible_default_ipv4.address }}"
        port: 80
        state: started
        timeout: 30

    - name: HTTP 200が返るか確認する
      ansible.builtin.uri:
        url: "http://{{ ansible_default_ipv4.address }}/"
        status_code: 200

  handlers:
    - name: restart httpd
      ansible.builtin.service:
        name: httpd
        state: restarted

# ansible.cfg に検索パスを追加する
[defaults]
roles_path = ./roles:/etc/ansible/roles

ERROR! A circular dependency was detected in the role tree:
webserver -> os_base -> webserver