Ansibleのinventory・role・module設計｜現場で崩れない構成管理の基礎

この記事のポイント

・ansible inventory は環境別（dev/prod）に分離し host_vars で個体差を吸収する
・role は機能単位（nginx/mariadb）で分割し依存性を ansible-galaxy で管理する
・module は「冪等性が保証されるか」を基準に選択。command/shell は最終手段
・inventory・role・module の設計が揃って初めて構成管理が安定する

# ディレクトリ構造（推奨）
inventories/
├── dev/
│   ├── hosts          # 開発環境のホスト定義
│   └── group_vars/
│       └── all.yml    # 開発環境共通変数
└── prod/
    ├── hosts          # 本番環境のホスト定義
    └── group_vars/
        └── all.yml    # 本番環境共通変数

# inventories/dev/hosts の例
[web]
web01.dev.example.com
web02.dev.example.com

[db]
db01.dev.example.com

[all:vars]
ansible_user=ec2-user
ansible_ssh_private_key_file=~/.ssh/dev_key.pem

# 開発環境に対してPlaybookを実行
ansible-playbook -i inventories/dev site.yml

# 本番環境に対してPlaybookを実行（ドライラン推奨）
ansible-playbook -i inventories/prod site.yml --check

# host_vars/web01.dev.example.com.yml の例
# サーバー固有の変数をここで定義する
nginx_port: 80
data_volume: /dev/xvdb
max_conn: 512

# host_vars/web02.dev.example.com.yml の例
nginx_port: 80
data_volume: /dev/xvdc   # 別デバイスでも吸収できる
max_conn: 256

# inventories/dev/aws_ec2.yml（動的inventory設定例）
plugin: amazon.aws.aws_ec2
regions:
  - ap-northeast-1
filters:
  "tag:Env": dev
  "tag:Role": web
keyed_groups:
  - key: tags.Role
    prefix: role

# 実行時のコマンド
ansible-playbook -i inventories/dev/aws_ec2.yml site.yml

# ansible-inventory -i inventories/dev/aws_ec2.yml --list の出力例（抜粋）
{
  "_meta": {
    "hostvars": {
      "10.0.1.23": {
        "ansible_host": "10.0.1.23",
        "tags": {"Env": "dev", "Role": "web"}
      }
    }
  },
  "role_web": {
    "hosts": ["10.0.1.23", "10.0.1.24"]
  }
}

# role雛形の生成
ansible-galaxy role init nginx

# 生成されるディレクトリ構造
nginx/
├── defaults/
│   └── main.yml    # デフォルト変数（最低優先度）
├── handlers/
│   └── main.yml    # handler（サービス再起動など）
├── tasks/
│   └── main.yml    # タスク本体
├── templates/
│   └── nginx.conf.j2  # Jinja2テンプレート
├── vars/
│   └── main.yml    # role内固定変数（高優先度）
├── files/           # 静的ファイル
├── meta/
│   └── main.yml    # roleの依存関係定義
└── tests/
    └── test.yml

# site.yml（roleを束ねるエントリポイント）
---
- name: Configure web servers
  hosts: web
  roles:
    - common
    - nginx
    - php-fpm

- name: Configure DB servers
  hosts: db
  roles:
    - common
    - mariadb

# nginx/defaults/main.yml
---
nginx_port: 80
nginx_worker_processes: auto
nginx_access_log: /var/log/nginx/access.log
nginx_error_log: /var/log/nginx/error.log
nginx_max_body_size: 10m

# nginx/templates/nginx.conf.j2（Jinja2テンプレートで変数を展開）
worker_processes {{ nginx_worker_processes }};

http {
    access_log {{ nginx_access_log }};
    error_log  {{ nginx_error_log }};

    server {
        listen {{ nginx_port }};
        client_max_body_size {{ nginx_max_body_size }};
    }
}

# nginx/tasks/main.yml
---
- name: Install nginx
  ansible.builtin.dnf:
    name: nginx
    state: present

- name: Deploy nginx.conf
  ansible.builtin.template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
    mode: '0644'
  notify: Reload nginx    # 変更があった場合のみhandlerを呼ぶ

- name: Ensure nginx is started and enabled
  ansible.builtin.service:
    name: nginx
    state: started
    enabled: true

# nginx/handlers/main.yml
---
- name: Reload nginx
  ansible.builtin.service:
    name: nginx
    state: reloaded

# php-fpm/meta/main.yml
---
galaxy_info:
  role_name: php-fpm
  author: yourname
  min_ansible_version: "2.15"

dependencies:
  - role: nginx

# commandで冪等性を確保する例
# creates: に指定したファイルが存在する場合はスキップされる
- name: Initialize MariaDB data directory
  ansible.builtin.command:
    cmd: mysql_install_db --user=mysql --basedir=/usr
    creates: /var/lib/mysql/mysql    # このディレクトリがあればスキップ

# エラーが出たときのデバッグ手順
# --check でドライランして変更予定タスクを確認する
ansible-playbook -i inventories/dev site.yml --check --diff

# 特定のtagを付けたタスクだけ実行して切り分ける
ansible-playbook -i inventories/dev site.yml --tags "nginx"

# 実行結果の詳細を表示する（-vvv で最大詳細）
ansible-playbook -i inventories/dev site.yml -v

# ansible.cfg の設定例
[defaults]
inventory      = inventories/dev
roles_path     = roles:~/.ansible/roles
remote_user    = ec2-user
host_key_checking = False    # 検証機では無効化することが多い

[privilege_escalation]
become = True
become_method = sudo