Ansible Execution Environments（EE）設計入門｜ansible-builderで実行環境をコンテナ化してチーム統一を実現する方法

この記事の監修：宮崎智広（Linux実務・教育歴20年以上・受講者3,100名超）

ＨＯＭＥ＞ Linux技術リナックスマスター.JP（Linuxマスター.JP）＞ Ansible ＞ Ansible Execution Environments（EE）設計入門｜ansible-builderで実行環境をコンテナ化してチーム統一を実現する方法

「自分のPCでは動くのに、同僚のPCでは失敗する」
Ansibleを使い始めたチームが最初にぶつかる壁の多くは、実行環境のばらつきから来ます。コレクションのバージョン、Pythonライブラリのバージョン、Ansibleのマイナーバージョン……。個人の環境に依存した自動化は、チームに展開した瞬間に崩れます。

この問題を根本から解決するのが、Red Hatが推進する Ansible Execution Environments（EE） です。Playbookの実行に必要なすべての依存物（Ansible本体・コレクション・Pythonライブラリ・システムパッケージ）をコンテナイメージにパッケージし、「どこで実行しても同じ結果が出る」を実現する仕組みです。

この記事では、EEの設計思想とビルドツール ansible-builder の実践的な使い方、さらに ansible-navigator によるPlaybook実行の流れを解説します。Ansible CLIは使えるが実行環境の統一に悩んでいるエンジニアが掴んでおくべき設計思想を整理します。

この記事のポイント

・AnsibleのEEはPlaybook実行環境をOCIコンテナに封入してチームで統一する仕組み
・ansible-builderでEEイメージを作成し、ansible-navigatorで実行するのが基本フロー
・execution-environment.ymlにベースイメージ・コレクション・Pythonパッケージを定義する
・AWX・AAPへのEE登録でCI/CD全体の実行環境を一元管理できる

「このままじゃマズい」と感じていませんか？

参考書を開く気力もない、同年代に取り残される不安——
でも安心してください。プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。

姓・名・メールの3つだけ／30秒／解除は3秒／詳細はこちら

なぜAnsible Execution Environments（EE）が生まれたのか

Ansibleが普及する中で、コミュニティでもRed Hat社内でも繰り返し報告されてきた問題があります。「ローカルでは動くのにCI/CDサーバーで失敗する」「先月まで動いていたPlaybookが今日突然壊れた」——その多くは、PythonやコレクションのバージョンがPC・サーバー・CI環境でそれぞれ異なることに起因していました。

従来のAnsible実行環境は「コントロールノード上にpipやdnfでAnsibleをインストールし、必要なコレクションを随時追加」という方式です。この方式の問題点は3つあります。

・再現性がない： pip install ansible-core を実行した時期によってバージョンが変わる
・依存関係が壊れやすい： コレクションAの更新がコレクションBの要件と競合することがある
・環境の属人化： 担当者のPCでだけ動くPlaybookが生まれ、引き継ぎ時に詰まる

EEはこれらの問題に対する答えとして設計されました。実行に必要なすべて（Ansible本体・コレクション・Pythonライブラリ・システムパッケージ）を1つのOCI準拠コンテナイメージに封入することで、「このイメージを使えば、誰が・どのマシンで実行しても同じ結果が出る」環境を実現します。

EEのアーキテクチャ——コンポーネントの役割と関係

1. EEとは何か——コンテナに閉じ込めた実行環境

EEは本質的には OCI（Open Container Initiative）準拠のコンテナイメージ です。Podman または Docker が動くコントロールノードで実行されます。コンテナ内には以下が含まれています。

・ベースイメージ： RHEL UBI（Universal Base Image）またはCentOS Streamをベースにしたイメージ
・ansible-runner： Playbookの実行エンジン（AWXやansible-navigatorはこれを内部的に呼び出す）
・Ansible core： Playbook解釈・モジュール実行の本体
・コレクション： requirements.ymlで指定したAnsible Galaxy（または社内レジストリ）のコレクション
・Pythonライブラリ： boto3（AWS操作）など、コレクションが依存するPythonパッケージ
・システムパッケージ： openssh-clients・sshpass などのOSレベルのバイナリ

2. ansible-builderとansible-navigatorの役割分担

EEに関わるメインツールは2つです。

ツール	役割	使う場面
ansible-builder	EEコンテナイメージを「作成」する。execution-environment.ymlを読み込みDockerfileを生成してPodman/Dockerでビルドする	CI/CDパイプライン、本番前の準備作業
ansible-navigator	EEコンテナイメージを「使って実行」する。ansible-playbookの上位互換CLIで、コンテナ内でPlaybookが動く	ローカル検証・開発・CLI運用

AWXやAnsible Automation Platform（AAP）は、このEEイメージをジョブテンプレートの実行環境として指定できます。「ansible-builderで作成 → レジストリにプッシュ → AWXで参照」という一連のフローが、チーム全体の実行環境統一の基本パターンです。

3. ベースイメージとレイヤー構造の選択

ansible-builderは複数のベースイメージをサポートします。社内での実運用では EE Minimal をベースに自チームが使うコレクションだけを追加した最小構成を作るのが推奨です。コンテナサイズを抑えることで、CI/CDでのプル時間が短縮されます。

