Documentation

15. 実行環境の設定リファレンス

このセクションには、execution environments のセットアップとビルドに関連する参照情報が含まれています。

15.1. Execution environment definition

定義ファイルは、execution environment のイメージをビルドするために必要な .yml ファイルです。execution environment 定義スキーマの例は以下のとおりです。

---
version: 1

build_arg_defaults:
  EE_BASE_IMAGE: 'quay.io/ansible/ansible-runner:stable-2.10-devel'

ansible_config: 'ansible.cfg'

dependencies:
  galaxy: requirements.yml
  python: requirements.txt
  system: bindep.txt

additional_build_steps:
  prepend: |
    RUN whoami
    RUN cat /etc/os-release
  append:
    - RUN echo This is a post-install command!
    - RUN ls -la /etc

15.1.1. 引数とベースイメージのビルド

ビルド引数のデフォルト値は、default_build_args セクションの定義ファイルでディクショナリーとして指定できます。これは、--build-arg CLI フラグを使用する代わりとなります。

ansible-builder によって使用されるビルド引数は、以下のとおりです。

  • ANSIBLE_GALAXY_CLI_COLLECTION_OPTS により、ユーザーは –pre フラグを渡してプレリリースコレクションのインストールを有効化できます。

  • EE_BASE_IMAGE は、execution environment の親イメージを指定します。

  • EE_BUILDER_IMAGE は、タイプタスクのコンパイルに使用されるイメージを指定します。

default_build_args 内部に与えられた値は、Containerfile にハードコーディングされるため、podman build が手動で呼び出される場合は永続化します。

CLI --build-arg フラグで同じ変数が指定されている場合は、CLI 値の優先順位が高くなります。

15.1.2. Ansible 設定ファイルパス

ansible.cfg ファイルを使用して、プライベートアカウントのトークンとその他の設定を Automation Hub サーバーに渡す場合、ここに設定ファイルのパスを (文字列として) 一覧表示すると、ビルドの初期段階でビルド引数として含めることができます。

15.1.3. AnsibleGalaxy の依存関係

galaxy エントリーは、ansible-galaxy collection install -r ... コマンドの有効な要件ファイルを指しています。

エントリー requirements.yml は、execution environment 定義のフォルダーのディレクトリーからの相対パスであるか、または絶対パスである可能性があります。

15.1.4. Python の依存関係

Python エントリーは、pip install -r ... コマンドの有効な要件ファイルを指しています。

エントリー requirements.txt は、execution environment 定義のフォルダーのディレクトリーからの相対パスであるか、または絶対パスである可能性があります。

15.1.5. システムレベルの依存関係

system エントリーは、bindep 要件ファイルを指します。これは bindep によって処理されてから dnf に渡されます。他のプラットフォームはまだサポートされていません。bindep の詳細については、OpenDev documentation を参照してください。

15.1.6. 追加のカスタムビルドの手順

追加のコマンドは、メインビルド手順の前 (prepend) または後 (append) のいずれかで、additional_build_steps セクションで指定できます。構文は以下のいずれかである必要があります。

  • 複数行の文字列 (上記の prepend セクションに例を示しています)

  • ディクショナリー (append を介して示すとおりです)

15.2. ansible-builder ビルドオプション

次のオプションは、ansible-builder build コマンドと使用できます。

Flag

Syntax

Description

--tag

$ ansible-builder build --tag=my-custom-ee

To customize the tagged name applied to the built image.

--file

$ ansible-builder build --file=my-ee.yml

To use a definition file named something other than execution-environment.yml.

--context

$ ansible-builder build --context=/path/to/dir

To specify a location other than the default directory named context created in the current working directory.

--build-arg

$ ansible-builder build --build-arg FOO=bar

To use Podman or Docker build-time variables, specify them the same way you would with podman build or docker build. By default, the Containerfile or Dockerfile contains a build argument EE_BASE_IMAGE, that lets you rebuild without modifying files.

--build-arg

$ ansible-builder build --build-arg EE_BASE_IMAGE=registry.example.com/another-ee

To use a custom base image, replaces previously discontinued --base-image option.

--container-runtime

$ ansible-builder build --container-runtime=docker

To use Docker to build images instead of the Podman default.

--verbosity

$ ansible-builder build --verbosity 2

To customize the level of verbosity.

15.2.1.

test/data/pytz の例では、execution environment 定義に awx.awx のコレクションが必要です。ルックアッププラグイン awx.awx.tower_schedule_rrule が機能するには、PyPI pytz と別のライブラリーが必要です。test/data/pytz/execution-environment.yml ファイルが ansible-builder build コマンドに提供される場合は、イメージ内にコレクションがインストールされ、コレクション内の requirements.txt ファイルを読み取り、続いて pytz をイメージにインストールします。

生成されたイメージは、これらの変数をプライベートデータディレクトリー内の env/settings ファイル内に配置して、ansible-runner プロジェクト内で使用することができます。

---
container_image: image-name
process_isolation_executable: podman # or docker
process_isolation: true

awx.awx コレクションは、デフォルトの AWX execution environment に含まれるコンテンツのサブセットです。詳細については、awx-ee repository を参照してください。

15.3. Collection-level metadata

execution environment の galaxy エントリー内のコレクションは、Python とシステム要件をイメージに提供します。

コレクションからの要件は、以下の方法で認識できます。

  • ファイル meta/execution-environment.yml は、Python および/または bindep 要件ファイルを参照します。

  • requirements.txt という名前のファイルは、コレクションのルートレベルにあります。

  • bindep.txt という名前のファイルは、コレクションのルートレベルにあります。

これらのファイルのいずれかがコレクションの build_ignore にある場合は、正しく動作しません。

コレクションメンテナーは、introspect コマンドを使用して、ansible-builder が想定する要件を認識していることを確認できます。いかに例を示します。

ansible-builder introspect --sanitize ~/.ansible/collections/

15.3.1. Python の依存関係

Python 要件ファイルは、他のファイルへの参照などの複雑な構文をサポートするために、requirements-parser ライブラリーを使用して 1 つのファイルに結合されます。

同じパッケージ名を与える別々のコレクションからのエントリーは、制約が結合された状態で同じエントリーに結合されます。

ansible-builder によって明確に 無視 されるパッケージ名がいくつかあります。コレクションがこれらのパッケージ名を一覧表示する場合、それらは結合されたファイルには含まれません。これらには、テストパッケージと Ansible 自体を提供するパッケージが含まれます。詳細な一覧は、ansible_builder.requirements モジュールの EXCLUDE_REQUIREMENTS を参照してください。

15.3.2. システムレベルの依存関係

bindep 形式は、クロスプラットフォームの要件を指定する方法を提供します。コレクションが [platform:rpm] に必要な要件を指定することが、少なくとも想定されています。

複数のコレクションからのエントリーは、1 つのファイルに結合されます。プロファイルのない要件 (ランタイム要件) のみがイメージにインストールされます。互いに完全に重複している複数のコレクションからのエントリーは、結合されたファイルに統合される場合があります。