ansible

Name: ansible
Author: iuliandita

github.com/iulianditaクラウド・DevOps1049 回インストール今日更新

ansible について

Playbookや再利用可能なロールから運用ワークフロー、コンプライアンス強化まで、Ansible自動化の作成、レビュー、設計を支援するスキルです。インフラチームやコーディングエージェント向けに、冪等性、検証、本番環境での安全な運用を重視します。

主な機能

01Playbook、ロール、コレクションの指針
02インベントリー、Vault、実行環境の運用
03コンプライアンス強化のパターン
04MoleculeテストとLintの手順
05冪等性と本番安全性のチェック
06CI/CD連携の指針

活用シーン

01プロビジョニング後のサーバー設定自動化
02コンプライアンス要件に沿ったホスト強化
03再利用可能なロールの作成とテスト
04本番実行前のPlaybookレビュー

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/iuliandita/skills --skill ansible

インストール後、Claude Code で/ansibleを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/

agent-hygiene.md

compliance.md

operations-and-execution.md

output-contract.md

playbook-patterns.md

production-checklist.md

roles-and-collections.md

vault-and-secrets.md

詳細

Ansible：本番環境の構成管理

単一のプレイブックから、複数階層にわたるコンプライアンス強化済みのインフラ管理まで、Ansible の自動化を作成、レビュー、設計します。目標は、ローカルでも CI/CD でも同じように動作する、冪等で監査可能、保守しやすい自動化です。

対象バージョン（2026 年 10 月）：

ansible-core 2.21.4（現行の安定版、コントローラーは Python 3.12 以降）；バージョンを固定する前に、サポートマトリックスで管理対象ノードの Python サポートとブランチの EOL を確認してください
ansible（コミュニティパッケージ）14.4.0（ansible-core 2.21 に依存）
molecule 26.9.0、ansible-lint 26.9.0、ansible-navigator 26.9.0（CalVer）
ansible-builder 3.1.1（EE 定義 v3）
AWX 24.6.1（正式リリースは 2024 年 7 月が最後；大規模なリファクタリングのため、上流の AWX リリースは一時停止中ですが、devel ブランチは有効です。ansible/awx を追跡してください；K8s デプロイ向けの awx-operator ~2.19.x は引き続き提供されています）。特定のバージョンやインストール方法を推奨する前に、現在の AWX/AAP のリリース状況を確認してください。
AAP 2.7（現行ストリーム）；デプロイ前に、ベンダーのライフサイクルに関するドキュメントで、サポートされているインストール方法とパッチビルドを確認してください

このスキルは、状況に応じて次の 4 つの領域を扱います：

プレイブック - タスク、ハンドラー、変数、条件、ループ、ブロック、テンプレート、Jinja2
ロールとコレクション - ロールの構成、コレクションのパッケージ化、Galaxy/Automation Hub、Molecule によるテスト
運用 - インベントリー、実行環境、CI/CD 連携、Vault、ansible-navigator
コンプライアンス - PCI-DSS 4.0 のハードニング、CIS ベンチマーク、Ansible-Lockdown、監査ログ

使用する場面

Ansible のプレイブック、ロール、コレクションを作成またはレビューする場合
Terraform でプロビジョニングしたサーバーを構成する場合（day-2 運用）
OS のハードニング（CIS ベンチマーク、STIG、PCI-DSS の構成要件）
パッケージ、サービス、ユーザー、ファイアウォールルール、cron ジョブ、構成ファイルを管理する場合
Molecule または tox-ansible で自動化をテストする場合
シークレット管理のために Ansible Vault を設定する場合
インベントリー構成（静的、動的、複数環境）を設計する場合
一貫性のある実行環境を構築する場合
Ansible を CI/CD パイプライン（GitLab CI、GitHub Actions）に統合する場合
AI 生成のプレイブックが正確で、慣用的なパターンに従っているかレビューする場合

使用しない場面

