📚 Ansibleが理解できない理由はLinuxにあった【Ansible編】第0回：なぜShellの知識がないとAnsibleは壊れるのか
⓪ なぜShellの知識がないとAnsibleは壊れるのか
① なぜshellモジュールは危険なのか
② なぜmoduleを使うと安全になるのか
③ なぜ毎回changedになるのか
④ なぜ条件分岐が壊れるのか（Ansible編）
⑤ なぜ変数が意図通りに扱えないのか
⑥ なぜタスクの順序で壊れるのか
⑦ なぜエラー制御が破綻するのか
⑧ なぜ非同期・待機で失敗するのか
⑨ なぜPlaybookが読めないのか
⑩ なぜAnsibleを正しく設計できるようになるのか
🗺️ 初めての方・シリーズの全体像を知りたい方はこちら
本記事は、OSの仕組みからAnsible設計までを繋ぐ連載シリーズの一部です。
「どこから読み始めればいいか」あるいは、「OS/Shell/Ansible編の関係性」 について把握されたい場合は、以下の統合ガイドで整理しています。
📑 【Ansible編】全体のまとめはこちら
→ Ansibleが理解できない理由はLinuxにあった【Ansible編】まとめ ※近日公開予定
📑 連載の移動
前の記事：【Shell編】第11回 ｜ 次の記事：【Ansible編】第1回 ※近日公開予定
📋 目次
- はじめに（この記事のスタンス）
- 逆引き辞典との連動
- Ansibleは何をしているのか（構造の再確認）
- なぜShellを理解しないと構造が崩れるのか
- 「shellを使うな」の本当の意味
- moduleとは何をしているのか
- Shell編との接続
- まとめ
- 次回予告
- 連載一覧：Ansibleが理解できない理由はLinuxにあった【Ansible編】
※本記事の位置とシリーズ全体の関係を先に確認します。
シリーズ全体構造（学習 × 問題解決）
本シリーズは
「理解（各記事）」と「問題解決（逆引き辞典）」を組み合わせて
スキルを身につける構成になっています。
この図は、どこから学び、どこに進めばよいかを示した“ロードマップ”です。
📍 現在の位置
※現在はこの図の「Ansible編の第0回」になります。
1. はじめに（この記事のスタンス）
これまでの Shell編（第1回〜第11回） では、標準入出力、環境変数、終了ステータス、変数展開といったLinuxのコマンド実行の仕組みを順に見てきました。
Ansibleを使い始めると、「なぜか変数が空になる」「スペースを含むパスで処理が崩れる」といった問題に直面することがあります。
これらをAnsible特有の癖と片付けてしまうのは誤りです。
Ansibleが実行に失敗する理由の大部分は、その基盤である「Shellの仕様」にあります。
本記事では、AnsibleがShellをSSH越しに叩くラッパーに過ぎないことを、実行プロセスの観点から整理します。
2. 逆引き辞典との連動
「設計上の原因」を特定したい場合は、以下の逆引き辞典を活用してください。
※随時公開予定
Ansibleが理解できない理由はLinuxにあった【Ansible編】：トラブル逆引き辞典（設計パターン版）
- まず「逆引き辞典」で該当ステップを特定する
- 次に「本編（各連載記事）」で仕組みを理解する
3. Ansibleは何をしているのか（構造の再確認）
Ansibleの動作をブラックボックスとして捉えず、実行プロセスを把握する必要があります。
Ansibleがリモートホストに命令を出す際、その実体は「Shellを介したコマンド実行」です。
実行の全体像
[制御ノード: Ansible]
↓
( SSHプロトコル )
↓
[ターゲットノード: SSHd]
↓
[ リモートShell ]
↓
[ Linuxコマンド実行 ]
さらに、Ansible内で定義した変数が実行されるまでの内部プロセスを分解すると、Shell編 で学んだ各レイヤーが順に出てきます
内部処理フロー（shellモジュール使用時）
1. [Jinja2展開] : Ansible側で {{ var }} を文字列に置換
↓
2. [コマンド文字列生成] : 実行すべき最終的な一行の文字列を組み立て
↓
3. [SSH転送] : 文字列をリモートへ送信
↓
4. [Shell評価] : リモートShellがクォート解釈や引数分割を行う
↓
5. [プロセス実行] : 実際のバイナリが実行される
↓
6. [結果返却] : stdout / stderr / rc（exit code）が確定
↓
7. [Ansible判定] : exit code を見て failed / changed を決定
Ansibleは、組み立てた文字列をリモートのShellに渡し、その戻り値を受け取って判定しているツールに過ぎません。
このプロセスの一部でもShellの解釈ルール（IFSやエスケープ）と
食い違いが生じれば、コマンドは意図通りに動きません。
4. なぜShellを理解しないと構造が崩れるのか
Ansibleで起きるトラブルは一見バラバラに見えますが、たいていはShellのどの仕様に引っかかっているかで説明できます。
つまり 「現象 → Shellのどのルールか」 に置き換えられるかどうかが、
デバッグを速くするかどうかの分かれ目です。
| 現象 | 原因（Shellの仕様） |
|---|---|
| 変数が空として扱われる | 環境変数（Shell編 第9回）：Jinja2展開ではなく、Shell変数を参照している |
| スペースでパスが壊れる | 単語分割（Shell編 第10回）：スペースが引数の区切り（IFS）として解釈されている |
| command not found | 環境差分（Shell編 第5回）：非対話シェルによるPATHの未適用 |
| 条件分岐（when）が失敗する |
終了ステータス（Shell編 第6回）：意図しないrcが返っている、またはパイプでエラーが消えている |
これらはAnsibleの設定を見直しても解決しません。
「Shellがその文字列をどう解釈したか」 という視点が必要です。
5. 「shellを使うな」の本当の意味
Ansibleの設計指針として「shellモジュールを極力使うな」と言われるのは、使う側がShellの解釈ルールをすべて把握・制御しなければならないからです。
shellモジュールを使うということは、クォート解釈や引数分割といった
Shellの再評価プロセスを丸ごと自分で面倒を見るということです。
Shellは自由度が高い分、環境差分や特殊文字の混入に弱い側面があります。
その制御が一箇所でも崩れると、自動化全体が意図通りに動かなくなります。
だからこそ、shellモジュールの使用は必要な場面に限るべきとされています。
6. moduleとは何をしているのか
一方、Ansibleの各種module（copy, file, yum等）を使うと、
Shellの文字列解釈を経由せずに済みます。
moduleはターゲットホストにPythonコードを送り込み、状態を直接操作します。これにより Shell編 で見てきた以下の問題を避けられます。
- 引数が確実に届く: Shellの単語分割に左右されない
- クォート崩壊が起きない: エスケープ処理をmodule内部で完結させる
- 環境差分の影響を受けにくい: PATHの設定に依存せず操作できる
-
終了ステータスを気にしなくていい: 単なる
rc判定ではなく「意図した状態になったか（changed）」で判定する
補足：Ansible公式ドキュメントに基づく構造的根拠
本記事でmoduleを推奨した理由は、Ansible公式ドキュメントの
アーキテクチャ説明および設計思想に基づいています。
1. moduleは「プログラムを送り込んでいる」
Ansibleはコマンド文字列をリモートに送るのではなく、モジュール本体をリモートホストに転送して実行します。
多くの場合、moduleはPythonコードとしてパッケージ化（Ansiballz）され、ターゲット上で展開・実行されます。そのため、Shellによるクォート解釈や引数分割の影響を受けません。
出典：
2. 「Shellの介在」をバイパスする仕組み
専用moduleを使うと、リモートShellによる以下の処理を経由しません。
- 引数の解釈（単語分割）
- クォートの再評価
Ansible公式でも、shellやcommandより専用モジュールの使用を推奨しています。
shellはShellによる文字列解釈が入り、commandはShellを介さないもののパイプ・リダイレクト・ワイルドカードが使えません。
専用モジュールはこれらの制約を気にせず使えます。
出典：
3. 「結果」ではなく「状態（State）」を操作する
冪等性（Idempotency）とは、同じ操作を繰り返しても結果が変わらない性質のことです。
Ansibleでは「どう実行するか」ではなく「どんな状態にしたいか」を書きます。
moduleは実行時に現在の状態を確認し、必要な変更だけを加えます。
すでに目的の状態になっていれば、何もしません。出典：
※以下の公式定義に基づく筆者の解釈を含みます
7. Shell編との接続
Shell編では、Ansibleで起きるトラブルの原因がShellのどの仕様に対応するかを見てきました。
Ansible編では、その知識をベースに
「どう書けば意図通りに動くか」「再実行しても同じ結果になるか（冪等性）」
という書き方の話に移ります。
- Shell編：原因の理解（エラーがShellのどの仕様から来ているかを把握する）
- Ansible編：設計の実践（moduleを正しく選び、崩れにくいPlaybookを書く）
ShellのクセをふまえてAnsibleをどう使うか。
その具体的な書き方を次回から整理していきます。
8. まとめ
AnsibleはShellをSSH越しに叩くラッパーです。
Ansibleから出てくるエラーの多くは、リモートホスト上のShellが意図しない動作をした結果です。
- AnsibleはShellのラッパーである
- エラーの原因はShellの実行プロセスにある
- moduleはShellの文字列解釈を経由せず、状態を直接操作する仕組みである
この仕組みを把握しているかどうかで、トラブル発生時の対応速度はかなり変わります。
9. 次回予告
第0回では、AnsibleがShellのラッパーであること、そしてエラーの多くがShellの実行プロセスに起因することを整理しました。
次に取り上げるのはshellモジュールです。
実務でよく使われる一方、クォート解釈や単語分割といったShellの仕様がそのまま影響するため、意図しない動作を起こしやすいモジュールです。
Shell編 で見てきた各仕様が、実際のAnsible実行でどう問題になるか。
その具体的なケースを次回で扱います。
次回：【Ansible編】第1回：なぜshellモジュールは危険なのか ※近日公開予定
📑 連載の移動
前の記事：【Shell編】第11回 ｜ 次の記事：【Ansible編】第1回 ※近日公開予定
📑 【Ansible編】全体のまとめはこちら
→ Ansibleが理解できない理由はLinuxにあった【Ansible編】まとめ ※近日公開予定
🗺️ 初めての方・シリーズの全体像を知りたい方はこちら
本記事は、OSの仕組みからAnsible設計までを繋ぐ連載シリーズの一部です。
「どこから読み始めればいいか」あるいは、「OS/Shell/Ansible編の関係性」 について把握されたい場合は、以下の統合ガイドで整理しています。
📚10. 連載一覧：Ansibleが理解できない理由はLinuxにあった【Ansible編】
| 回数とタイトル | 内容（概要） |
|---|---|
| 【Ansible編】第0回：なぜShellの知識がないとAnsibleは壊れるのか | AnsibleはShellのラッパーとして動作している。Shell編で学んだ構造（Ansible → SSH → Shell → Linux）を再確認し、「なぜmoduleを使うべきなのか」の前提を整理する。 |
| 【Ansible編】第1回：なぜshellモジュールは危険なのか | shellモジュールはShellの仕様（分割・展開・環境）に依存するため壊れやすい。commandとの違いを理解し、「どこまでShellを許容すべきか」を判断できるようになる。 |
| 【Ansible編】第2回：なぜmoduleを使うと安全になるのか | file / copy / lineinfile などのmoduleは状態管理を前提としている。「結果」ではなく「状態」を扱うことで、Shell依存を排除し安全な構成を実現する。 |
| 【Ansible編】第3回：なぜ毎回changedになるのか | shellモジュールは状態を判定できないため、常にchangedになる。changed_whenを使った制御と冪等性（idempotency）の設計を理解する。 |
| 【Ansible編】第4回：なぜ条件分岐が壊れるのか（Ansible編） | when条件が意図通りに動かない原因は、rc / stdout / stderrの扱いにある。Shell編で学んだ終了ステータスと組み合わせ、正しい条件分岐を設計する。 |
| 【Ansible編】第5回：なぜ変数が意図通りに扱えないのか | vars / host_vars / group_vars のスコープや、registerの扱いを誤ると値が壊れる。Ansible内での変数管理と評価タイミングを整理する。 |
| 【Ansible編】第6回：なぜタスクの順序で壊れるのか | Ansibleのタスクはそれぞれ独立したプロセスとして実行される。chdir / environment の制御と、「前の結果に依存する設計」の危険性を理解する。 |
| 【Ansible編】第7回：なぜエラー制御が破綻するのか | ignore_errors や failed_when の使い方を誤るとエラーが隠蔽または暴発する。Shellのrcと連動させた正しいエラー制御を設計する。 |
| 【Ansible編】第8回：なぜ非同期・待機で失敗するのか | サービス起動や外部依存処理はタイミング問題を引き起こす。async / poll / wait_for / retries を使い、安定した実行制御を実現する。 |
| 【Ansible編】第9回：なぜPlaybookが読めないのか | role構成やタスク分割が不適切だと可読性が崩壊する。実務で保守できるPlaybook設計と構造化の原則を理解する。 |
| 【Ansible編】第10回：なぜAnsibleを正しく設計できるようになるのか | これまでの知識を統合し、Shell編と接続することで「壊れない設計」ができるようになる。Ansibleを実務で使いこなすための設計思想を完成させる。 |