Ansibleのansible.cfg設計入門｜接続・実行・ログ・escalationの全セクションとプロジェクト別設定分離のパターン

この記事のポイント

・ansible.cfgは4段階の優先順で探索され、プロジェクト直下への配置が現場標準
・[defaults]・[privilege_escalation]・[ssh_connection]の3セクションが設計の中心
・pipelining=Trueの有効化でsudo対応かつPlaybook実行を大幅に高速化できる
・グローバル設定はansible.cfg、ホスト固有の差分はhost_varsに書き分けるのが鉄則

$ ansible --version
ansible [core 2.17.4]
  config file = /home/admin/ansible-project/ansible.cfg
  configured module search path = ['/home/admin/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3.9/site-packages/ansible
  ansible collection location = /home/admin/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/bin/ansible
  python version = 3.9.18 (main, Sep  7 2023, 00:00:00) [GCC 11.4.1 20230605 (Red Hat 11.4.1-2)]
  jinja version = 3.1.4
  libyaml = True

[defaults]
# デフォルトのインベントリファイルパス
inventory = ./inventory/hosts.yaml

# 接続先サーバーのSSHユーザー名
remote_user = ansible

# 初回接続時のhostkey確認を省略（CI/CDや開発環境で使用）
host_key_checking = False

# Roleの追加検索パス
roles_path = ./roles:~/.ansible/roles

# 並列接続数（デフォルトは5）
forks = 10

# 失敗したPlaybookの.retryファイルを生成しない（Ansible 2.12+でデフォルト無効化）
retry_files_enabled = False

# 実行結果の出力フォーマット（yaml/dense/oneline）
stdout_callback = yaml

# コールバックプラグインの有効化（タイミング情報の収集等）
callbacks_enabled = timer, profile_tasks

# 複数インベントリを指定する例（静的インベントリ＋動的インベントリの混在）
inventory = ./inventory/staging.yaml:./inventory/aws_ec2.yaml

# defaultフォーマットの出力例
TASK [install nginx] ********************
changed: [web01.example.com]

# yamlフォーマットの出力例（変更内容がYAML形式で詳細表示される）
TASK [install nginx] ********************
changed: [web01.example.com] => changed=true
  invocation:
    module_args:
      name:
      - nginx
      state: present

[privilege_escalation]
# 権限昇格を使用するか（全タスクにbecomeを適用する場合True）
become = True

# 昇格方法（sudo/su/pbrun/pfexec）
become_method = sudo

# 昇格後のユーザー（デフォルトはroot）
become_user = root

# sudoパスワードをインタラクティブに求めるか（NOPASSWDを前提とする場合False）
become_ask_pass = False

# inventory/host_vars/prod-web01.yaml（本番ホスト固有の設定）
ansible_become: true
ansible_become_method: sudo
ansible_become_user: root

# inventory/host_vars/dev-web01.yaml（開発ホストはbecome不要）
ansible_become: false

# /etc/sudoers.d/ansible（管理対象サーバー側の設定）
ansible ALL=(ALL) NOPASSWD: ALL

[ssh_connection]
# pipelining有効化（パフォーマンス改善の最重要設定）
pipelining = True

# SSH接続オプション（多重接続・タイムアウト設定）
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o StrictHostKeyChecking=no

# SSH多重接続のソケット保存先（デフォルトの/tmpより専用ディレクトリが推奨）
control_path_dir = ~/.ansible/cp

# requirettyの有無を確認（何も出力されなければ問題なし）
$ sudo grep requiretty /etc/sudoers /etc/sudoers.d/* 2>/dev/null

# pipelineの効果を実測する例（timeコマンドで実行時間を比較）
$ time ansible-playbook -i inventory/hosts.yaml site.yml

# pipelining=False（参考値）
real    2m47s
# pipelining=True（参考値）
real    1m23s

# モノレポ（単一リポジトリ）で複数環境を管理する構成例
ansible-project/
├── ansible.cfg              # プロジェクト共通設定
├── inventory/
│   ├── staging/
│   │   └── hosts.yaml
│   └── production/
│       └── hosts.yaml
├── group_vars/
│   ├── staging.yaml
│   └── production.yaml
├── host_vars/
└── site.yml

# システムごとにリポジトリとansible.cfgを完全分離する構成例
/home/admin/
├── webserver-ansible/
│   ├── ansible.cfg      # Webサーバー専用設定（remote_user=deploy）
│   └── site.yml
├── database-ansible/
│   ├── ansible.cfg      # DBサーバー専用設定（remote_user=dbadmin）
│   └── site.yml
└── monitoring-ansible/
    ├── ansible.cfg      # 監視システム専用設定
    └── site.yml

# .gitignore に追加する項目
.vault_pass
*.retry
*.pyc
__pycache__/

# 実際に読まれているansible.cfgを確認する
$ ansible --version | grep "config file"
  config file = /home/admin/other-project/ansible.cfg   # 意図しないパス

# ANSIBLE_CONFIG環境変数が設定されていないか確認
$ echo $ANSIBLE_CONFIG

# カレントディレクトリを確認（./ansible.cfgが優先される）
$ pwd && ls -la ansible.cfg

# requirettyの確認（RHEL系サーバーで実行）
$ sudo grep requiretty /etc/sudoers
Defaults    requiretty    # これが原因

# 対処：visudoでコメントアウトする
$ sudo visudo
# Defaults    requiretty    # 先頭に#を付けてコメントアウト

# またはsudoers.dで上書きする
$ echo 'Defaults !requiretty' | sudo tee /etc/sudoers.d/ansible-pipeline

[ssh_connection]
# host_key_checkingと合わせてssh_args側でも無効化する
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null