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

この記事のポイント

・ansible-playbookはYAMLのplaybookでサーバーを冪等設定できる
・インベントリでホスト一覧を定義してplaybookで操作対象を指定する
・--checkでドライラン、-v/-vvvでデバッグが本番適用前の基本
・ハンドラーで「変更時だけ再起動」を安全に制御できる
・site.yml×import_playbookで役割別・オペレーション別Playbookを一元管理できる
・import_playbookはPlaybook全体・import_tasksはtask列のみを読む別物
・commonロールをhosts:allで全ホストにベースライン設定を適用できる
・roleは「何を設定するか」、Playbookは「どこに配るか」で責任を分ける
・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"

# パターンマッチでホストを絞る（ワイルドカード使用可）
ansible-playbook -i inventory.yml site.yml --limit "web*"

# 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 --list-tags

playbook: site.yml

  play #1 (webservers): Webサーバー設定 TAGS: []
      TASK TAGS: [config, install, service]

  play #2 (dbservers): DBサーバー設定 TAGS: []
      TASK TAGS: [config, install]

# 標準の詳細ログ
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再起動     # 変更があった時だけハンドラーを呼び出す

TASK [設定ファイルのコピー] *****************************************************
changed: [web01.example.com]
changed: [web02.example.com]

RUNNING HANDLERS ***********************************************************
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
web02.example.com : ok=3  changed=2  unreachable=0  failed=0  skipped=0

