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

この記事のポイント

・inventory は INI形式（手軽）とYAML形式（階層記述）から用途に合わせて選択する
・ansible inventory は dev/stg/prod のディレクトリに分割し group_vars で環境差分を自動適用する
・ansible-inventory --list / --graph で変数とグループ構造を実行前に必ず検証する
・role は機能単位（nginx/mariadb）で分割し依存性を meta/main.yml で管理する
・module は「冪等性が保証されるか」を基準に選択。command/shell は最終手段
・本番適用前は --check --diff でドライランし差分を確認してから実行する

# hostsファイル（INI形式の例）
[webservers]
web01.example.com
web02.example.com

[dbservers]
db01.example.com
db02.example.com

[all:vars]
ansible_user=rocky
ansible_ssh_private_key_file=/home/ansible/.ssh/id_ed25519

# INI形式でchildrenを使う例（webserversとdbserversをapp_serversにまとめる）
[app_servers:children]
webservers
dbservers

# inventory.yml（YAML形式の例）
all:
  children:
    webservers:
      hosts:
        web01.example.com:
        web02.example.com:
    dbservers:
      hosts:
        db01.example.com:
    app_servers:            # 親グループ（webservers + dbservers をまとめる）
      children:
        webservers:
        dbservers:

# ディレクトリ構造（推奨）
inventories/
├── dev/
│   ├── hosts          # 開発環境のホスト定義
│   └── group_vars/
│       └── all.yml    # 開発環境共通変数
├── stg/
│   ├── 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

# 親グループ dev_all が子グループ web / db を持つ宣言（変数の継承に使う）
[dev_all:children]
web
db

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

# inventories/prod/hosts の例（本番ホストのみ）
[web]
prod-web01 ansible_host=10.0.1.11
prod-web02 ansible_host=10.0.1.12

[db]
prod-db01 ansible_host=10.0.2.11

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

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

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

# 本番環境への適用前にドライランで差分確認（推奨）
ansible-playbook -i inventories/prod site.yml --check --diff

# 本番環境に対してPlaybookを実行
ansible-playbook -i inventories/prod site.yml

# 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/prod/host_vars/prod-web02.yml
# prod-web02のみメンテナンスモードを有効にする場合
nginx_maintenance_mode: true
maintenance_message: "定期メンテナンス中です（10:00～12:00）"

# inventories/dev/group_vars/all.yml
env: dev
app_port: 8080
nginx_worker_processes: 1
log_level: debug
allow_debug_endpoints: true
db_host: 192.168.10.21
db_name: myapp_dev
ansible_user: ansible
ntp_server: ntp.nict.jp

# inventories/prod/group_vars/all.yml
env: prod
app_port: 80
nginx_worker_processes: auto
log_level: warn
allow_debug_endpoints: false
db_host: 10.0.2.11
db_name: myapp_prod
ansible_user: ansible
ntp_server: ntp.nict.jp

# inventories/dev/group_vars/webservers.yml（webグループ専用）
http_port: 80
https_port: 443
webserver_package: nginx
max_connections: 512

# tasks/main.yml の例 — env変数で環境ごとに条件分岐する
- name: デバッグエンドポイントを有効化する（dev環境のみ）
  ansible.builtin.template:
    src: debug_routes.conf.j2
    dest: /etc/nginx/conf.d/debug.conf
  when: env == "dev"

- name: worker_processesを設定する
  ansible.builtin.lineinfile:
    path: /etc/nginx/nginx.conf
    regexp: '^'worker_processes'
    line: "worker_processes {{ nginx_worker_processes }};"

# 本番inventoryの全変数をJSON形式で確認する
ansible-inventory -i inventories/prod --list

# 特定ホストの変数だけを絞り込んで確認する
ansible-inventory -i inventories/prod --host prod-web01

# グループ階層をツリー形式で視覚的に確認する
ansible-inventory -i inventories/prod --graph

# ansible-inventory --graph の出力例
$ ansible-inventory -i inventories/prod --graph
@all:
  |--@web:
  |  |--prod-web01
  |  |--prod-web02
  |--@db:
  |  |--prod-db01
  |--@ungrouped:

