includerole 実務リファレンス¶

この記事について¶

Ansibleのroles:、import_role、include_roleの使い分けに迷うエンジニア向けの実務リファレンスです。

この記事で得られること：

フローチャートで3つの手段を即座に判断できる
逆引き表で「やりたいこと」から適切な手段を選べる
トラブル時に事故逆引き表で原因と対応を特定できる

このドキュメントの使い方¶

今すぐ決めたい → 意思決定フローチャートと逆引き表だけ見る
なぜそうなるか知りたい → 本文（各セクション）を参照
トラブル発生 → 事故逆引き表から引く

意思決定フローチャート¶

Playの骨格としてロールを並べるだけ？
│
├─ Yes ───────────────────────────→ roles:
│
└─ No → 途中にタスクを挟む必要がある？
         │
         ├─ No ───────────────────→ roles:
         │
         └─ Yes → 条件分岐/ループ/可変ロール名が必要？
                   │
                   ├─ No ─────────→ import_role
                   │                 （静的・タグがロール内に効く）
                   │
                   └─ Yes ────────→ include_role
                                     （動的・条件/ループに強い）
                                     │
                                     └─ タグ等をロール内に効かせたい？
                                         ├─ Yes → apply: 併用
                                         └─ No  → そのまま

逆引き表（やりたいこと → 手段）¶

やりたいこと	使う手段	注意点
Playの骨格として並べる	`roles:`	最優先。依存解決も自動
途中にタスクを挟む	`import_role`	位置を明示できる
タグをロール内全タスクに効かせる	`import_role`	include_roleは`apply:`必要
条件分岐でロール選択	`include_role`	`when:`と組み合わせ
ループでロール呼び出し	`include_role`	`loop:`と組み合わせ
可変ロール名（変数で指定）	`include_role`	`name: "{{ var }}"`
ロール内の特定ファイルだけ実行	`tasks_from:`	入口は少数に限定
ロール変数を後続タスクへ公開	`include_role` + `public: true`	明示必須
同一ロールを複数回実行	`allow_duplicates: true`（ロール側）	meta/main.ymlに記載

事故逆引き表（症状 → 対処）¶

症状	原因	対処
タグ指定したのにロール内が動かない	include_roleのタグはロール内に継承されない	`apply:`を使う or `import_role`に変更
同じロールの2回目がスキップ	重複排除（デフォルト）	ロール側に`allow_duplicates: true`
変数が前段タスクにも影響	import_roleは解析時に露出	`public`明示＋共有変数は専用ロール化
ハンドラ内でroleが動かない	handlers内でのrole呼び出しは不可	handlerは単機能に限定、role呼び出しはtasksへ
handler名衝突で別のが動く	handlersはPlay全体スコープ	`role_name : handler_name`形式でnotify

3つの手段の性格¶

静的 vs 動的¶

種別	展開タイミング	特徴
静的 (`roles:`, `import_role`)	解析時（parse）	実行計画が早期に確定。タグ等がロール内に効きやすい
動的 (`include_role`)	実行時（runtime）	条件分岐/ループに強い。タグ等は`apply:`で明示

各手段の概要¶

手段	用途	性格
`roles:`	Playの骨格	静的。依存解決も自動。tasksより前に走る
`import_role`	途中に挟む＋タグを効かせたい	静的。tasks列に配置可能
`include_role`	条件分岐/ループ/可変ロール名	動的。柔軟だがタグは`apply:`必要

実行順¶

roles: で指定したロール  ←── 先に実行
        ↓
tasks: のタスク列（import_role/include_roleはここに挿入される）

roles:はtasksより前段で走る
import_role/include_roleはtasks列の書いた位置で実行

タグの効き方（最重要の差分）¶

手段	タグの効き先	対処
`roles:` / `import_role`	ロール内全タスクに適用	そのまま使える
`include_role`	include_role文自体にのみ	`apply:`でロール内に通す

include_role + apply 例：

- name: deploy with tags
  ansible.builtin.include_role:
    name: app
    apply:
      tags: [deploy]
      become: true
  tags: [deploy]  # ← この行はinclude_role文へのタグ

特定ファイルだけ呼ぶ（tasks_from等）¶

- ansible.builtin.include_role:
    name: myrole
    tasks_from: setup.yml      # roles/myrole/tasks/setup.yml
    handlers_from: custom.yml  # roles/myrole/handlers/custom.yml

実務ルール： 入口は少数（install/configure/verify程度）に限定。増えたらロール分割を検討。

変数スコープと public¶

手段	public指定時の露出範囲
`include_role`	そのタスク以降で参照可能
`import_role`	解析時に公開（前段にも影響しうる）

- ansible.builtin.include_role:
    name: shared_vars
    public: true  # ← 明示が必須

チーム標準： publicは常に明示（true/false）。共有変数は専用ロールに閉じる。

重複排除と allow_duplicates¶

原則： 同一Play内で同じロールは1回だけ実行（依存ロールも同様）

複数回実行したい場合：

# roles/myrole/meta/main.yml
allow_duplicates: true

パターン集¶

A. Play骨格（デフォルト）¶

- hosts: all
  roles:
    - common
    - hardening
    - app

B. 途中に検査を挟む¶

- hosts: web
  tasks:
    - name: precheck
      command: /usr/local/bin/precheck

    - ansible.builtin.import_role:
        name: app
      tags: [deploy]

C. 条件分岐¶

- hosts: all
  tasks:
    - ansible.builtin.include_role:
        name: app_debian
      when: ansible_facts['os_family'] == 'Debian'

    - ansible.builtin.include_role:
        name: app_rhel
      when: ansible_facts['os_family'] == 'RedHat'

D. ループ¶

- hosts: all
  tasks:
    - ansible.builtin.include_role:
        name: "{{ item }}"
      loop:
        - common
        - app

E. include_role + apply¶

- hosts: web
  tasks:
    - ansible.builtin.include_role:
        name: app
        apply:
          tags: [deploy]
          become: true
      tags: [deploy]

チーム標準化（最小ルール）¶

デフォルトは roles:
例外条件を明文化
途中に挟む → import_role
条件/ループ/可変 → include_role（ロール内に効かせるならapply:）
publicは常に明示（true/false）
tasks_fromの入口は少数（増えたらロール分割）
複数回実行が必要なロールはallow_duplicatesをロール側に
handlerでのrole呼び出しは禁止（設計規約）

参照¶

更新: 2025-12-29