インフラのプロビジョニング（VPC、RDS、EC2、クラウドリソース） - terraform を使用してください
Kubernetes マニフェスト、Helm チャート、クラスターアーキテクチャ - kubernetes を使用してください
Dockerfile、Compose スタック、コンテナーイメージの最適化 - docker を使用してください
CI/CD パイプラインの設計（ステージ、ランナー、キャッシュ） - ci-cd を使用してください
アプリケーションコードのセキュリティ監査（SAST、依存関係スキャン） - security-audit を使用してください
シェルスクリプトまたは単発のコマンド - shell-scripting を使用してください
ファイアウォールアプライアンスの管理（OPNsense/pfSense） - opnsense-pfsense を使用してください
単一マシンの OS レベルの管理に関する質問（自動化の文脈を伴わないパッケージ設定、ユーザー管理、サービス構成） - 適切なディストリビューション用スキルを使用してください：debian-ubuntu、rhel-fedora、kali-linux、または arch-linux

AI セルフチェック

AI ツールは、Ansible で同じミスを繰り返し発生させます。生成したプレイブック、ロール、またはタスクを返す前に、必ずこのリストで確認してください。

パフォーマンス

大規模なフリートでは、対象を絞ったインベントリ、タグ、--limit を使用してください。単一のロールを反復調整している間は、フリート全体での実行を避けてください。
必要なファクトのみを収集し、低速または高レイテンシーの環境で対応している場合はファクトをキャッシュしてください。
Ansible が処理をまとめ、安全に差分を表示し、冪等性を報告できるよう、シェルのループよりネイティブモジュールを優先してください。

ベストプラクティス

本番環境の自動化では、requirements.yml でコレクションのバージョンを固定してください。
破壊的なプレイブックは、まず --check --diff を付けて実行し、本番ホストには人間が確認した --limit を必須にしてください。
Vault の値を差分、ログ、コールバック出力、生成された例に含めないでください。

ワークフロー

このチェックリストをコピーし、進捗を管理してください。

ステップ 1：ドメインを特定
ステップ 2：要件を収集（対象 OS、権限、接続、シークレット、インベントリ）
ステップ 3：プレイブック、ロール、または設定を作成
ステップ 4：構文チェック、リンター、--check --diff がすべて問題なし（失敗した場合は修正してステップ 3 に戻る）
本番環境チェックリストと AI セルフチェックに合格

ステップ 1：ドメインを特定する

依頼内容に基づいて判断します。

「X を設定するプレイブックを作成」 -> プレイブック
「X 用の再利用可能なロールを作成」 -> ロールとコレクション
「インベントリを設定」／「CI/CD」／「Vault」／「EE」 -> 運用
「このサーバーを強化」／「CIS ベンチマーク」／「PCI 準拠」 -> コンプライアンス
「このプレイブック／ロールをレビュー」 -> 本番環境チェックリスト + 重要ルール + AI セルフチェックを適用

実際のタスクでは、複数のドメインが組み合わさることがほとんどです。まずプレイブックから始め、再利用の必要性が明確になったらロールに切り出し、最後に運用へ組み込みます。

ステップ 2：要件を整理する

YAML を書く前に、次の項目を確認します。

対象 OS：RHEL/CentOS、Ubuntu/Debian、Alpine、Windows — モジュールの選択に影響します
対象ホストの Python バージョン：Target versions の下にあるサポートマトリックスで、ピン留めされた ansible-core の管理対象ノードのサポートを確認します
権限昇格：become の方法（sudo、su、doas、Windows の場合は runas）
接続：SSH（デフォルト）、WinRM（Windows）、ローカル、network_cli（ネットワークデバイス）
冪等性：すべてのタスクを複数回実行しても安全な状態にします
シークレット：Ansible Vault、HashiCorp Vault、CI/CD のシークレット、環境変数
テスト：Molecule シナリオ？ tox-ansible マトリックス？統合テスト？
コンプライアンス：PCI-DSS の適用範囲？ CIS ベンチマークのレベル？ STIG プロファイル？
インベントリー：静的、動的（クラウド）、またはハイブリッド？複数の環境？
実行：ansible-playbook（直接）、ansible-navigator（EE）、AWX/AAP（プラットフォーム）？

