ansible-playbookコマンドの使い方｜インベントリ・playbook作成からLinuxサーバー自動化の実践例まで

この記事のポイント

・ansible-playbookはYAMLのplaybookでサーバーを冪等設定できる
・インベントリでホスト一覧を定義してplaybookで操作対象を指定する
・--checkでドライラン、-v/-vvvでデバッグが本番適用前の基本
・ハンドラーで「変更時だけ再起動」を安全に制御できる
・GitHub Actionsと連携してPlaybook検証・デプロイを自動化できる

# EPELリポジトリの有効化
sudo dnf install -y epel-release

# Ansibleのインストール
sudo dnf install -y ansible

# バージョン確認
ansible --version

# 公式PPAを追加してからインストール（最新版を使う場合）
sudo apt-add-repository --yes --update ppa:ansible/ansible
sudo apt install -y ansible

# または標準リポジトリから（バージョンは古い場合あり）
sudo apt install -y ansible

# バージョン確認
ansible --version

# 仮想環境の作成とAnsibleのインストール
python3 -m venv ~/ansible-env
source ~/ansible-env/bin/activate
pip install ansible ansible-lint

# バージョン確認
ansible --version
ansible-lint --version

[admin@controller ~]$ ansible --version
ansible [core 2.16.3]
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/home/admin/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3.11/site-packages/ansible
  ansible collection location = /home/admin/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/bin/ansible
  python version = 3.11.7
  jinja2 version = 3.1.2
  libyaml = True

# /etc/ansible/hosts または任意の inventory.ini

# 単独のホスト指定
web01.example.com
192.168.10.11

# グループ化
[webservers]
web01.example.com
web02.example.com

[dbservers]
db01.example.com ansible_user=dbadmin ansible_port=2222

# グループのグループ（親グループ）
[datacenter:children]
webservers
dbservers

# inventory.yml
all:
  children:
    webservers:
      hosts:
        web01.example.com:
          ansible_user: ec2-user
        web02.example.com:
          ansible_user: ec2-user
    dbservers:
      hosts:
        db01.example.com:
          ansible_user: dbadmin
          ansible_port: 2222
  vars:
    ansible_ssh_private_key_file: ~/.ssh/id_rsa

# インベントリ内のホスト一覧を表示
ansible-inventory -i inventory.yml --list

# グラフ形式で確認
ansible-inventory -i inventory.yml --graph

# 疎通確認（pingモジュール）
ansible -i inventory.yml webservers -m ping

# site.yml
---
- name: Webサーバー初期設定
  hosts: webservers
  become: yes          # sudo で実行

  tasks:
    - name: Apacheのインストール
      ansible.builtin.dnf:
        name: httpd
        state: present

    - name: Apacheの起動と自動起動有効化
      ansible.builtin.service:
        name: httpd
        state: started
        enabled: yes

tasks:
  - name: Apacheのインストール（RHEL系）
    ansible.builtin.dnf:
      name: httpd
      state: present
    when: ansible_os_family == "RedHat"

  - name: Apacheのインストール（Debian系）
    ansible.builtin.apt:
      name: apache2
      state: present
    when: ansible_os_family == "Debian"

# 基本実行
ansible-playbook -i inventory.yml site.yml

# SSH鍵を指定して実行
ansible-playbook -i inventory.yml site.yml --private-key=~/.ssh/id_rsa

# sudo パスワードを対話的に入力する場合
ansible-playbook -i inventory.yml site.yml --ask-become-pass

# ドライラン（変更は行わず確認のみ）
ansible-playbook -i inventory.yml site.yml --check

# ドライランと差分表示を組み合わせる（より詳細）
ansible-playbook -i inventory.yml site.yml --check --diff

# 特定ホストのみ実行
ansible-playbook -i inventory.yml site.yml --limit web01.example.com

# 特定グループのみ実行
ansible-playbook -i inventory.yml site.yml --limit webservers

# 複数ホストをカンマ区切りで指定
ansible-playbook -i inventory.yml site.yml --limit "web01.example.com,web02.example.com"

