--- title: "Ansibleの使い方入門：インストールからアドホックコマンド・最初のPlaybookまで【2.21系】" url: "https://www.issoh.co.jp/tech/details/18473/" published: 2026-10-18 updated: 2026-10-18 categories: ["自動化"] publisher: "株式会社一創" --- # Ansibleの使い方入門：インストールからアドホックコマンド・最初のPlaybookまで【2.21系】 Ansibleの使い方は、制御ノードへのインストール、ansible.cfgとインベントリの作成、アドホックコマンドでの単発作業、Playbookでの手順化という4段階で覚えると迷いません。この記事では、ansible-core 2.21系を前提に、検証用のサーバー2台へ接続するところから、`ping`・`shell`・`copy`のアドホックコマンド、変数と`loop`で複数ユーザーを作る最初のPlaybookまでを、そのまま打てるコマンド付きで示します。最後に、アドホックで済ませる作業とPlaybookに書く作業の境界も整理しました。版番号と仕様は2026年10月時点の公式ドキュメントとPyPIで確かめた内容です。 ## まとめ｜Ansibleの使い方はインストール・インベントリ・アドホック・Playbookの4段階 入門で押さえる順番は次のとおりです。 1. 制御ノード（Linux・macOS・WSL）にPythonの仮想環境を作り、`ansible-core`を系列固定で入れる。管理対象のサーバーには何も入れない 2. 作業ディレクトリに`ansible.cfg`と`inventory.ini`を置き、設定をそのディレクトリの中に閉じ込める 3. `ansible all -m ansible.builtin.ping`が全台で`pong`を返すまで、Playbookには進まない 4. 1回きりの確認や再起動はアドホックコマンドで流し、2回以上繰り返す作業や手順書に残す作業はPlaybookに書く Playbookを2回流して、2回目が`changed=0`になれば入門の手順は完了です。 ## Ansibleを動かす前提：制御ノードと管理対象ノードの要件と検証環境の構成 Ansibleがエージェントを入れずにSSHで動く仕組みと、構成管理ツールとしての長所・短所は[Ansibleとは？エージェントレスの仕組みとメリット・デメリット、Red Hat AAPの制約](https://www.issoh.co.jp/tech/details/6533/)で扱っています。ここからは手を動かす手順だけを書きます。 ### 制御ノードはLinux・macOS・WSLで、管理対象にはPythonとSSHだけを用意 [公式のインストールガイド](https://docs.ansible.com/projects/ansible/latest/installation%5Fguide/intro%5Finstallation.html)によると、Ansibleを実行する制御ノードはPythonが動くUNIX系のマシンであればよく、Red Hat系・Debian系・Ubuntu・macOSが対象です。WindowsはWSL上のLinuxでのみ制御ノードになれます。ネイティブのWindowsからは実行できません。 管理対象ノードにはAnsibleを入れる必要がありません。要るのは、SSHでログインできるユーザーと、Ansibleが送り込むモジュールを動かすためのPythonの2つだけです。[公式のリリースとメンテナンスの表](https://docs.ansible.com/projects/ansible/latest/reference%5Fappendices/release%5Fand%5Fmaintenance.html)では、ansible-core 2.21系の制御ノードに必要なPythonは3.12〜3.14、管理対象側は3.9〜3.14とされています。古いCentOS 7のようにPythonが3.6止まりのサーバーは、2.21系の管理対象になりません。 以降の例は、制御ノード1台と、AlmaLinuxなどRHEL系の検証サーバー2台（web01・web02）を想定しています。 ### ansibleとansible-coreの違いとpipでのインストール・バージョン固定 PyPIには2つのパッケージがあります。`ansible-core`は組み込みのモジュールとプラグインだけを含む最小構成で、`ansible`はコミュニティが選んだコレクション一式を同梱した大きなパッケージです。[PyPIのansible-core](https://pypi.org/project/ansible-core/)では2.21.5が最新で（2026年10月5日公開）、同梱版の`ansible`は14.5.0（2026年10月6日公開）でした。14.x系がcore 2.21系に対応します。 ``` # 制御ノードに仮想環境を作り、ansible-coreを2.21系に固定して入れる python3 -m venv ~/.venvs/ansible source ~/.venvs/ansible/bin/activate pip install "ansible-core==2.21.*" # 入ったバージョンと、使われているPython・設定ファイルの場所を確認する ansible --version ``` 入門ではcoreだけで足ります。ネットワーク機器やクラウドのモジュールが必要になった時点で、必要なコレクションだけを追加すれば済むためです。系列を`2.21.*`で固定しておくと、挙動が変わる系列の更新を自分で決めた時期に寄せられます。公式ガイドには`pipx install ansible-core`で入れる方法も載っており、仮想環境の管理を任せたい場合はこちらでも構いません。 ## ansible.cfgとインベントリの作り方：作業ディレクトリに設定を閉じ込める インストール直後の状態では、Ansibleは`/etc/ansible/hosts`をインベントリとして探します。案件ごとに対象サーバーが違うのが普通なので、設定とインベントリは作業ディレクトリに置きます。 ### ansible.cfgの読み込み順4段階とプロジェクト直下に置く理由 [公式の設定リファレンス](https://docs.ansible.com/projects/ansible/latest/reference%5Fappendices/config.html)では、設定ファイルは次の順で探され、最初に見つかった1つだけが使われます。 1. 環境変数`ANSIBLE_CONFIG`で指定したファイル 2. カレントディレクトリの`ansible.cfg` 3. ホームディレクトリの`~/.ansible.cfg` 4. `/etc/ansible/ansible.cfg` 複数のファイルの設定が合算されるわけではありません。ホームに置いた設定が効かないと悩む原因の多くは、カレントディレクトリに別の`ansible.cfg`があることです。`ansible --version`の出力の`config file`行を見れば、どのファイルが使われているかが分かります。もう1つの例外として、誰でも書き込めるディレクトリ（パーミッション777など）に置いた`ansible.cfg`は、第三者に設定を差し込まれる危険があるため読み込まれません。 ``` # 作業ディレクトリの構成 ansible-intro/ ├── ansible.cfg ├── inventory.ini └── users.yml # ansible.cfg（全項目入りのひな形は ansible-config init --disabled で出力できる） [defaults] inventory = ./inventory.ini remote_user = deploy forks = 5 ``` 並列で接続する台数`forks`の既定値は5です。`host_key_checking`は既定で`True`のままにしておきます。検証で`Host key verification failed`が出ても`False`にはせず、一度手でSSH接続するか`ssh-keyscan`で`known_hosts`に登録して解消します。`False`にした設定ファイルが本番の作業ディレクトリへ持ち込まれると、接続先のすり替えに気付けなくなるためです。 ### グループ・変数とansible-inventory –graphによる所属確認 インベントリは、接続先のホストをグループ名で束ねたファイルです。書き方は[公式のインベントリガイド](https://docs.ansible.com/projects/ansible/latest/inventory%5Fguide/intro%5Finventory.html)にINI形式とYAML形式があり、最初は行数の少ないINI形式で十分です。 ``` # inventory.ini [web] web01 ansible_host=192.0.2.11 web02 ansible_host=192.0.2.12 [db] db01 ansible_host=192.0.2.21 [web:vars] http_port=8080 # グループ構成と、ホストごとに解決される変数を確認する ansible-inventory --graph ansible-inventory --host web01 ``` `ansible_host`は接続先のIPアドレスで、行頭のweb01は作業で呼ぶための名前です。`[web:vars]`に書いた変数の適用範囲は、webグループに属する全ホストです。[ansible-inventoryコマンド](https://docs.ansible.com/projects/ansible/latest/cli/ansible-inventory.html)の`--graph`はグループの木構造を、`--host`はそのホストに最終的に渡る変数を表示するので、Playbookを書く前にここで所属と値を確かめます。ホストが増えて変数が多くなったら、`group_vars/web.yml`のようにファイルを分けます。 ## アドホックコマンドの使い方：ping・shell・copyで単発の作業を流す アドホックコマンドは、Playbookを書かずに1つのモジュールを複数台へ一度に流す使い方です。接続確認、全台の稼働状況の確認、緊急の再起動のように、手順として残すほどではない作業に向いています。 ### ansibleコマンドの書式と-mを省略したときのcommandモジュール [公式のアドホックコマンドガイド](https://docs.ansible.com/projects/ansible/latest/command%5Fguide/intro%5Fadhoc.html)の書式は`ansible [対象] -m [モジュール] -a "[引数]"`です。対象にはインベントリのグループ名、ホスト名、全台を表す`all`を書きます。 ``` # 全台への接続とPythonの実行を確認する（pongが返れば成功） ansible all -m ansible.builtin.ping # -m を省略すると command モジュールでコマンドを実行する ansible web -a "uptime" # root権限が要る操作は --become、sudoのパスワード入力が要るなら -K を足す ansible web -a "/usr/bin/systemctl is-active sshd" --become -K ``` `-m`を書かないときの既定モジュールは`ansible.builtin.command`です。pingで失敗する原因は、ほぼSSH鍵か`remote_user`の指定のどちらかです。`-vvv`を付けて流すと、実際に使われたユーザーと鍵が表示されるので、Playbookへ進む前にここで潰します。 ### shellとcommandの使い分け：パイプやリダイレクトが要るときだけshell commandモジュールはシェルを通さずにコマンドを実行するため、`|`や`>`、`$HOME`のような変数展開が使えません。パイプが要るときだけ`ansible.builtin.shell`に切り替えます。 ``` # パイプを使うので shell モジュールを指定する ansible web -m ansible.builtin.shell -a "df -h | grep -v tmpfs" ``` [shellモジュールのリファレンス](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/shell%5Fmodule.html)は、シェルの機能が不要な場面ではcommandを使うよう勧めています。shellは引数がそのまま`/bin/sh`に渡るので、変数を埋め込むと`;`などで別のコマンドを差し込まれる余地が生まれるためです。変数を渡すときは`quote`フィルタで囲みます。どちらのモジュールも状態を判断できず、流すたびに`changed`を返す点も覚えておきます。 ### copy・dnf・serviceモジュールで状態を宣言しchangedを読む ファイルの配布やパッケージの導入は、コマンドではなく専用モジュールで書きます。モジュールは「こうなっていてほしい状態」を受け取り、すでにその状態なら何もしません。 ``` # ファイルを配る（同じ内容がすでにあれば ok、書き換えたら changed） ansible web -m ansible.builtin.copy -a "src=./motd dest=/etc/motd mode=0644" --become # パッケージを入れる（-C を付けると変更せずに結果だけを見る） ansible web -m ansible.builtin.dnf -a "name=chrony state=present" --become -C # サービスを起動する ansible web -m ansible.builtin.service -a "name=chronyd state=started enabled=true" --become ``` 同じコマンドを2回流すと、1回目は`CHANGED`、2回目は`SUCCESS`（変更なし）と表示が変わります。何度流しても結果が同じになるこの性質が[冪等性](https://www.issoh.co.jp/tech/details/13382/)で、shellで書いた作業との一番大きな違いです。`-C`（`--check`）を付けると、対象ホストを一切変更せずに「変わるかどうか」だけを返します。 ### setupモジュールでファクトを集めOSやメモリ量を一覧で確認 Ansibleは接続先のOS・IPアドレス・メモリ量などを「ファクト」として集めます。アドホックで`ansible.builtin.setup`を流すと、その中身を確認できます。 ``` # OSの系統とバージョンだけを絞り込んで表示する ansible all -m ansible.builtin.setup -a "filter=ansible_distribution*" # メモリ量（MB）を確認する ansible all -m ansible.builtin.setup -a "filter=ansible_memtotal_mb" ``` フィルタなしで流すと1台あたり数百行のJSONが出るので、`filter`で項目を絞ります。ここで確かめた`ansible_distribution_major_version`のような名前は、Playbookの`when`で「RHEL 9系だけに流す」といった条件分岐にそのまま使えます。 ## 最初のPlaybookを実行する：変数とloopで複数ユーザーを作る手順 アドホックで接続とモジュールの動きを確かめたら、手順をファイルに書きます。題材は「webグループの全台に、運用担当者のユーザーを3人分作る」作業です。 ### users.ymlの全文とhosts・vars・loop・itemの役割 ``` --- - name: 運用担当者のユーザーを作成する hosts: web become: true vars: ops_users: - name: tanaka uid: 2001 - name: suzuki uid: 2002 - name: sato uid: 2003 tasks: - name: 運用担当者のユーザーを作る ansible.builtin.user: name: "{{ item.name }}" uid: "{{ item.uid }}" groups: wheel append: true state: present loop: "{{ ops_users }}" loop_control: label: "{{ item.name }}" ``` `hosts: web`はインベントリのwebグループを指し、`become: true`で全タスクをroot権限で実行します。`vars`に書いたリストを`loop`に渡すと、タスクが要素の数だけ繰り返され、各回の要素を参照するための変数が`item`です。[公式のループガイド](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/playbooks%5Floops.html)によると`loop`は2.5で加わった書き方で、古い記事に多い`with_items`より推奨されています。`loop_control`の`label`は出力を名前だけに絞る表示用の設定で、機密を隠す機能ではない点に注意してください。 値が`{{`で始まるときは式全体を引用符で囲みます。[公式の変数ガイド](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/playbooks%5Fvariables.html)にある規則で、引用符を外すとYAMLの構文エラーになります。 ### ansible-playbookで流して2回目にchanged=0を確かめる流れ ``` # 構文だけを確認する（ホストには接続しない） ansible-playbook users.yml --syntax-check # 変更せずに結果を予測する ansible-playbook users.yml --check # 1台に絞って適用し、同じコマンドをもう一度流す ansible-playbook users.yml --limit web01 ansible-playbook users.yml --limit web01 # 残りの台へ適用する ansible-playbook users.yml ``` 実行の最後に出る`PLAY RECAP`で、1回目はユーザーを作った分だけ`changed=1`、2回目は`changed=0`になれば正しく書けています。2回目にも`changed`が出るなら、どこかでshellやcommandを使っているか、毎回変わる値を渡している状態です。設定ファイルの配布と再起動の連動（handlers）や、`--diff`での差分確認、変数の優先順位については[Ansible Playbookの書き方と実行手順：–checkでのdry-runとhandlers](https://www.issoh.co.jp/tech/details/18457/)で詳しく扱っています。 ### ansible-lintで入門者がつまずく書き方を流す前に洗い出す ``` pip install ansible-lint ansible-lint users.yml ``` [ansible-lint](https://github.com/ansible/ansible-lint)はPlaybookの書き方を点検するツールで、PyPIでは2026年10月13日公開の26.10.1が最新でした。モジュールを`user`のような短縮名で書いている箇所、`changed_when`の無いcommandタスク、`name`の無いタスクなど、入門段階で入り込みやすい書き方を流す前に指摘します。手元で通るようになったら、同じコマンドをCIにも入れておくと、レビューで書式を指摘する手間が減ります。 ## アドホックとPlaybookの使い分け：手順書に残す作業はPlaybookへ移す 使い方を覚えた後に迷うのは、どの作業をPlaybookにするかです。ここは条件で決めてしまいます。 ### アドホックで済ませてよい作業とPlaybookに書くべき作業の境界 | 作業の例 | 向く書き方 | 判断の理由 | | -------------- | -------- | ------------------ | | 全台の疎通・稼働時間の確認 | アドホック | 状態を変えず、記録も不要 | | 障害時の一斉再起動 | アドホック | 1回限りで、手順の再利用がない | | ユーザー追加・パッケージ導入 | Playbook | サーバー追加のたびに同じ手順を流す | | 設定ファイルの配布と再起動 | Playbook | 順番と変更時だけの再起動を保証したい | | 手順書に書いて引き継ぐ作業 | Playbook | 手順書そのものをコードにできる | 境界は「2回目があるか」と「他の人が流すか」の2つです。どちらかに当てはまる作業は、アドホックのコマンドを手順書に貼るのをやめ、Playbookとしてリポジトリに置きます。逆に、shellのコマンドを並べるだけになる作業はPlaybookにしても再実行で安全にならないため、Ansibleに載せるのを見送る判断が必要です。どの運用作業から自動化するかの費用対効果は[Ansibleによる運用自動化の進め方](https://www.issoh.co.jp/column/details/18092/)で試算式とあわせて整理しています。 ### 入門の次に読む順番：Playbook設計・Vault・Galaxy・Windows管理 入門の4段階を通したら、次は扱う対象に合わせて進みます。 - Playbookを本番で流す：[Playbookの書き方と実行手順](https://www.issoh.co.jp/tech/details/18457/)でhandlers・`--check --diff`・tagsを押さえる - パスワードやAPIキーを扱う：[Ansible Vaultの使い方](https://www.issoh.co.jp/tech/details/18471/)で機密変数を暗号化する - 他人の書いたロールを使う：[Ansible Galaxyの使い方](https://www.issoh.co.jp/tech/details/18469/)で`requirements.yml`による依存管理を覚える - Windowsサーバーも管理する：[AnsibleでWindowsを管理する手順](https://www.issoh.co.jp/tech/details/18467/)でWinRMとSSHの接続設定を行う - Terraformで作ったサーバーを管理する：[TerraformとAnsibleの連携手順](https://www.issoh.co.jp/tech/details/18475/)でTerraformの出力をインベントリに取り込む 最優先はVaultです。インベントリや変数ファイルにパスワードを平文で書いたままリポジトリへ入れると、後から履歴ごと消す作業が発生します。 ### 社内にAnsibleを根づかせる段階で外部の支援を入れる判断 1人の担当者が手元で流しているうちは、この記事の範囲で足ります。問題になるのは、書ける人が1人しかいないままPlaybookが増え、その人の異動で誰も直せなくなる場面です。外部に頼る場合は、Playbookを納品物として受け取るだけでなく、インベントリと変数の置き場所、lintとdry-runの手順まで含めて引き継げる形で残してもらうことが条件になります。一創では、既存の手順書の棚卸しからPlaybook化、CIでのansible-lint実行、社内メンバーへの引き継ぎまでを[DevOps・CI/CD導入支援](https://www.issoh.co.jp/service/system/devops/)として請け負っています。 ## よくある質問 Ansibleの使い方を学び始めた段階で多い質問に答えます。 ### WindowsのパソコンからAnsibleを使えますか？ ネイティブのWindowsは制御ノードとしてサポートされていません。Windowsのパソコンから使う場合は、WSLでUbuntuなどのLinuxを動かし、その中にansible-coreを入れます。一方、Windowsサーバーを管理対象として扱うことは可能です。その場合は制御ノードからWinRMかSSHで接続し、`ansible.windows`コレクションのモジュールを使います。 ### Host key verification failedで止まるときはどうしますか？ 接続先のホスト鍵が制御ノードの`known_hosts`に登録されていないか、サーバーの再構築で鍵が変わったことが原因です。一度手でSSH接続して鍵を確認するか、`ssh-keyscan`で登録します。`host_key_checking = False`で回避する方法も見かけますが、接続先のすり替えを検知できなくなるので、検証環境の使い捨ての設定以外では使わないでください。 ### パスワード認証のサーバーにも接続できますか？ 接続できます。`-k`（`--ask-pass`）を付けると実行時にSSHのパスワードを尋ねられます。ただし制御ノードに`sshpass`が必要で、台数が増えるほど入力の手間も増える仕組みです。入門の段階で`ssh-copy-id`を使って公開鍵認証に切り替えておくと、CIからの実行にもそのまま移れます。 ### ansible-coreのバージョンはいつ上げればよいですか？ ansible-coreは約半年ごとに新しい系列が出ます。2.21系は2026年5月に公開され、2027年11月にサポートが終わる予定です。系列を`2.21.*`のように固定してパッチ版だけを追い、次の系列へは検証環境でPlaybookを流して`changed=0`が変わらないことを確かめてから上げます。制御ノードのPythonの対応範囲も系列ごとに変わるので、同時に確認します。 ### 変数はインベントリとPlaybookのどちらに書けばよいですか？ サーバーや環境によって変わる値はインベントリ側（`group_vars`・`host_vars`）に、どの環境でも変わらない値はPlaybookの`vars`に書きます。同じ名前の変数を両方に書くと、優先順位の高いPlaybook側が勝つため、環境ごとの値が効かなくなる点に注意が必要です。実行時に`-e`で渡した値はどこに書いた値よりも優先されるため、一時的な上書き以外には使わないようにします。 ## 関連記事 - [Ansible Playbookの書き方と実行手順：–checkでのdry-runとhandlers【2.21系】](https://www.issoh.co.jp/tech/details/18457/)：本記事の次に読む、Playbookを本番で流すための書き方と段階実行。 - [Ansibleとは？エージェントレスの仕組みとメリット・デメリット、Red Hat AAPの制約](https://www.issoh.co.jp/tech/details/6533/)：Ansibleの仕組みと採用判断の前提。 - [Ansibleによる運用自動化の進め方：対象作業の選び方と費用対効果・失敗パターン](https://www.issoh.co.jp/column/details/18092/)：どの作業から自動化するかを決める判断材料。 - [構成管理とは？CMDB・IaC・ソフトウェア構成管理の違いと運用体制の作り方](https://www.issoh.co.jp/column/details/15291/)：Ansibleを運用体制の側から位置付けた記事。 - [構成管理ツールの比較と選び方｜Ansible・Terraform・Chef・Puppet・OpenTofuの選定条件](https://www.issoh.co.jp/column/details/15293/)：Ansible以外の選択肢との比較。 --- 出典: [Ansibleの使い方入門：インストールからアドホックコマンド・最初のPlaybookまで【2.21系】]()（株式会社一創）