ホーム / Ansible /

ansible-playbook コマンド

2019/03/03

Ansible

 Ansible Documentation

ansible-playbook

 特徴

  • 対象ホストに対し playbook ファイルに記述したタスクを実行するコマンド
  • playbook ファイルに複数のタスクを定義することで、複数のタスクを順に実行できる
  • playbook ファイルにタスクの繰り返し実行や、条件成立時にタスクを実行するようにでき、複雑な処理を定義できる

 構文

  • ansible-playbook [options] playbook.yml [playbook2 ...]

 options

options指定する内容 / 指示する内容
-i
--inventory		 inventory ファイル名
"," で区切って対象ホストの IP アドレスを指定する
-l
--limit		targets セクションの hosts: で絞り込んだ対象ホストをさらに絞り込む
--list-tasks実行されるすべてのタスクのリスト
--start-at-task開始位置をタスク名で指定する
-C
--check		ドライラン（ dry run ）
--syntax-check構文チェック
-K
--ask-become-pass		実行時に become_user: で指定したユーザーアカウントのパスワードを要求する
-u
--user		対象ホストに接続するときのユーザー名（default=None）
-c
--connection		対象ホストに接続するときのコネクションタイプ（default=smart）
-t
--tags		指定したタグが付いたタスクだけを実行する
--skip-tags指定したタグが付いたタスクを除いて実行する
-e
--extra-vars		コマンドラインで変数を追加定義する

 例

■ inventory ファイル : hosts.yml 
all:
  hosts:
    node1:
    node2:
    node3:
■ playbook ファイル : site.yml 
---
- hosts: all

  vars:
    pkgs:
      - open-vm-tools
      - httpd

  tasks:
    - name: 初期パッケージのインストール
      yum:
        name: "{{ item }}"
        state: latest
      loop: "{{ pkgs }}"

    - name: インストール済パッケージのアップデート
      yum:
        name: '*'
        state: latest
■ 構文チェック 
[ansibleman@ansiblesv ansible]$ ansible-playbook -i hosts.yml --syntax-check site.yml
 
playbook: site.yml
[ansibleman@ansiblesv ansible]$

■ ドライラン 
[ansibleman@ansiblesv ansible]$ ansible-playbook -i hosts.yml -C site.yml 
 
PLAY [all] ****************************************************************************************
 
TASK [Gathering Facts] ****************************************************************************
ok: [node2]
ok: [node3]
ok: [node1]
 
TASK [初期パッケージのインストール] *****************************************************************************
changed: [node2] => (item=open-vm-tools)
changed: [node1] => (item=open-vm-tools)
changed: [node3] => (item=open-vm-tools)
changed: [node1] => (item=httpd)
changed: [node2] => (item=httpd)
changed: [node3] => (item=httpd)
 
TASK [インストール済パッケージのアップデート] ************************************************************************
changed: [node3]
changed: [node1]
changed: [node2]
 
PLAY RECAP ****************************************************************************************
node1                      : ok=3    changed=2    unreachable=0    failed=0   
node2                      : ok=3    changed=2    unreachable=0    failed=0   
node3                      : ok=3    changed=2    unreachable=0    failed=0   
 
[ansibleman@ansiblesv ansible]$

■ 実行 
[ansibleman@ansiblesv ansible]$ ansible-playbook -i hosts.yml site.yml
 
PLAY [all] ****************************************************************************************
 
TASK [Gathering Facts] ****************************************************************************
ok: [node2]
ok: [node1]
ok: [node3]
 
TASK [初期パッケージのインストール] *****************************************************************************
changed: [node3] => (item=open-vm-tools)
changed: [node1] => (item=open-vm-tools)
changed: [node2] => (item=open-vm-tools)
changed: [node3] => (item=httpd)
changed: [node2] => (item=httpd)
changed: [node1] => (item=httpd)
 
TASK [インストール済パッケージのアップデート] ************************************************************************
changed: [node3]
changed: [node1]
changed: [node2]
 
PLAY RECAP ****************************************************************************************
node1                      : ok=3    changed=2    unreachable=0    failed=0   
node2                      : ok=3    changed=2    unreachable=0    failed=0   
node3                      : ok=3    changed=2    unreachable=0    failed=0   
 
[ansibleman@ansiblesv ansible]$

  実行結果の見方

タスクごとの実行結果に色つきの文字が表示されている部分があります。これは、対象ホストでタスクを実行したときの結果で異なります。
  • ok : 緑色
  • 対象ホストにタスクを実行したが、対象ホストの状態は変更されなかった
  • changed : 黄色
  • 対象ホストにタスクを実行した結果、対象ホストの状態が変更された
  • skipping : 水色
  • 対象ホストにタスクを実行しなかった（タスクの実行を飛ばした）
  • failed : 赤色
  • 対象ホストにタスクを実行したら、何らかのエラーが発生した
最後に出力される "PLAY RECAP" は対象ホストごとのタスクの実行結果のサマリーです。
  • ok
  • 対象ホストで正常に実行したタスクの数 : ok + changed
  • changed
  • 対象ホストの状態を変更したタスクの数
  • unreachable
  • 対象ホストに接続できなかったタスクの数
  • failed
  • 対象ホストでエラーが発生したタスクの数