ステップ 3：構築する

以下のドメイン固有のセクションに従います。完了前に、必ずステップ 4、references/production-checklist.md の本番環境チェックリスト、AI によるセルフチェックを実行してください。

ステップ 4：検証する

構文チェック、lint、--check --diff の順に実行します。失敗した場合は、報告された問題を修正してステップ 3 に戻り、構文チェックから再実行します。3 つすべてに問題がない場合のみ完了とします。

# Syntax check (fast, no connection needed)
ansible-playbook playbook.yml --syntax-check

# Lint (use production profile for strictest checks)
if command -v ansible-lint >/dev/null; then
  ansible-lint --profile production playbook.yml
else
  echo "ansible-lint not installed: lint NOT run; report it as unverified"
fi

# Dry run (needs inventory + connectivity)
ansible-playbook playbook.yml --check --diff

ロールの場合のみ、シナリオが存在するときは Molecule を追加します。

if command -v molecule >/dev/null; then
  molecule test                        # full cycle: create, converge, verify, destroy
  # molecule converge                  # just apply (dev loop)
  # molecule verify                    # run verification only
else
  echo "molecule not installed: role tests NOT run; report them as unverified"
fi

チェック以外の実行では変更が適用されます。--limit を指定して実行し、本番ホストを対象にする前に人間の承認を得てください。

# Navigator (EE-based execution)
ansible-navigator run playbook.yml --mode stdout --eei <ee-image> --limit <hosts>

Playbook

サービス、パッケージ、ファイル、テンプレート、ユーザー、ファイアウォール、cron、systemd、OpenRC のタスク例や Jinja2 パターンなど、コピーして使用できる例の全編については、references/playbook-patterns.md をお読みください。

構成

---
- name: Configure web servers
  hosts: webservers
  become: true
  gather_facts: true

  vars:
    app_port: 8080
    app_user: appuser

  pre_tasks:
    - name: Update apt cache
      ansible.builtin.apt:
        update_cache: true
        cache_valid_time: 3600
      when: ansible_os_family == "Debian"

  roles:
    - role: common
      tags: [common]
    - role: nginx
      tags: [nginx]

  tasks:
    - name: Ensure application directory exists
      ansible.builtin.file:
        path: /opt/app
        state: directory
        owner: "{{ app_user }}"
        mode: "0755"

  handlers:
    - name: Restart nginx
      ansible.builtin.systemd:
        name: nginx
        state: restarted
        daemon_reload: true

主なパターン

変数の優先順位（22段階。重要なものを優先度の低い順に示します）：

ロールのデフォルト値（defaults/main.yml） - 最も弱く、上書きされることを想定しています
インベントリー変数（group_vars/、host_vars/）
Play の変数
タスクの変数
追加変数（-e） - 最も強く、すべてを上書きします

経験則：デフォルト値はロールの defaults/ に、環境固有の値は group_vars/ に、一時的な上書きは host_vars/ に、緊急時の上書きは -e で指定します。

ハンドラー：変更されたタスクから通知された場合にのみ実行され、Play の最後に一度だけ実行されます（すぐには実行されません）。注意点：

ハンドラー名は、インクルードされたすべてのロールを通じて一意である必要があります
ハンドラーに到達する前に Play が失敗すると、ハンドラーは実行されません（必要に応じて meta: flush_handlers を使用します）
ハンドラーは通知された順序ではなく、定義された順序で実行されます
同じハンドラーへの通知が複数あっても、実行は1回だけです

ブロック：エラー処理とロールバックには block/rescue/always を使用します。デプロイとロールバックの完全な例は playbook-patterns.md を参照してください。ignore_errors: true よりも block/rescue を優先してください。

ループ：以前の with_* ルックアップ構文よりも loop: を優先してください。出力を見やすくするには loop_control.label を使用します。

条件付き実行：when: ansible_os_family == "Debian" などを指定します。複数の OS に対応するロールでは、条件式または OS ファミリーごとの include_tasks を使用します。Alpine/OpenRC のパターンについては playbook-patterns.md を参照してください。

