15.2. 設定オプション
定義ファイルで次の設定 YAML キーを使用します。
Ansible Builder 3.x 実行環境定義ファイルは、次の 7 つの最上位セクションを受け入れます。
15.2.1. additional_build_files
ビルドファイルは、ビルドコンテキストディレクトリーに追加する内容を指定します。これらは、任意のビルド段階で Additional_build_steps によって参照またはコピーできます。
形式はディクショナリー値のリストで、各リスト項目に src および dest のキーと値を含めます。
各リスト項目は、次の必須キーを含むディクショナリーである必要があります。
| src | ビルドコンテキストディレクトリーにコピーするソースファイルを指定します。
これは、 |
| dest |
ソースファイル (例:
この値を絶対パスで指定することや、パス内に 注記
|
15.2.2. additional_build_steps
ビルドステップは、任意のビルドフェーズのカスタムビルドコマンドを指定するものです。これらのコマンドは、コンテナーランタイムのビルド指示ファイル (Containerfile や Dockerfile など) に直接挿入されます。コマンドは、コンテナー化ツールで必要なルールに準拠する必要があります。
ビルドステップは、イメージ作成プロセスのどの段階の前後にも追加できます。たとえば、依存関係をインストールする前に git をインストールする必要がある場合は、ベースビルド段階の最後にビルドステップを追加できます。
有効なキーは次のとおりです。それぞれが複数行の文字列または文字列のリストをサポートします。
| append_base | 基本イメージの構築後に挿入するコマンド。 |
| append_builder | ビルダーイメージの構築後に挿入するコマンド。 |
| append_final | 最終イメージの構築後に挿入するコマンド。 |
| append_galaxy | Galaxy イメージの構築後に挿入するコマンド。 |
| prepend_base | 基本イメージを構築する前に挿入するコマンド。 |
| prepend_builder | ビルダーイメージを構築する前に挿入するコマンド。 |
| prepend_final | 最終イメージを構築する前に挿入するコマンド。 |
| prepend_galaxy | Galaxy イメージを構築する前に挿入するコマンド。 |
15.2.3. build_arg_defaults
これにより、ビルド引数のデフォルト値がディクショナリーとして指定されます。
これは、--build-arg CLI フラグの代わりに使用する方法です。
Ansible Builder は次のビルド引数を使用します。
| ANSIBLE_GALAXY_CLI_COLLECTION_OPTS |
|
| ANSIBLE_GALAXY_CLI_ROLE_OPTS |
使用すると、 |
| PKGMGR_PRESERVE_CACHE | これは、イメージのビルドプロセス中にパッケージマネージャーのキャッシュがクリアされる頻度を制御します。
この値が設定されていない場合 (デフォルト)、キャッシュは頻繁にクリアされます。値が |
Ansible Builder は、build_arg_defaults 内で指定された値をビルド指示ファイルにハードコーディングするため、コンテナーのビルドを手動で実行した場合でも値は保持されます。
定義と CLI build-arg フラグを使用したコマンドラインで同じ変数を指定すると、CLI の値によって定義の値がオーバーライドされます。
15.2.4. 依存関係
ansible-core、ansible-runner、Python パッケージ、システムパッケージ、コレクションなど、最終イメージにインストールする依存関係を指定します。Ansible Builder は、ユーザーがインストールする Ansible コレクションの依存関係を自動的にインストールします。
一般に、標準の構文を使用してパッケージのバージョンを制限できます。dnf、pip、ansible-galaxy、またはその他のパッケージ管理ユーティリティーに渡すのと同じ構文を使用します。パッケージまたはコレクションを別のファイルで定義し、定義ファイルの dependencies セクションで上記のファイルを参照することもできます。
有効なキーは次のとおりです。
| ansible_core |
インストールされる
この値は、キー ( ansible_core:
package_pip: ansible-core
ansible_core:
package_pip: ansible-core==2.14.3
ansible_core:
package_pip: https://github.com/example_user/ansible/archive/refs/heads/ansible.tar.gz
|
| ansible_runner | インストールする Ansible Runner Python パッケージのバージョン。
この値は、キー ( ansible_runner:
package_pip: ansible-runner
ansible_runner:
package_pip: ansible-runner==2.3.2
ansible_runner:
package_pip: https://github.com/example_user/ansible-runner/archive/refs/heads/ansible-runner.tar.gz
|
| galaxy | Ansible Galaxy からインストールするコレクション。
これは、ファイル名、ディクショナリー、または Ansible Galaxy |
| python | Python のインストール要件。
これには、ファイル名または要件のリストなどを使用できます。Ansible Builder は、 このライブラリーは、他のファイルへの参照を含む複雑な構文をサポートします。多数のコレクションに同じ パッケージ名 が必要な場合、Ansible Builder はそれらを 1 つのエントリーにまとめ、制約を結合します。
Ansible Builder は、コレクションにパッケージが依存関係としてリストされている場合でも、Python 依存関係の結合ファイル内の一部のパッケージを除外します。これには、テストパッケージと、Ansible 自体を提供するパッケージが含まれます。完全なリストは、
このような除外されるパッケージ名のいずれかを含める必要がある場合は、 この方法で提供されたパッケージは、除外された Python パッケージのリストに対して処理されません。 |
| python_interpreter |
dnf によってインストールされる Python システムパッケージ名 ( |
| system | インストールされるシステムパッケージ (bindep 形式)。ファイル名または要件のリストを指定できます。 bindingep の詳細は、OpenDev のドキュメント を参照してください。
システムパッケージの場合、 |
次の例では、さまざまな依存関係を含むファイル名を使用しています。
dependencies:
python: requirements.txt
system: bindep.txt
galaxy: requirements.yml
ansible_core:
package_pip: ansible-core==2.14.2
ansible_runner:
package_pip: ansible-runner==2.3.1
python_interpreter:
package_system: "python310"
python_path: "/usr/bin/python3.10"この例ではインライン値を使用します。
dependencies:
python:
- pywinrm
system:
- iputils [platform:rpm]
galaxy:
collections:
- name: community.windows
- name: ansible.utils
version: 2.10.1
ansible_core:
package_pip: ansible-core==2.14.2
ansible_runner:
package_pip: ansible-runner==2.3.1
python_interpreter:
package_system: "python310"
python_path: "/usr/bin/python3.10"
これらの依存関係ファイル (requirements.txt、bindep.txt、requirements.yml) のいずれかがコレクションの build_ignore に含まれている場合、ビルドが失敗します。
コレクションのメンテナーは、introspect コマンドを使用して、期待される要件を ansible-builder が認識していることを確認できます。
ansible-builder introspect --sanitize ~/.ansible/collections/
--sanitize オプションは、すべてのコレクション要件を確認し、重複を削除します。また、通常は除外される Python 要件も削除されます (Python の依存関係を参照)。
-v3 オプションを使用して イントロスペクト を行い、除外されている要件に関するログメッセージを確認します。
15.2.5. images
使用するベースイメージを指定します。少なくとも、ベースイメージのソース、イメージ、およびタグを指定する必要があります。基本イメージはオペレーティングシステムを提供し、いくつかのパッケージも提供することもできます。標準の host/namespace/container:tag 構文を使用してイメージを指定します。代わりに Podman または Docker のショートカット構文を使用することもできますが、完全な定義の方が信頼性と移植性が高くなります。
このセクションの有効なキーは次のとおりです。
| base_image | 実行環境の親イメージを定義するディクショナリー。
使用するコンテナーイメージには |
15.2.6. Image verification
podman コンテナーランタイムを使用している場合は、署名されたコンテナーイメージを検証できます。
Container-policy CLI オプションを設定して、コンテナーイメージの署名検証のための Podman policy.json ファイルに関連してこのデータがどのように使用されるかを制御します。
-
ignore_allポリシー: 署名検証が実行されないビルドのcontext directory <context>に、policy.jsonファイルを生成します。 -
システムポリシー: 署名の検証は、標準のシステムの場所にある既存のpolicy.jsonファイルを使用して実行されます。ansible-builderは、これらのファイル内のコンテンツに対する責任を負わず、ユーザーがコンテンツを完全に制御できます。 -
Signature_requiredポリシー:ansible-builderは、コンテナーイメージ定義で、ビルド中にイメージを検証するために使用される、ビルドのcontext directory <context>内にpolicy.jsonファイルを生成します。
15.2.7. options
Ansible Builder のランタイム機能に影響を与える可能性のあるキーワードまたはオプションのディクショナリー。
このセクションの有効なキーは次のとおりです。
context_init: コンテナーの
ENTRYPOINTおよびCMDディレクティブ (および関連する動作) のカスタマイズを可能にするキーを含むディクショナリー。これらの動作のカスタマイズは高度なタスクであり、デバッグが困難な障害が発生する可能性があります。下記のデフォルト値は、複数の密接な動作を制御するものです。そのため、いずれかの値をオーバーライドすると、このディクショナリー内の残りのデフォルトがすべてスキップされます。有効なキーは次のとおりです。
-
cmd :
CMDContainerfile ディレクティブのリテラル値。デフォルト値は["bash"]です。 entrypoint:
ENTRYPOINTContainerfile ディレクティブのリテラル値。デフォルトのエントリーポイントの動作は、サブプロセスへのシグナルの伝播を処理するだけでなく、実行時に、コンテナーユーザーが有効で書き込み可能なホームディレクトリーが含まれる適切な環境が含まれます。このディレクトリーは、/etc/passwdで表現されており、HOME環境変数と一致するように設定されています。デフォルトのエントリーポイントスクリプトは、ユーザーのランタイム環境を適切に調整できない場合に、stderrに警告を発行できます。この動作は無視されるか、致命的なエラーに格上げされる可能性があります。詳細は、エントリーポイントターゲットスクリプトのソースを参照してください。デフォルト値は
["/opt/builder/bin/entrypoint", "dumb-init"]です。package_pip : エントリーポイントのサポートのために pip を使用してインストールするパッケージ。このパッケージは、最終的なビルドイメージにインストールされます。
デフォルト値は
Dam-init==1.2.5です。
-
cmd :
-
package_manager_path: 使用するパッケージマネージャー (dnf または microdnf) へのパスを含む文字列。デフォルトは
/usr/bin/dnfです。この値は、dependencyで指定されている場合、assembleスクリプトによるビルドフェーズ中に Python インタープリターをインストールするために使用されます。 Skip_ansible_check: このブール値は、Ansible および Ansible Runner のインストールのチェックを最終イメージで実行するかどうかを制御します。
このチェックを実行しない場合は、この値を
Trueに設定します。デフォルトは
Falseです。Relax_passwd_permissions : このブール値は、
ルートグループ (GID 0) に、最終コンテナーイメージ内の/etc/passwdへの書き込みパーミッションを明示的に付与するかどうかを制御します。デフォルトのエントリーポイントスクリプトは、完全に機能する POSIX ユーザー環境とホームディレクトリーを確保するために、動的に作成されたユーザーを使用して一部のコンテナーランタイムで/etc/passwdの更新を試みることができます。この機能を無効にすると、有効で書き込み可能なホームディレクトリーを持つユーザーを/etc/passwdにリストする必要があるソフトウェア機能 (たとえば、ansible-core のasyncや~usernameシェル拡張など) が失敗する可能性があります。デフォルトは
Trueです。workdir: 最終コンテナーイメージで開始される新しいプロセスのデフォルトとして設定されている現在の作業ディレクトリー。一部のコンテナーランタイムは、
root(GID 0) グループ内で動的に作成されたユーザーのHOMEとしてもこの値を使用します。この値を指定すると、ディレクトリーがまだ存在しない場合はディレクトリーが作成され、rootグループの所有権が設定され、rwxグループのアクセス許可が再帰的に適用されます。デフォルト値は
/runnerです。user: 最終的なコンテナーイメージのデフォルトユーザーとして使用するユーザー名または UID を設定します。
デフォルト値は
1000です。
オプションの例:
options:
container_init:
package_pip: dumb-init>=1.2.5
entrypoint: '["dumb-init"]'
cmd: '["csh"]'
package_manager_path: /usr/bin/microdnf
relax_password_permissions: false
skip_ansible_check: true
workdir: /myworkdir
user: bob
15.2.8. version
実行環境定義ファイルのスキーマバージョンを設定する整数値。
デフォルトは 1 です。
Ansible Builder 3.x を使用している場合、値は 3 である必要があります。
