Ansibleを実務で導入した当初はシンプルだったPlaybookも、管理対象サーバーの増加や環境（開発・ステージング・本番）の多様化に伴い、コードの肥大化や変数の競合といった運用上の課題に直面しがちです。
本記事では、Ansible Playbookの保守性を向上させるための「Role分割の設計基準」と「変数の優先順位を意識した管理手法」について、具体的なディレクトリ構成やコード例を交えて解説します。
読者が抱える課題
- 単一のPlaybook（
site.ymlなど）にタスクが集中し、どこに何が書かれているか把握しづらい - 開発環境と本番環境で設定値を切り替える際、変数の定義場所が散らばっていて修正漏れが発生する
- Roleを作成したものの、再利用性が低く、結局プロジェクトごとにコピー＆ペーストしている
この記事で分かること
- 実務に耐えうる標準的なディレクトリ構成（ベストプラクティス準拠）
- Roleを「再利用可能」にするための設計基準と良い例・悪い例
- 変数の競合を防ぎ、意図通りに制御するための変数管理ルール
- 導入時に役立つ「Role設計チェックリスト」
1. 推奨されるディレクトリ構成
Ansible公式のベストプラクティスをベースに、環境ごとの変数管理（group_vars / host_vars）とRole分割を明確にした構成例です。
.
├── production.ini # 本番環境用インベントリ
├── staging.ini # ステージング環境用インベントリ
├── site.yml # 全体実行用マスターPlaybook
├── group_vars/
│ ├── all.yml # 全ホスト共通の変数
│ ├── production.yml # 本番環境共通の変数
│ └── staging.yml # ステージング環境共通の変数
└── roles/
├── common/ # 共通セットアップRole（全サーバー対象）
│ ├── defaults/
│ │ └── main.yml # デフォルト変数（優先度：低）
│ └── tasks/
│ └── main.yml # 実行タスク
└── nginx/ # 特定機能Role（Nginxインストール・設定）
├── defaults/
│ └── main.yml
├── templates/
│ └── nginx.conf.j2
└── tasks/
└── main.yml
2. Role分割の設計基準（良い例・悪い例）
Roleを分割する際の重要な基準は、**「そのRoleが単一の責務（機能）に特化しているか」および「環境依存の値がハードコードされていないか」**です。
悪い例：環境依存の値がタスク内にハードコードされている
以下の例では、ポート番号やドキュメントルートがタスク内に直接書かれているため、開発環境と本番環境で使い回すことができません。
# roles/nginx/tasks/main.yml (悪い例)
- name: Install Nginx
ansible.builtin.package:
name: nginx
state: present
- name: Copy Nginx configuration
ansible.builtin.template:
src: nginx.conf.j2
dest: /etc/nginx/nginx.conf
# ポート番号やパスがタスクやテンプレート内で固定されていると再利用できない
良い例：変数を外部から注入できるように設計する
タスク内では変数名のみを指定し、デフォルト値を defaults/main.yml に定義します。環境ごとの差異はインベントリや group_vars から上書きします。
# roles/nginx/defaults/main.yml (デフォルト値の定義)
nginx_port: 80
nginx_document_root: /var/www/html
nginx_package_state: present
# roles/nginx/tasks/main.yml (良い例)
- name: Install Nginx
ansible.builtin.package:
name: nginx
state: "{{ nginx_package_state }}"
- name: Copy Nginx configuration
ansible.builtin.template:
src: nginx.conf.j2
dest: /etc/nginx/nginx.conf
3. 変数管理のルールと優先順位の活用
Ansibleには多くの変数定義場所があり、優先順位（Precedence）が定められています。実務で混乱を防ぐためには、使用する場所を以下の3つに制限することを推奨します。
| 優先度 | 変数の定義場所 | 主な用途 | 特徴 |
|---|---|---|---|
| 低 | roles/<role_name>/defaults/main.yml |
Roleのデフォルト値 | 他の場所から容易に上書き可能。Role単体で動作させるための最低限の設定を記述。 |
| 中 | group_vars/<group_name>.yml |
環境ごとの差異（本番/ステージング等） |
production.yml や staging.yml で、ポート番号やドメイン名などの環境固有値を定義。 |
| 高 | Playbook実行時の -e オプション（Extra Vars） |
一時的な設定変更やデバッグ | 実行時に動的に変更したい値（パッケージのバージョン指定など）に限定して使用。 |
変数命名の衝突を防ぐ「プレフィックスルール」
複数のRoleを組み合わせた際、変数名の競合（例：複数のRoleで port という変数名を使ってしまうなど）を防ぐため、変数名には必ずRole名をプレフィックスとして付与します。
- 避けるべき変数名:
port,user,version - 推奨される変数名:
nginx_port,mysql_user,common_timezone
4. 実務導入時のRole設計チェックリスト
新規にRoleを作成・分割する際、または既存のPlaybookをリファクタリングする際は、以下のチェックリストを活用してください。
- 単一責務の原則: そのRoleは1つのミドルウェアや設定（例: nginx, mysql, users）に特化しているか？
-
プレフィックスの付与:
defaults/main.yml内のすべての変数にRole名にちなんだプレフィックスが付いているか？ -
ハードコードの排除: IPアドレス、ドメイン名、ポート番号、パスなどの環境依存値が
tasks/内に直接書かれていないか？ -
デフォルト値の存在: Role単体で実行した際に、エラーにならず最低限動作するデフォルト値が
defaults/main.ymlに定義されているか？ -
機密情報の分離: パスワードやAPIキーなどの機密情報がプレーンテキストでコミットされていないか？（
ansible-vaultの利用を検討しているか？）
5. 注意点とよくある失敗
1. vars/main.yml の過剰な使用
Role内には defaults/main.yml のほかに vars/main.yml も存在します。しかし、vars/main.yml で定義された変数は優先順位が非常に高く、group_vars などから上書きすることが困難になります。特別な理由がない限り、Role内の変数は defaults/main.yml に配置してください。
2. 過度なRole分割による複雑化
「1タスク＝1Role」のように細分化しすぎると、Playbook全体の流れを追うのが難しくなり、ディレクトリ構造が複雑化します。「再利用する単位」または「単一のミドルウェア単位」を意識して分割の粒度を決定してください。
まとめ
Ansible Playbookの保守性を高める鍵は、**「Roleの疎結合化」と「変数の整理」**にあります。
- 共通処理と個別処理をRoleとして切り出す
- 変数にはRole名のプレフィックスを付与し、
defaults/main.ymlにデフォルト値を集約する - 環境ごとの差異は
group_varsで吸収する
この原則を守ることで、環境の変化に強く、複数人のメンバーでもメンテナンスしやすいインフラ構成管理を実現できます。
注意
Ansibleのバージョンによって、推奨されるモジュール名（ansible.builtin.packageなど）や挙動が異なる場合があります。実装の際は、利用しているバージョンの公式ドキュメントを併せてご確認ください。