サービス管理：ディストリビューションをまたいで使うロールでは、汎用の ansible.builtin.service を使用します。ansible_service_mgr により、systemd、OpenRC、SysV が自動検出されます。systemd 固有の機能（daemon_reload、scope）が必要な場合に限り、ansible.builtin.systemd を使用してください。OpenRC のパターンについては playbook-patterns.md を参照してください。

シェルプロファイルの変更：手動でのシェルプロファイルの調整を Ansible に置き換える場合は、ansible.builtin.blockinfile、ロール名を接頭辞にしたデフォルト値、専用のロールアウト用 Playbook を備えた、再利用可能な専用ロールを使用してください。references/operations-and-execution.md を参照してください。自動化、scp、rsync、リモート SSH コマンドを妨げないよう、ブロックでは SSH 接続であること、すでに tmux 内にいないこと、標準入力と標準出力が実際の TTY であること、および TERM が使用可能であることを条件にする必要があります。

結果の登録：register: result_var はタスクの出力を保存します。when: result_var.stat.exists、result_var.rc == 0 などを使用します。パターンについては playbook-patterns.md を参照してください。

Vault クイックリファレンス

# Encrypt a single variable (inline in YAML)
ansible-vault encrypt_string --prompt --name 'db_password'

# Encrypt an entire file
ansible-vault encrypt group_vars/production/secrets.yml

# Edit encrypted file
ansible-vault edit group_vars/production/secrets.yml

# Run playbook with vault
ansible-playbook site.yml --ask-vault-pass
# Or with a password file (for CI/CD)
ansible-playbook site.yml --vault-password-file ~/.vault_pass

Vault のパスワードをリポジトリと一緒に平文で保存しないでください。--ask-vault-pass、リポジトリ外のパスワードファイル、またはシークレットマネージャーから取得する Vault スクリプトを使用します。

書いてはいけないもの

command: apt-get install -y nginx（ansible.builtin.apt を使用してください）
shell: systemctl restart nginx（ansible.builtin.systemd を使用してください）
shell: useradd deploy（ansible.builtin.user を使用してください）
機密ファイルに mode: を指定せずに copy を使用すること（デフォルトでは umask が適用され、予測できません）
ソースファイルの拡張子が .j2 でない template の使用
理由を説明するコメントなしで ignore_errors: true を使用すること（代わりに block/rescue を使用してください）
with_items を loop に機械的に書き換えること：どちらもサポートされています。単純なリストには loop を優先し、必要な場合は flatten(1) で1階層のフラット化を維持してください
引用符なしの {{ var }}（YAML では辞書の開始として解釈されます）
fact を使わないのに gather_facts: true を指定すること（ホストごとに5～15秒の無駄になります）
name: のないタスク（構文上は有効ですが、出力が読みにくくなります）
本番の Playbook で state: latest を指定すること（結果が一定にならないため、バージョンを固定してください）

ロールとコレクション

ロールの詳細な構成、コレクションの構造、Galaxy のパターン、Molecule のテストワークフローについては references/roles-and-collections.md を読んでください。

1つのロールにつき、責任を1つにします。
ユーザーが調整できる値は vars/main.yml ではなく defaults/main.yml に記述します。
すべての箇所で FQCN を使用します。
変数の衝突を避けるため、ロール名を接頭辞に付けます。
シナリオがあるロールでは、Molecule の冪等性チェックを任意の仕上げではなく、必須として扱います。

運用

インベントリの構成、ansible.cfg、実行環境、CI/CD 統合、ansible-navigator については、references/operations-and-execution.md を参照してください。
インベントリは環境ごとに分けてください。
既存のインベントリを変更する場合は、従来の INI 形式より YAML 形式のインベントリを優先してください。
pipelining = True、ファクトキャッシュ、コールバック設定を、標準的な本番環境のデフォルトとして扱ってください。
再現性のあるローカル実行と CI 実行には、実行環境を使用してください。
Vault の使用方法については references/vault-and-secrets.md に記載してください。シークレットは暗号化し、接頭辞を付け、no_log: true でラップしてください。

