ansible-playbook

Ansible Playbook の開発

概要

Ansible の Playbook では、命令型のコマンドではなく、望ましいシステムの状態を宣言します。中核となる原則は冪等性です。Playbook を複数回実行しても、意図しない変更を加えることなく同じ結果が得られます。

使用する場面

• 新しい Playbook やロールを作成するとき
• インベントリファイルを記述するとき
• YAML 構文エラーをデバッグするとき
• モジュールのパラメーターに関する問題をトラブルシューティングするとき
• 変数の優先順位を理解するとき
• シェルスクリプトを Ansible に変換するとき

クイックリファレンス

プロジェクト構成

project/
├── ansible.cfg          # Configuration
├── inventory            # Host definitions
├── group_vars/          # Group variables
├── host_vars/           # Host-specific vars
├── roles/               # Reusable roles
└── playbooks/           # Playbook files

必須の ansible.cfg

[defaults]
inventory = ./inventory
roles_path = ./roles
host_key_checking = False
stdout_callback = yaml

[privilege_escalation]
become = True
become_method = sudo

モジュールのパターン

操作	モジュール	主なパラメーター
ディレクトリの作成	ansible.builtin.file	state: directory、mode、owner
ファイルのコピー	ansible.builtin.copy	src、dest、mode
テンプレート	ansible.builtin.template	src、dest、.j2 内の変数
パッケージのインストール	ansible.builtin.package	name、state: present
サービスの管理	ansible.builtin.service	name、state、enabled
コマンドの実行	ansible.builtin.command	cmd、結果の登録、changed_when の設定

変数の優先順位（低い順）

1. ロールのデフォルト値（defaults/main.yml）
2. インベントリの group_vars
3. インベントリの host_vars
4. Playbook の vars
5. ロールの vars（vars/main.yml）
6. タスクの vars
7. 追加の vars（-e）

ハンドラー

tasks:
  - name: Update config
    ansible.builtin.template:
      src: app.conf.j2
      dest: /etc/app.conf
    notify: Restart app

handlers:
  - name: Restart app
    ansible.builtin.service:
      name: app
      state: restarted

エラー処理

- block:
    - name: Risky operation
      ansible.builtin.command: /opt/app/upgrade.sh
  rescue:
    - name: Handle failure
      ansible.builtin.debug:
        msg: "Upgrade failed, rolling back"
  always:
    - name: Cleanup
      ansible.builtin.file:
        path: /tmp/upgrade.lock
        state: absent

よくある間違い

間違い	修正方法
短いモジュール名を使用する	常に FQCN を使用します。copy ではなく ansible.builtin.copy を指定します
値をハードコードする	defaults/main.yml の変数に切り出します
コマンドに changed_when がない	changed_when: "'created' in result.stdout" を追加します
ハンドラーのフラッシュを忘れる	依存するタスクの前に必要に応じて meta: flush_handlers を使用します
YAML のインデントエラー	スペースを 2 つ使用し、タブは使いません
引用符で囲まれていない文字列内のコロン	: を含む値を引用符で囲みます

検証コマンド

ansible-playbook --syntax-check playbook.yml  # Check YAML
ansible-playbook --check playbook.yml         # Dry run
ansible-playbook --check --diff playbook.yml  # Show file changes
ansible-inventory --list                       # Verify inventory
ansible-inventory --host hostname             # Check host vars