{
  "_meta": {
    "hostvars": {
      "prod-web01": {
        "ansible_host": "10.0.1.11",
        "ansible_user": "ansible",
        "app_port": 80,
        "db_host": "10.0.2.11",
        "env": "prod",
        "log_level": "warn",
        "nginx_worker_processes": "auto",
        "ntp_server": "ntp.nict.jp"
      }
    }
  },
  "web": {
    "hosts": ["prod-web01", "prod-web02"]
  }
}

# 全ホストのenv変数を一覧表示して環境を目視確認する
ansible-inventory -i inventories/prod --list | python3 -c "
import json, sys
inv = json.load(sys.stdin)
for host, vars in inv['_meta']['hostvars'].items():
    print(host, '->', vars.get('env', '未設定'))
"

# 出力例（全ホストが prod を指していることを確認する）
# prod-web01 -> prod
# prod-web02 -> prod
# prod-db01  -> prod

# prod専用のVaultファイルを新規作成する
ansible-vault create inventories/prod/group_vars/vault.yml

# ファイル内に記述する変数（暗号化前の平文イメージ）:
# db_password: "ProdP@ssw0rd"
# app_secret_key: "prod-secret-key-xxxxx"

# Vaultパスワードファイルを使ってPlaybookを実行する
ansible-playbook -i inventories/prod --vault-password-file ~/.vault_pass.txt site.yml

# 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"]
  }
}

# dev環境へのPlaybook実行
ansible-playbook -i inventories/dev site.yml

# stg環境へのPlaybook実行
ansible-playbook -i inventories/stg site.yml

# prod環境への適用前にcheckモードで差分確認（必須）
ansible-playbook -i inventories/prod --check --diff site.yml

# prod環境への本番適用
ansible-playbook -i inventories/prod site.yml

$ ansible-playbook -i inventories/prod --check --diff site.yml

PLAY [web] ******************************************

TASK [nginx : Deploy nginx.conf from template] ******
--- before: /etc/nginx/nginx.conf
+++ after: /home/ansible/.ansible/tmp/ansible-tmp-xxx/source
@@ -3,7 +3,7 @@
-worker_processes 1;
+worker_processes auto;

PLAY RECAP ******************************************
prod-web01 : ok=4  changed=1  unreachable=0  failed=0
prod-web02 : ok=4  changed=1  unreachable=0  failed=0

# Makefile（タブでインデントすること）
.PHONY: dev stg check-prod prod

dev:
    ansible-playbook -i inventories/dev site.yml

stg:
    ansible-playbook -i inventories/stg site.yml

check-prod:
    ansible-playbook -i inventories/prod --check --diff site.yml

prod: check-prod
    @echo "prod本番適用を実行します。本当によいですか？ [y/N]"
    @read ans && [ "651618{ans}" = "y" ] && ansible-playbook -i inventories/prod site.yml || echo "中止しました。"

# 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    # このディレクトリがあればスキップ

# グループ階層を確認して「No hosts matched」の原因を特定する
$ ansible-inventory -i inventories/dev --graph
@all:
  |--@web:
  |  |--web01.dev.example.com
  |--@ungrouped:
  |  |--db01.dev.example.com    # ← ungroupedに入っているホストを発見

# NG: プロジェクトルートにまとめて置くパターン
project/
├── group_vars/
│   └── all.yml     # どの環境で実行しても同じ値が使われる
└── inventories/
    ├── dev/hosts
    └── prod/hosts

# OK: inventoryディレクトリ配下に置く
project/
└── inventories/
    ├── dev/
    │   └── group_vars/
    │       └── all.yml   # dev実行時のみ参照される
    └── prod/
        └── group_vars/
            └── all.yml   # prod実行時のみ参照される

# YAML構文チェック（python3が使える環境で実行する）
$ python3 -c "import yaml; yaml.safe_load(open('inventories/prod/group_vars/all.yml'))"

# エラーがなければ何も出力されない。エラーがある場合は行番号付きで表示される
# 例: yaml.scanner.ScannerError: mapping values are not allowed here
#   in "inventories/prod/group_vars/all.yml", line 5, column 12

# エラーが出たときのデバッグ手順
# --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