コンプライアンス

Ansible コントロールへの PCI-DSS 4.0 要件の完全な対応付け、CIS ベンチマークの自動化、ハードニングパターンについては、references/compliance.md を参照してください。

Ansible が担うのは OS とサービスの適用であり、アプリケーションレベルのセキュリティレビューではありません。
CIS と PCI のコントロールはロールやテンプレートへの入力として扱い、デフォルトとして無条件に適用しないでください。
ベンチマークに基づくハードニングは、広範囲に展開する前にステージング環境でテストしてください。
コールバックプラグイン、AWX/AAP のアクティビティストリーム、または CI アーティファクトを使用して、監査証跡を保持してください。

非推奨と破壊的変更

ansible-core 2.20

削除済みの機能：

smart トランスポート値。ssh または paramiko を明示的に選択してください。
Galaxy v2 API のサポート。Galaxy サーバーは v3 をサポートする必要があります。
PARAMIKO_HOST_KEY_AUTO_ADD と PARAMIKO_LOOK_FOR_KEYS の設定キー
encrypt ユーティリティの passlib_or_crypt API

非推奨（2.24 で削除予定）：

INJECT_FACTS_AS_VARS のデフォルトは True ですが、False に変更されます。ansible_hostname ではなく ansible_facts['hostname'] を使ってファクトにアクセスしてください。
ansible.module_utils._text のインポート（to_bytes、to_native、to_text）。代わりに ansible.module_utils.common.text.converters を使用してください。
内部変数キャッシュの vars

ansible-core 2.19（以前のバージョン）

データタグ付けが全面的に見直され、エラー報告が改善されましたが、一部のループテンプレートが動作しなくなりました（GitHub issue #85605）。アップグレード後にループで型エラーが発生する場合は、ネイティブな Jinja2 の型処理との競合を確認してください。

CalVer への移行

Ansible DevTools の全プロジェクト（molecule、ansible-lint、ansible-navigator、tox-ansible）は、2024 年に SemVer から CalVer（YY.MM.MICRO）へ移行しました。バージョン番号の飛躍（例：ansible-lint 6.x から 26.x）に惑わされないでください。

セキュリティに関する考慮事項

把握しておくべき CVE

CVE	深刻度	説明	緩和策
CVE-2024-11079	低	Hostvars が安全でないコンテンツに対する保護を回避し、テンプレート化されたコンテンツ経由で任意のコードが実行される可能性があります	ansible-core >= 2.16.14、2.17.7、または 2.18.1 にアップグレードしてください
CVE-2024-8775	中	`no_log` がない場合、`include_vars` 経由で Vault 暗号化変数が平文で公開されます	シークレットを扱うすべてのタスクに `no_log: true` を追加してください
CVE-2025-14010	中	community.general が詳細出力で Keycloak の認証情報を公開します	community.general >= 12.0.0（または 11.4.1 / 10.7.6）、すなわち ansible パッケージ >= 12.2.0 にアップグレードしてください
CVE-2025-49520	高	EDA で認証済みの Git URL 引数がインジェクションされ、コマンドが実行される可能性があります	AAP/EDA にパッチを適用してください
CVE-2025-49521	高	EDA で Git ブランチ/refspec 経由のテンプレートインジェクションが発生し、コマンドが実行される可能性があります	AAP/EDA にパッチを適用してください

2026-09-10 確認：CVE-2026-16493 は重大度の高いコレクションインストール引数インジェクションです。ロールインストールの修正では CVE-2026-11332 は解消されましたが、この問題は対象外でした。requirements.yml の Git ソースを確認し、信頼できる Galaxy/Automation Hub ソースとベンダーの修正済みビルドを使用してください。取得したベンダーの記録では、上流の修正済みバージョン範囲は確認できません。そのため、対象のバージョンを固定しただけで修正済みと判断しないでください。

サプライチェーン