・EE Minimal（quay.io/ansible/ansible-runner）： Ansible本体なし。カスタムコレクションだけを積む最小構成
・EE Supported（Red Hat版）： Red Hatがサポートするコレクションとpython依存ライブラリを含む標準構成
・Community EE Base： communityコレクション入り。非商用・検証用途向け

ansible-builderでEEを作成する手順

1. ansible-builderをインストールする

ansible-builderはpipでインストールします。Python 3.9以上が必要です。

# Python環境確認（3.9以上推奨） python3 --version # pipでansible-builderをインストール pip3 install ansible-builder # バージョン確認 ansible-builder --version

実機確認（RHEL 9.4）:

$ ansible-builder --version ansible-builder 3.1.0

2. execution-environment.ymlを作成する

EEのビルド定義ファイルは execution-environment.yml です。プロジェクトのルートに作成します。

# execution-environment.yml --- version: 3 images: base_image: name: quay.io/ansible/ansible-runner:latest dependencies: ansible_core: package_pip: ansible-core==2.17.* ansible_runner: package_pip: ansible-runner galaxy: requirements.yml python: requirements-python.txt system: bindep.txt

主要フィールドの説明:

・version: 3： ansible-builder 3.x形式の定義バージョン（2.x形式とは構文が異なる）
・images.base_image： ベースとなるコンテナイメージ。Quay.ioのAnsible公式イメージを指定する
・dependencies.galaxy： Ansibleコレクションの定義ファイル（requirements.yml）
・dependencies.python： Pythonライブラリの定義ファイル（requirements-python.txt / pip形式）
・dependencies.system： OSレベルのシステムパッケージ定義ファイル（bindep形式）

3. requirements.ymlでコレクションとPythonパッケージを定義する

Ansibleコレクションを指定する requirements.yml を作成します。


# requirements.yml
---
collections:
  - name: ansible.posix
    version: ">=1.5.4"
  - name: community.general
    version: ">=9.0.0"
  - name: amazon.aws
    version: ">=7.0.0"

Pythonパッケージを指定する requirements-python.txt:


# requirements-python.txt
boto3>=1.28
botocore>=1.31
requests>=2.28

システムパッケージを指定する bindep.txt:


# bindep.txt
openssh-clients [platform:rpm]
sshpass [platform:rpm]

[platform:rpm] は「RPMベースのOS（RHEL/CentOS/Rocky等）でのみインストール」という条件指定です。Debian系をベースにする場合は [platform:dpkg] を使います。

4. ansible-builder buildでイメージをビルドする

定義ファイルが揃ったら、ansible-builder build でビルドします。

# EEをビルドする（タグ名: my-ee:1.0） ansible-builder build --tag my-ee:1.0 --verbosity 2 # ビルド後のイメージ確認 podman images | grep my-ee

実機出力例:

$ podman images | grep my-ee localhost/my-ee 1.0 a3f9e21c0b2d 3 minutes ago 1.24 GB

ビルドが完了すると、Podmanのローカルレジストリにイメージが保存されます。チームで共有する場合はプライベートレジストリ（Quay.io、Harbor、AWS ECR等）にプッシュします。

# Quay.ioにプッシュする例 podman tag my-ee:1.0 quay.io/yourorg/my-ee:1.0 podman push quay.io/yourorg/my-ee:1.0

ansible-navigatorでEEを使ってPlaybookを実行する

1. ansible-navigatorをインストールする

# ansible-navigatorのインストール pip3 install ansible-navigator # バージョン確認 ansible-navigator --version

実機確認（RHEL 9.4）:

$ ansible-navigator --version ansible-navigator 24.12.1

2. ansible-navigator.ymlで実行設定をする

プロジェクトのルートに ansible-navigator.yml を作成し、使用するEEを指定します。

# ansible-navigator.yml --- ansible-navigator: execution-environment: image: my-ee:1.0 enabled: true pull: policy: missing # ローカルになければプルする mode: stdout # TUIを使わずにstdoutに出力（CI/CDで推奨） logging: level: warning

mode: stdout を指定するとansible-playbookと同じ出力形式になります。インタラクティブに操作するTUIモード（mode: interactive）は手元の開発時に便利です。

3. EEを指定してPlaybookを実行する

設定ファイルがある状態で ansible-navigator run を実行します。

# ansible-navigator.ymlがある場合（EEは設定ファイルから自動読み込み） ansible-navigator run site.yml -i inventory/production # コマンドラインで直接EEを指定することも可能 ansible-navigator run site.yml \ --execution-environment-image my-ee:1.0 \ --mode stdout \ -i inventory/production

実機実行例（RHEL 9.4、site.yml → 2台のWebサーバーにNginxをインストール）:


$ ansible-navigator run site.yml -i inventory/production --mode stdout

PLAY [Configure webservers] ****************************

TASK [Gathering Facts] ****************************
ok: [web01.example.com]
ok: [web02.example.com]

TASK [Install Nginx] ****************************
changed: [web01.example.com]
changed: [web02.example.com]

