Ansibleの変数優先順位と設定スコープを整理する｜vars・defaults・group_vars・host_varsの使い分け

この記事のポイント

・Ansible変数は22段階の優先順位を持ち、extra_vars（-e）が最高優先度
・group_vars/host_varsでステージング・本番の環境差分を安全に管理できる
・roleのdefaults（上書き可）とvars（固定）を使い分けるのが設計の基本
・debugモジュールと-vオプションで変数の実値をその場で確認できる

# 現在の変数値をdebugモジュールで確認する例
$ ansible web01.example.com -m debug -a "var=http_port" -i inventory/hosts

ok: [web01.example.com] => {
    "http_port": "80"
}

# extra_varsで環境を指定する例
$ ansible-playbook site.yml -e "env=production" -e "app_version=2.5.1"

# 変数ファイルごと渡す場合
$ ansible-playbook site.yml -e "@secrets/production.yml"

# 推奨ディレクトリ構造
inventories/
├── production/
│   ├── hosts                # 本番ホスト定義
│   ├── group_vars/
│   │   ├── all.yml          # 全グループ共通変数
│   │   └── webservers.yml   # webserversグループ固有変数
│   └── host_vars/
│       └── web01.yml        # web01固有の変数
└── staging/
    ├── hosts                # ステージングホスト定義
    ├── group_vars/
    │   ├── all.yml
    │   └── webservers.yml
    └── host_vars/

# inventories/production/group_vars/webservers.yml
http_port: 80
db_host: db.prod.example.com
db_name: myapp_production
max_connections: 200

# inventories/staging/group_vars/webservers.yml
http_port: 8080
db_host: db.stg.example.com
db_name: myapp_staging
max_connections: 50

# tasks/configure.yml（Playbook側は変数名のみ記述、環境を意識しない）
- name: Apacheのポート設定
  ansible.builtin.lineinfile:
    path: /etc/httpd/conf/httpd.conf
    regexp: '^Listen'
    line: "Listen {{ http_port }}"
  notify: Restart Apache

# ステージング環境へのデプロイ
$ ansible-playbook site.yml -i inventories/staging/

# 本番環境へのデプロイ
$ ansible-playbook site.yml -i inventories/production/

# inventories/production/host_vars/web03.yml
http_port: 8443
ssl_enabled: true

# 実行結果確認：web03だけ8443になっていることを確認
$ ansible all -m debug -a "var=http_port" -i inventories/production/

ok: [web01.example.com] => {
    "http_port": "80"
}
ok: [web02.example.com] => {
    "http_port": "80"
}
ok: [web03.example.com] => {
    "http_port": "8443"
}

# roles/nginx/defaults/main.yml
nginx_port: 80
nginx_worker_processes: 1
nginx_keepalive_timeout: 65
nginx_log_dir: /var/log/nginx

# inventories/production/group_vars/webservers.yml
# defaultsの値を本番用に上書き
nginx_port: 443
nginx_worker_processes: auto

# roles/nginx/vars/main.yml
# 外から変更されては困る内部固有値（OS依存パス等）
nginx_pid_file: /run/nginx.pid
nginx_conf_dir: /etc/nginx
nginx_service_name: nginx

# site.yml
- hosts: webservers
  vars_files:
    - vars/common.yml
    - vars/{{ env }}_secrets.yml   # 環境ごとの機密ファイル（Vault暗号化推奨）
  roles:
    - nginx
    - app

# vars/production_secrets.yml（Ansible Vaultで暗号化）
db_password: "!vault |"
          ";1.1;AES256"
          "6236...（暗号化済み文字列）"
api_key: "!vault |"
         ";1.1;AES256"
         "3831...（暗号化済み文字列）"

# tasks/main.yml
- name: OSごとの変数ファイルを読み込む
  ansible.builtin.include_vars:
    file: "{{ ansible_os_family }}.yml"
  # RHEL系なら RedHat.yml、Debian系なら Debian.yml を読み込む

# vars/RedHat.yml
package_name: httpd
service_name: httpd
conf_path: /etc/httpd/conf/httpd.conf

# vars/Debian.yml
package_name: apache2
service_name: apache2
conf_path: /etc/apache2/apache2.conf

# CI/CDパイプライン（GitHub Actions等）からの呼び出し例
$ ansible-playbook deploy.yml   -i inventories/production/   -e "app_version="   -e "deploy_timestamp=20260710110559"   --vault-password-file ~/.vault_pass

# 本番インベントリを使いながら、ポートだけ変えて動作確認
$ ansible-playbook site.yml   -i inventories/production/   -e "http_port=8080"   --check    # 実際には変更しないドライランモード

# Playbook内にデバッグタスクを追加
- name: 変数の実値を確認する
  ansible.builtin.debug:
    msg: "http_port={{ http_port }}, db_host={{ db_host }}"

# 出力例
TASK [変数の実値を確認する] *****************
ok: [web01.example.com] => {
    "msg": "http_port=80, db_host=db.prod.example.com"
}

# インベントリ内の全変数を一覧表示（hostvars経由）
$ ansible web01.example.com -m debug   -a "var=hostvars[inventory_hostname]"   -i inventories/production/

# 特定変数だけ確認
$ ansible web01.example.com -m debug   -a "var=http_port"   -i inventories/production/

# -vvv でデータソースを含む詳細ログを出力
$ ansible-playbook site.yml   -i inventories/production/   -vvv 2>&1 | grep -A2 "http_port"

# 出力例（変数の定義元が確認できる）
"http_port": "80",   # group_vars/webservers.yml から読み込まれた値

# ホストごとの変数最終値をJSON形式で表示
$ ansible-inventory -i inventories/production/ --host web01.example.com

{
    "ansible_host": "192.0.2.10",
    "db_host": "db.prod.example.com",
    "http_port": "80",
    "max_connections": "200"
}