Galaxy にはパッケージ署名やハッシュ検証がありません。2025 年の学術研究では、482 個の Galaxy リポジトリにわたって 45 件の脆弱な依存関係チェーンが確認され、コードの 38〜54％の重複により脆弱性が伝播していました。
requirements.yml でコレクションのバージョンを固定してください。本番環境で重要なコレクションには、Galaxy よりも Automation Hub（Red Hat 認定）を優先してください。
CI/CD では GitHub Actions を可変タグではなくコミット SHA に固定してください。
他のコンテナーイメージと同様に、EE イメージの CVE をスキャンしてください。

AI 生成プレイブックのリスク

AI ツールはモジュール名やパラメーターを誤って生成することがあります。対象のコレクションバージョンに各モジュールが存在することを確認してください。
AI は、シークレットを扱うタスクに no_log: true を追加しないことがよくあります。
AI は、対応するモジュールが存在する場合でも、冪等でない command／shell タスクを生成します。
AI は FQCN ではなく、モジュールの単純名を使用します。
スロップスクワッティング：AI は、存在しない Galaxy ロールやコレクションを提案する場合があります。requirements.yml に追加する前に Galaxy で確認してください。

参照ファイル

references/playbook-patterns.md - 一般的な自動化作業向けのプレイブックおよびタスクのパターン
references/production-checklist.md - プレイブック、ロール、運用、PCI-DSS のチェックリスト。ビルドやレビューを完了する前に実行してください
references/roles-and-collections.md - ロールの構成、コレクションの構造、Galaxy のパターン、Molecule のワークフロー
references/operations-and-execution.md - インベントリーの構成、ansible.cfg、実行環境、CI/CD 統合、navigator の使用方法
references/vault-and-secrets.md - Vault の使用方法、シークレットの取り扱い、外部シークレットマネージャーとの統合
references/compliance.md - PCI-DSS および CIS を踏まえた強化のガイダンス

出力要件

要件の全文については references/output-contract.md を参照してください。

スキル名： ANSIBLE
成果物の分類： audits
モード： 条件付き。既存のリポジトリ内容の分析、レビュー、監査、改善のために呼び出された場合は、references/output-contract.md のレポートの分量とエビデンスに関する規則を適用し、成果物を docs/local/audits/ansible/<YYYY-MM-DD>-<slug>.md に書き込んでください。質問への回答、概念の解説、新しい成果物の作成、コンテンツの生成のために呼び出された場合は、要件にとらわれず自由に回答してください。
重大度の尺度： P0 | P1 | P2 | P3 | info（共通要件を参照。監査／レビューのモードでのみ使用）

ルール

これらは絶対に守る必要があります。違反はバグです。

デフォルトで冪等にします。 すべてのタスクは、複数回実行しても安全でなければなりません。command／shell タスクには、creates／removes または changed_when を指定する必要があります。
シークレットを扱うタスクには no_log: true を指定します。 パスワード、トークン、API キー、または機密データを扱うすべてのタスクが対象です。CVE-2024-8775は、これを忘れた場合の代償を示しました。
シークレットには Vault を使います。 group_vars に平文で記述したり、インベントリに ansible_ssh_pass を記述したり、Playbook で環境変数を使ったりしてはいけません。
Molecule でテストします。 共有ロールや複雑なロールには、収束、冪等性チェック、およびロールの観測可能な結果の検証を含む Molecule シナリオを用意します。すべてのタスクを検証する必要はありません。
コレクションのバージョンを固定します。 requirements.yml と EE の定義で固定してください。バージョンが固定されていないコレクションは、サプライチェーンのリスクになります。
ansible-lint をクリーンな状態に保ちます。 本番用プロファイルを使用し、CI で実行します。変更のたびに実行してください。
環境ごとにインベントリを分けます。 本番、ステージング、開発用に分けてください。環境を選択するために、単一のインベントリと --limit を使ってはいけません。
適用前に --check --diff を実行します。 変更内容を確認してから適用してください。特に CI/CD では必ず確認してください。

Markdown 対応

ログインしてコメント

基本情報

作者: iuliandita
リポジトリ: iuliandita/skills
カテゴリ: クラウド・DevOps
インストール数: 49
GitHub スター: 10

問題を報告