PLAY RECAP ****************************
web01.example.com : ok=2  changed=1  unreachable=0  failed=0
web02.example.com : ok=2  changed=1  unreachable=0  failed=0

従来の ansible-playbook コマンドとほぼ同じ出力ですが、Playbookが定義済みのコンテナ内で実行されている点が本質的な違いです。コントロールノードのAnsibleバージョンや手元のコレクション状態に左右されません。

AWX・AAPとEEを連携させる設計

AWXまたはAnsible Automation Platform（AAP）では、EEをジョブテンプレートに紐づけることで、チーム全体の実行環境を管理します。

・Execution Environmentsの登録： AWXのUIから「Execution Environments」メニューでEEを登録する。コンテナイメージのURLを入力するだけでよい
・ジョブテンプレートへの紐づけ： ジョブテンプレート作成時に「Execution Environment」フィールドで使用するEEを選択する
・バージョン管理： EEをタグで管理（my-ee:1.0、my-ee:2.0等）することで、Playbookごとに異なるバージョンを使い分けられる

EEをGitリポジトリと連携させ、コレクションやPythonパッケージのバージョンをコードとして管理する（GitOps化）と、Ansible実行環境の変更履歴も追跡可能になります。execution-environment.yml自体をPlaybookと同じリポジトリに格納し、更新のたびにCI/CDでビルド・プッシュ・AWXへの登録まで自動化するのが現場での定番パターンです。

フェーズ	操作	担当ツール
EE定義の変更	execution-environment.yml・requirements.ymlをGitでコミット	Git
EEのビルド	ansible-builder buildでイメージを作成	ansible-builder（CI/CD）
レジストリへのプッシュ	podman pushでQuay.io/ECR/Harborに格納	Podman（CI/CD）
AWXへの登録	AWX APIまたはUIでEEを更新・ジョブテンプレートに紐づけ	AWX（CI/CD or 手動）

よくあるエラーと対処法

【エラー1】「Podman binary could not be found in PATH」

Error: Failed to build EE: Podman binary could not be found in PATH

ansible-builderはデフォルトでPodmanを使います。未インストールの場合は dnf install podman でインストールします。DockerのみのPC環境では --container-runtime docker オプションでDockerを指定します。

# Dockerを使ってビルドする場合 ansible-builder build --tag my-ee:1.0 --container-runtime docker

【エラー2】「Could not find a collection named ...」

ERROR! Could not find a collection named 'namespace.collectionname'

requirements.ymlのコレクション名またはバージョン指定が間違っている可能性があります。コレクション名は namespace.collectionname の形式で正確に記述し、バージョンが存在するか事前に確認します。

# コレクションの存在とバージョン確認 ansible-galaxy collection info community.general

【エラー3】ansible-navigatorで「Image pull failed」

指定したEEイメージがローカルにもリモートにも見つからない場合に発生します。イメージのURLとタグを確認し、プライベートレジストリの場合はログイン状態も確認します。

# Quay.ioへのログイン確認 podman login quay.io # ansible-navigatorのpull policyをalwaysに変更して再取得を強制する # ansible-navigator.yml の該当行: # policy: always ansible-navigator run site.yml --pull-policy always -i inventory/production

本記事のまとめ

Ansible Execution Environments（EE）は、Playbookの実行環境をコンテナとして定義・管理し、チーム全員が同じ環境でAnsibleを動かせる基盤を提供します。「自分のPCでは動いたのに」という問題を根本から解決する設計思想です。

項目	説明
EE	PlaybookとすべてのAnsible依存物をOCIコンテナに封入した実行環境
ansible-builder	execution-environment.ymlを読んでEEイメージを作成するCLIツール
ansible-navigator	EEを使ってPlaybookを実行する。ansible-playbookの上位互換CLI
execution-environment.yml	ベースイメージ・コレクション・Pythonパッケージ・システムパッケージを一元定義
requirements.yml	EEに含めるAnsibleコレクションの一覧（Galaxy・Private Automation Hub）
AWX/AAP連携	EEをジョブテンプレートに紐づけてチーム全体の実行環境を統一管理する

EEとansible-navigatorを導入することで、実行環境の統一はコードで管理できるようになります。次のステップはexecution-environment.ymlをGitで管理し、CI/CDパイプラインでビルド・プッシュを自動化することです。Ansibleの冪等性設計と組み合わせることで、「インフラもコードも再現性100%」の自動化基盤が完成します。

現場で通用する安全なLinuxサーバー構築の「型」を体系的に身につけたい方へ、AnsibleのEEから実際のPlaybook設計まで、現役サーバー管理者が実機ハンズオンで体系的に教えます。20年以上の運用経験を持つ講師が、再現性のあるAnsible構成管理の型を伝授します。
Ansible実践ハンズオンの詳細を見る＞＞

無料メルマガで学習を続ける

Linuxの実践スキルをメールで毎週お届け。
登録は30秒、解除もいつでも可。

登録無料・いつでも解除できます

暗記不要・1時間後にはサーバーが動く

3,100名以上が実践した「型」を無料で公開中

プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
その「型」を図解60Pにまとめた入門マニュアルを、完全無料でプレゼントしています。