通常は unreachable と failed がゼロであれば、正しく実行できたと判断できます。

 タスクの実行と対象ホスト

 Ansible では 1 つのタスクに対しすべての対象ホストによる実行が終了した後に次のタスクに移ります。このことを踏まえて、複数の対象ホストに対し playbook ファイルを適用する場合、対象ホストの実行順序や同時に実行する組み合わせを考慮する必要があります。例えば、「サービスの停止　→　パッチの適用　→　サービスの再起動」の 3 つのタスクからなる playbook ファイルがあったとします。これを主系と従系からなる二重化されたシステムに適用する場合で考えてみます。主系と従系に対して同タイミングで playbook ファイルを実行した場合、最初の「サービスの停止」のタスクで主系と従計の両方が停止し、サービスダウンが発生します。このような状態を避けるため、最初に主系または従系のどちらかに playbook ファイルを適用し、その後、残りの系統に適用します。このように、実行する対象ホストの組み合わせにより思わぬ結果になるため注意が必要です。

 実行時のエラー

対象ホストでタスクを実行したときに何らかのエラーが発生した場合、その対象ホストはエラーが発生したタスクで実行が中断します = エラーが発生したタスク以降のタスクは実行されません。タスクを実行した結果、エラーが発生しなければ処理は継続します。次の playbook は対象ホスト node-u1810 でタスク [Gathering Facts] の実行時にエラーが発生しました。そのため、node-u1810 を除く対象ホストだけがタスク [対象ホストの OS] 以降の処理を実行しました。
---
- hosts: all

  tasks:
    - name: 対象ホストの OS
      debug:
        msg: "{{ inventory_hostname }} => {{ ansible_distribution }} {{ ansible_distribution_version }}"
    - ping:
      register: result
    - name: ping の実行結果
      debug:
        var: result
■ 実行結果 
[ansibleman@ansiblesv ansible]$ ansible-playbook -i hosts.yml site.yml
 
PLAY [all] ****************************************************************************************
 
TASK [Gathering Facts] ****************************************************************************
ok: [node-d0908]
fatal: [node-u1810]: FAILED! => {"changed": false, "module_stderr": "Shared connection to 192.168.101.23 closed.\r\n", "module_stdout": "/bin/sh: 1: /usr/bin/python: not found\r\n", "msg": "MODULE FAILURE\nSee stdout/stderr for the exact error", "rc": 127}
ok: [node-c0706]
ok: [node-c0610]
 
TASK [対象ホストの OS] **********************************************************************************
ok: [node-d0908] => {
    "msg": "node-d0908 => Debian 9.8"
}
ok: [node-c0610] => {
    "msg": "node-c0610 => CentOS 6.10"
}
ok: [node-c0706] => {
    "msg": "node-c0706 => CentOS 7.6.1810"
}
 
TASK [ping] ***************************************************************************************
ok: [node-d0908]
ok: [node-c0706]
ok: [node-c0610]
 
TASK [ping の実行結果] *********************************************************************************
ok: [node-d0908] => {
    "result": {
        "changed": false, 
        "failed": false, 
        "ping": "pong"
    }
}
ok: [node-c0610] => {
    "result": {
        "changed": false, 
        "failed": false, 
        "ping": "pong"
    }
}
ok: [node-c0706] => {
    "result": {
        "changed": false, 
        "failed": false, 
        "ping": "pong"
    }
}
        to retry, use: --limit @/home/ansibleman/ansible/site.retry
 
PLAY RECAP ****************************************************************************************
node-c0610                 : ok=4    changed=0    unreachable=0    failed=0   
node-c0706                 : ok=4    changed=0    unreachable=0    failed=0   
node-d0908                 : ok=4    changed=0    unreachable=0    failed=0   
node-u1810                 : ok=0    changed=0    unreachable=0    failed=1
 
[ansibleman@ansiblesv ansible]$

 冪等性

対象ホストに playbook ファイルを複数回適用（実行）しても常に同じ結果になることを「冪等性を保っている」と言います。playbook ファイルの  1 回目の実行で changed が発生しても、2 回目以降の実行ではすべて ok になれば、その playbook ファイルは冪等性を保っていると言えます。次の実行結果は、「実行例」であげた playbook ファイルの 2 回目の実行結果です。
[ansibleman@ansiblesv ansible]$ ansible-playbook -i hosts.yml site.yml
 
PLAY [all] ****************************************************************************************
 
TASK [Gathering Facts] ****************************************************************************
ok: [node1]
ok: [node2]
ok: [node3]
 
TASK [初期パッケージのインストール] *****************************************************************************
ok: [node3] => (item=open-vm-tools)
ok: [node2] => (item=open-vm-tools)
ok: [node1] => (item=open-vm-tools)
ok: [node3] => (item=httpd)
ok: [node2] => (item=httpd)
ok: [node1] => (item=httpd)
 
TASK [インストール済パッケージのアップデート] ************************************************************************
ok: [node1]
ok: [node3]
ok: [node2]
 
PLAY RECAP ****************************************************************************************
node1                      : ok=3    changed=0    unreachable=0    failed=0   
node2                      : ok=3    changed=0    unreachable=0    failed=0   
node3                      : ok=3    changed=0    unreachable=0    failed=0   
 
[ansibleman@ansiblesv ansible]$

 変更履歴

2019/03/04　「タスクの実行と対象ホスト」を追記した
2019/03/05　「実行時のエラー」の例示を変更した
2019/03/08　「options」に -l / --limit を追記した
2019/04/30　「options」に -K / --ask-become-pass を追記した
2019/06/01　「options」に --list-tasks を追記した
2019/06/02　「options」に --start-at-task を追記した
2019/06/06　「options」に -t / --tags と --skip-tags を追記した
2019/06/09　「options」に -u / --user と -c / --connection を追記した。 -i / --inventory の内容を更新した
2019/06/15　「options」に -e / --extra-vars を追記した

カテゴリー

目次

QooQ