Ansibleのrole命名と変数プレフィックス規約｜複数roleを併用しても名前が衝突しない名前空間を作る

この記事のポイント

・Ansible変数はPlaybook全体がスコープ—role変数は名前が衝突しやすい
・role名を変数プレフィックスにする（例: nginx_port）のが公式推奨の規約
・defaults/main.ymlでプレフィックスを付けると衝突リスクをほぼゼロにできる
・group_vars・host_varsはroleのdefaultsより優先されるため環境差分の上書きに使う

# roles/nginx/defaults/main.yml
port: 80

# roles/mysql/defaults/main.yml
port: 3306

# NG: 汎用すぎる名前（他roleとの衝突リスクが高い）
roles/
  web/
  db/
  app/

# OK: 具体的で一意な名前
roles/
  nginx_webserver/
  mysql_database/
  django_app/

# Galaxy形式のrole名（requirements.ymlでの指定例）
- name: geerlingguy.nginx
  version: "3.2.0"

# 社内roleの命名例（mycompany=自社namespace）
roles/
  mycompany.nginx_webserver/
  mycompany.mysql_database/
  mycompany.app_deploy/

# roles/nginx_webserver/defaults/main.yml
nginx_webserver_port: 80
nginx_webserver_user: nginx
nginx_webserver_worker_processes: auto
nginx_webserver_access_log: /var/log/nginx/access.log

# roles/mysql_database/defaults/main.yml
mysql_database_port: 3306
mysql_database_root_password: "{{ vault_mysql_root_password }}"
mysql_database_max_connections: 200
mysql_database_datadir: /var/lib/mysql

# roles/nginx_webserver/tasks/main.yml
- name: Nginxをインストールする
  ansible.builtin.dnf:
    name: nginx
    state: present

- name: Nginxの設定ファイルを配置する
  ansible.builtin.template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: '0644'
  notify: nginx_webserver reload

# roles/nginx_webserver/templates/nginx.conf.j2
worker_processes {{ nginx_webserver_worker_processes }};

events {
    worker_connections 1024;
}

http {
    access_log {{ nginx_webserver_access_log }};
    server {
        listen {{ nginx_webserver_port }};
    }
}

# site.yml
- name: Webサーバーのセットアップ
  hosts: webservers
  become: true
  roles:
    - role: nginx_webserver
      vars:
        nginx_webserver_port: 8080
        nginx_webserver_worker_processes: 4
    - role: mysql_database
      vars:
        mysql_database_max_connections: 500

$ ansible-playbook -i inventory/production site.yml --check -v

PLAY [Webサーバーのセットアップ] *****************************

TASK [nginx_webserver : Nginxをインストールする] ***
ok: [web01.example.com]

TASK [nginx_webserver : Nginxの設定ファイルを配置する] ***
changed: [web01.example.com]

TASK [mysql_database : MySQLをインストールする] ***
ok: [web01.example.com]

PLAY RECAP ***
web01.example.com : ok=3  changed=1  unreachable=0  failed=0

# inventory/group_vars/production.yml
# 本番環境固有の設定（プレフィックスで対象roleが一目でわかる）
nginx_webserver_port: 443
nginx_webserver_worker_processes: 8
mysql_database_max_connections: 1000

# NG: 衝突する変数定義
port: 80         # roles/nginx/defaults/main.yml
port: 5432       # roles/postgresql/defaults/main.yml

# OK: プレフィックスで分離
nginx_port: 80              # roles/nginx/defaults/main.yml
postgresql_port: 5432       # roles/postgresql/defaults/main.yml

# コミュニティroleのdefaults変数名一覧を確認する
$ grep "^[a-z]" roles/geerlingguy.nginx/defaults/main.yml | cut -d: -f1
nginx_worker_processes
nginx_worker_connections
nginx_keepalive_timeout
nginx_listen_ipv6

# NG: プレフィックスなしで読み込む
- name: 設定ファイルを読み込む
  ansible.builtin.include_vars:
    file: config.yml   # 変数名にプレフィックスがない場合は危険

# OK: nameオプションでnamespace化する（Ansible 2.8+）
- name: 設定ファイルをnamespace付きで読み込む
  ansible.builtin.include_vars:
    file: config.yml
    name: nginx_webserver_config   # 辞書変数の中にキーが格納される