# playbook にタグを付ける例
---
- name: Webサーバー設定
  hosts: webservers
  become: yes
  tasks:
    - name: Apacheのインストール
      ansible.builtin.dnf:
        name: httpd
        state: present
      tags: install

    - name: 設定ファイルのコピー
      ansible.builtin.copy:
        src: httpd.conf
        dest: /etc/httpd/conf/httpd.conf
      tags: config

# installタグのタスクのみ実行
ansible-playbook -i inventory.yml site.yml --tags install

# configタグのタスクをスキップ
ansible-playbook -i inventory.yml site.yml --skip-tags config

# 標準の詳細ログ
ansible-playbook -i inventory.yml site.yml -v

# さらに詳細なデバッグ情報（SSH接続情報も表示）
ansible-playbook -i inventory.yml site.yml -vvv

# 最大詳細ログ（機密情報も表示されるため開発環境限定・本番では使用禁止）
ansible-playbook -i inventory.yml site.yml -vvvv

# site.yml
---
- name: Webサーバー設定
  hosts: webservers
  become: yes
  vars:
    http_port: 80
    max_clients: 200
    server_name: "{{ inventory_hostname }}"

  tasks:
    - name: httpdのインストール
      ansible.builtin.dnf:
        name: httpd
        state: present

    - name: 設定ファイルをテンプレートから生成
      ansible.builtin.template:
        src: httpd.conf.j2
        dest: /etc/httpd/conf/httpd.conf
        owner: root
        group: root
        mode: '0644'

---
- name: Apacheの設定と起動
  hosts: webservers
  become: yes

  handlers:
    - name: apache再起動
      ansible.builtin.service:
        name: httpd
        state: restarted

  tasks:
    - name: Apacheのインストール
      ansible.builtin.dnf:
        name: httpd
        state: present

    - name: 設定ファイルのコピー
      ansible.builtin.copy:
        src: httpd.conf
        dest: /etc/httpd/conf/httpd.conf
      notify: apache再起動     # 変更があった時だけハンドラーを呼び出す

[admin@controller ~]$ ansible-playbook -i inventory.yml site.yml

PLAY [Webサーバー初期設定] ****************************************************

TASK [Gathering Facts] *********************************************************
ok: [web01.example.com]
ok: [web02.example.com]

TASK [Apacheのインストール] *****************************************************
changed: [web01.example.com]
changed: [web02.example.com]

TASK [Apacheの起動と自動起動有効化] ********************************************
changed: [web01.example.com]
changed: [web02.example.com]

PLAY RECAP *********************************************************************
web01.example.com : ok=3  changed=2  unreachable=0  failed=0  skipped=0  rescued=0  ignored=0
web02.example.com : ok=3  changed=2  unreachable=0  failed=0  skipped=0  rescued=0  ignored=0

# site.yml
---
- name: Webサーバーの構成適用
  hosts: webservers
  serial: 2                   # 一度に2台ずつ更新
  max_fail_percentage: 30     # 30%超失敗で中断
  become: yes
  roles:
    - nginx

# ansible-galaxy コマンドでロールの雛形を作成
ansible-galaxy init roles/webserver

# 生成されるディレクトリ構造
roles/
└── webserver/
    ├── tasks/
    │   └── main.yml        # メインのタスク定義
    ├── handlers/
    │   └── main.yml        # ハンドラー定義
    ├── templates/
    │   └── httpd.conf.j2   # Jinja2テンプレート
    ├── files/
    ├── vars/
    │   └── main.yml        # 変数定義
    ├── defaults/
    │   └── main.yml        # デフォルト変数
    ├── meta/
    │   └── main.yml        # ロールのメタ情報
    └── README.md

# site.yml（ロール呼び出し版）
---
- name: Webサーバーの構成
  hosts: webservers
  become: yes
  roles:
    - webserver    # roles/webserver/ を自動的に読み込む
    - firewall     # roles/firewall/ も適用

