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 など）や挙動が異なる場合があります。実装の際は、利用しているバージョンの公式ドキュメントを併せてご確認ください。