[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

# プロジェクト構成例
.
├── site.yml           ← エントリーポイント
├── webservers.yml     ← Webサーバー設定Playbook
├── dbservers.yml      ← DBサーバー設定Playbook
├── lb.yml             ← ロードバランサー設定Playbook
├── inventory/
│   ├── staging/
│   │   ├── hosts
│   │   └── group_vars/
│   └── production/
│       ├── hosts
│       └── group_vars/
└── roles/
    ├── nginx/
    ├── mysql/
    └── haproxy/

# site.yml
---
# 1. まずロードバランサーを設定
- import_playbook: lb.yml

# 2. Webサーバー群の設定
- import_playbook: webservers.yml

# 3. DBサーバー群の設定
- import_playbook: dbservers.yml

# staging環境への適用
ansible-playbook -i inventory/staging/hosts site.yml

# 本番環境への適用
ansible-playbook -i inventory/production/hosts site.yml

# プロジェクト構成（環境分離版）
.
├── site.yml               ← 全環境一括（CI/CD用など）
├── staging.yml            ← staging専用エントリーポイント
├── production.yml         ← 本番専用エントリーポイント
├── webservers.yml
├── dbservers.yml
└── inventory/
    ├── staging/
    │   └── hosts
    └── production/
        └── hosts

# staging.yml
---
- import_playbook: webservers.yml
- import_playbook: dbservers.yml

# staging実行
ansible-playbook -i inventory/staging/hosts staging.yml

# 本番実行
ansible-playbook -i inventory/production/hosts production.yml

# site.yml（タグ付き）
---
- import_playbook: lb.yml
  tags: lb

- import_playbook: webservers.yml
  tags: web

- import_playbook: dbservers.yml
  tags: db

# Webサーバーの設定だけ実行
ansible-playbook -i inventory/hosts site.yml --tags web

# 実行対象のタスク一覧を事前確認
ansible-playbook -i inventory/hosts site.yml --tags web --list-tasks

# site.yml で利用可能なタグ一覧を確認する
ansible-playbook -i inventory/hosts site.yml --list-tags

# webタグのタスク一覧を事前確認してから実行する
ansible-playbook -i inventory/hosts site.yml --tags web --list-tasks
ansible-playbook -i inventory/hosts site.yml --tags web

# オペレーション別分割の構造例
playbooks/
├── setup.yml        # 初回構築（サーバー追加時のみ実行）
├── deploy.yml       # アプリデプロイ（頻繁に実行）
└── patch.yml        # OSパッチ適用（月次）

# playbooks/common.yml
---
- hosts: all
  become: yes
  roles:
    - common

# site.yml（commonロールを先頭に置く構成）
---
# 全ホストのベースライン設定（必ず最初に実行）
- import_playbook: playbooks/common.yml

# インフラ基盤レイヤー
- import_playbook: playbooks/dbservers.yml

# アプリケーションレイヤー（DBより後）
- import_playbook: playbooks/webservers.yml

# 監視設定（全サービスが起動してから）
- import_playbook: playbooks/monitoring.yml

# inventory/production/hosts
[lb]
lb01 ansible_host=192.168.10.10

[webservers]
web01 ansible_host=192.168.10.21
web02 ansible_host=192.168.10.22

[dbservers]
db01 ansible_host=192.168.10.31

[all:vars]
ansible_user=deploy
ansible_ssh_private_key_file=~/.ssh/deploy_key

# site.yml（3層構成完成形）
---
# 1. 全4台にベースライン設定（NTP・ユーザー・SSH設定）
- import_playbook: playbooks/common.yml

# 2. DBを先に構成（WebサーバーからDBへの接続情報が必要なため）
- import_playbook: playbooks/dbservers.yml

# 3. Webサーバーは必ずDBの後で構成する
- import_playbook: playbooks/webservers.yml

# 4. LBはWebが起動してから設定（バックエンドIPをヘルスチェック後に登録）
- import_playbook: playbooks/lb.yml

# playbooks/common.yml
---
- hosts: all
  become: yes
  roles:
    - common

# playbooks/dbservers.yml
---
- hosts: dbservers
  become: yes
  roles:
    - mysql

# playbooks/webservers.yml
---
- hosts: webservers
  become: yes
  roles:
    - nginx
    - app

# playbooks/lb.yml
---
- hosts: lb
  become: yes
  roles:
    - haproxy

# NG: site.ymlにPlayを直接書く
---
- name: Webサーバーの設定
  hosts: webservers
  roles:
    - nginx

# OK: import_playbookで委譲する
---
- import_playbook: webservers.yml

# .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

# NG: import_playbookにwhen:は使えない（Ansible 2.12以降include_playbookも廃止）
- import_playbook: webservers.yml
  when: env == "production"   # ERROR

# OK: エントリーポイントを環境別に分離する
# staging.yml / production.yml を別ファイルとして用意する（h3 3参照）

# 警告例
[WARNING]: Could not match supplied host pattern, ignoring: webservers
[WARNING]: No hosts matched, nothing to do

# インベントリのグループ構成を確認する
ansible-inventory -i inventory.yml --graph

# 特定グループのホスト一覧を確認する
ansible-inventory -i inventory.yml --list-hosts webservers

# NG：hostsと同列に書こうとしている（Playbookの中のPlay定義内）
- hosts: webservers
  import_playbook: other.yml   # これは不可

# OK：トップレベルに書く（hostsと並列でなく独立したリスト項目として）
- import_playbook: playbooks/webservers.yml
- hosts: monitoring
  roles:
    - prometheus

# 実行は常にプロジェクトルートから行う
cd /home/deploy/ansible-project
ansible-playbook -i inventory/production/hosts site.yml

# site.yml が /home/deploy/ansible-project/site.yml にある場合
# playbooks/webservers.yml は
# /home/deploy/ansible-project/playbooks/webservers.yml を参照する

# 対象ホスト一覧を事前に確認してスキップを事前検出する
ansible-playbook --list-hosts site.yml

# インベントリのグループ一覧を確認する
ansible-inventory -i inventory/production/hosts --graph

# NG: site.ymlでimport_tasksを使ってしまう
---
- import_tasks: webservers.yml   # hostsを含むPlaybookには使えない

# OK: Playbook全体を読み込む場合はimport_playbook
---
- import_playbook: webservers.yml

# import_tasksが適切な場面：role内部でのtaskファイル分割
# roles/nginx/tasks/main.yml
---
- import_tasks: install.yml     # tasks/install.yml のtask列を読む
- import_tasks: configure.yml   # tasks/configure.yml のtask列を読む