# コレクションのインストール（例：Nginx公式コレクション）
ansible-galaxy collection install nginxinc.nginx_core

# インストール済みコレクション一覧
ansible-galaxy collection list

# .github/workflows/ansible-syntax-check.yml
name: Ansible Syntax Check

on:
  pull_request:
    paths:
      - 'playbooks/**'
      - 'roles/**'
      - 'inventory/**'

jobs:
  syntax-check:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4

      - name: Playbookの構文チェック
        run: |
          ansible-playbook playbooks/site.yml             --inventory inventory/production/hosts.ini             --syntax-check
        env:
          ANSIBLE_HOST_KEY_CHECKING: "False"

      - name: ansible-lintの実行
        run: |
          ansible-lint playbooks/site.yml             --profile production

# .github/workflows/ansible-deploy.yml
name: Ansible Deploy

on:
  push:
    branches:
      - main

jobs:
  dry-run:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4

      - name: SSH鍵の配置
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.ANSIBLE_SSH_PRIVATE_KEY }}" > ~/.ssh/ansible_rsa
          chmod 600 ~/.ssh/ansible_rsa

      - name: Vaultパスワードファイル作成
        run: printf '%s' "${{ secrets.ANSIBLE_VAULT_PASSWORD }}" > /tmp/vault_pass.txt

      - name: dry-run（--check --diff）
        run: |
          ansible-playbook playbooks/site.yml             --inventory inventory/production/hosts.ini             --vault-password-file /tmp/vault_pass.txt             --check --diff             --private-key ~/.ssh/ansible_rsa
        env:
          ANSIBLE_HOST_KEY_CHECKING: "False"

      - name: Vaultパスワードファイル削除
        if: always()
        run: rm -f /tmp/vault_pass.txt

  deploy:
    needs: dry-run
    runs-on: self-hosted
    environment: production   # 承認者によるレビューゲート
    steps:
      - uses: actions/checkout@v4
      # ... （dry-runと同様にPlaybook本番適用）

# エラー例
fatal: [web01.example.com]: UNREACHABLE! => {"changed": false, "msg": "Failed to connect to the host via ssh", "unreachable": true}

# 疎通確認
ansible -i inventory.yml web01.example.com -m ping

# SSHで直接接続テスト
ssh -i ~/.ssh/id_rsa admin@web01.example.com

# インベントリの接続情報を確認
ansible-inventory -i inventory.yml --host web01.example.com

# エラー例
fatal: [web01.example.com]: FAILED! => {"msg": "Missing sudo password"}

# 対処1：インタラクティブにパスワードを入力
ansible-playbook -i inventory.yml site.yml --ask-become-pass

# 対処2：sudoersでパスワードなしを設定（NOPASSWD）
# /etc/sudoers に以下を追加（visudo で編集）
# ansibleuser ALL=(ALL) NOPASSWD: ALL

# エラー例
fatal: [web01.example.com]: FAILED! => {"changed": false, "msg": "No package matching 'httpd' found available"}

# 対処：パッケージリポジトリの確認
# -vvv でより詳細なエラー内容を確認
ansible-playbook -i inventory.yml site.yml -vvv

# 手動でパッケージ確認（アドホックコマンド）
ansible -i inventory.yml webservers -m shell -a "dnf list available httpd" --become

# 問題：echo は末尾に改行を付与するためパスワードが一致しない
echo "$VAULT_PASSWORD" > /tmp/vault_pass.txt   # NG

# 解決：printf '%s' で末尾改行を除去してから書き出す
printf '%s' "$VAULT_PASSWORD" > /tmp/vault_pass.txt   # OK

# 手動でVaultファイルを検証する
ansible-vault decrypt group_vars/production/vault.yml --ask-vault-pass

# NGパターン（毎回ユーザーを作ろうとする）
- name: ユーザー作成
  ansible.builtin.shell: useradd appuser

# OKパターン（すでに存在していれば変更なし）
- name: ユーザー作成（冪等）
  ansible.builtin.user:
    name: appuser
    state: present
    shell: /bin/bash