Ansible Builder ガイド

Red Hat Ansible Automation Platform 2.1

Red Hat Ansible Automation Platform 用の一貫性のある再現可能な自動化実行環境を作成するための実行環境ビルダー

Red Hat Customer Content Services

概要

フィードバックの提供:
このドキュメントを改善するための提案がある場合、またはエラーを見つけた場合は、テクニカルサポート (https://access.redhat.com) に連絡し、Docs コンポーネントを使用して Ansible Automation Platform Jira プロジェクトで issue を作成してください。

はじめに

Ansible Builder を使用して、Red Hat Ansible Automation Platform のニーズに合わせて一貫性のある再現可能な自動化実行環境を作成します。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、今後の複数のリリースで段階的に用語の置き換えを実施して参ります。詳細は、弊社の CTO である Chris Wright のメッセージ を参照してください。

第1章 Ansible Builder の概要

1.1. Ansible Builder について

Ansible Builder は、さまざまな Ansible Collection で定義されたメタデータと、ユーザーが定義したメタデータを使用して、自動化実行環境を構築するプロセスを自動化するコマンドラインツールです。

1.1.1. Ansible Builder を使用する理由

Ansible Builder が開発される以前、Automation Platform ユーザーは、必要とするすべての依存関係がインストールされたカスタム仮想環境またはコンテナーを作成しようとすると、依存関係の問題と複数のエラーメッセージに対して実行される可能性がありました。

簡単でカスタマイズ可能な定義ファイルを使用することで、Ansible Builder は、Ansible、指定されたコレクション、およびその依存関係をインストールし、ジョブを実行するのに必要なすべての要件がバックグラウンドで満たされるようにします。

第2章 Ansible Builder の使用

2.1. Ansible Builder のインストール

Red Hat Subscription Management (RHSM) を使用して Ansible Builder をインストールし、Red Hat Ansible Automation Platform サブスクリプションをアタッチできます。Red Hat Ansible Automation Platform サブスクリプションをアタッチ すると、ansible-builder のインストールに必要なサブスクリプションのみのリソースにアクセスできます。サブスクリプションをアタッチすると、ansible-builder に必要なリポジトリーが自動的に有効になります。

注記

ansible-builder をインストールする前に、有効なサブスクリプションがホストにアタッチされている必要があります。

手順

  1. ターミナルで次のコマンドを実行して、Ansible Automation Platform リポジトリーをアクティブ化します。 

    $ dnf config-manager --enable ansible-automation-platform-2.1-for-rhel-8-x86_64-rpms

  2. 次に、次のコマンドを入力して Ansible Builder をインストールします。 

    $ dnf install ansible-builder

2.2. 定義ファイルの構築

Ansible Builder をインストールしたら、自動化実行環境イメージを作成するために Ansible Builder が使用する定義ファイルを作成する必要があります。自動化実行環境イメージを構築する高レベルのプロセスは、Ansible Builder が定義ファイルを読み取って検証してから、Containerfile を作成し、最後に Containerfile を Podman に渡して、自動化実行環境イメージを作成します。Ansible Builder 用に作成する定義ファイルには yaml 形式が使用されており、さまざまなセクションが含まれています。これらのセクションについては、さらに詳しく説明します。

以下は定義ファイルの例です。

例2.1 定義ファイル

version: 1

build_arg_defaults: 1
  ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: "-v"

ansible_config: 'ansible.cfg' 2

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

additional_build_steps: 4
  prepend: |
    RUN whoami
    RUN cat /etc/os-release
  append:
    - RUN echo This is a post-install command!
    - RUN ls -la /etc
1
ビルド引数のデフォルト値の一覧表示
2
ansible.cfg ファイルパスの指定
3
各種要件ファイルの場所の指定
4
追加のカスタムビルド手順用のコマンド

これらの定義ファイルのパラメーターについての詳細は、こちらのセクション を参照してください。

2.3. ビルドの実行およびコマンドの作成

前提条件

  • 定義ファイルを作成している

手順

自動化実行環境イメージをビルドするには、以下を実行します。 

$ ansible-builder build

Ansible Builder は、デフォルトでは execution-environment.yml という名前の定義ファイルを探しますが、-f フラグを使用して異なるファイルパスを引数として指定できます。 

$ ansible-builder build -f definition-file-name.yml

where definition-file-name は定義ファイルの名前を指定します。

2.4. 定義ファイルの内容の内訳

自動化実行環境のコンテナーイメージに含まれるコンテンツを指定するため、Ansible Builder で自動化実行環境を構築するには、定義ファイルが必要です。

次のセクションでは、定義ファイルのさまざまな部分について説明します。

2.4.1. ビルド引数およびベースイメージ

定義ファイルの build_arg_defaults セクションは、キーが Ansible Builder への引数のデフォルト値を指定できるディクショナリーです。build_arg_defaults で使用できる値の一覧は、以下の表を参照してください。

Value説明

ANSIBLE_GALAXY_CLI_COLLECTION_OPTS

  • ユーザーが –pre フラグを渡して、プレリリースコレクションのインストールを有効にすることを許可します
  • -c は verify_ssl を false に設定するのと同じです。

EE_BASE_IMAGE

自動化実行環境の親イメージを指定し、既存のイメージに基づいて新しいイメージを構築できるようにします。

EE_BUILDER_IMAGE

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

build_arg_defaults で指定される値は Containerfile にハードコーディングされるため、podman build を手動で呼び出すとこれらの値が維持されます。

注記

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

2.4.2. Ansible 設定ファイルパス

ansible.cfg ファイルを使用して、プライベートアカウントのトークンと他の設定を自動化ハブサーバーに渡す場合は、設定ファイルのパス (定義ファイルの場所を基準にした相対パス) を文字列として一覧表示し、ビルドの初期フェーズでビルド引数として有効にします。

ansible.cfg ファイルは以下の例のような形式にする必要があります。

例2.2 ansible.cfg ファイル

[galaxy]
server_list = automation_hub

[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=my_ah_token

自動化ハブからコレクションをダウンロードする方法は、関連する Ansible ドキュメントページ を参照してください。

2.4.3. 依存関係

2.4.3.1. Galaxy

galaxy エントリーは、ansible-galaxy collection install -r …​ コマンドの有効な要件ファイルを参照します。

requirements.yml エントリーは、自動化実行環境定義のディレクトリーからの相対パス、または絶対パスである可能性があります。

requirements.yml ファイルの内容は以下のようになります。

例2.3 Galaxy の requirements.yml ファイル

collections:
  - geerlingguy.java
  - kubernetes.core

2.4.3.2. Python

定義ファイルの python エントリーは、pip install -r …​ コマンドの有効な要件ファイルを参照します。

requirements.txt エントリーは、Collection がすでに Python の依存関係としてリストされているように追加の Python 要件をインストールするファイルです。自動化実行環境定義のフォルダーのディレクトリーからの相対パス、または絶対パスとして記載されている可能性があります。requirements.txt ファイルの内容は、pip freeze コマンドの標準出力と同様に、以下の例のような形式にする必要があります。

例2.4 Python の requirements.txt ファイル

boto>=2.49.0
botocore>=1.12.249
pytz
python-dateutil>=2.7.0
awxkit
packaging
requests>=2.4.2
xmltodict
azure-cli-core==2.11.1
python_version >= '2.7'
collection community.vmware
google-auth
openshift>=0.6.2
requests-oauthlib
openstacksdk>=0.13
ovirt-engine-sdk-python>=4.4.10

2.4.3.3. システム

定義の システム エントリーは、bindep 要件ファイルを指定しています。このファイルは、コレクションに依存関係として含まれていないシステムレベルの依存関係をインストールします。自動化実行環境定義のフォルダーのディレクトリーからの相対パス、または絶対パスとして記載されている可能性があります。

これは、libxml2 パッケージおよび subversion パッケージをコンテナーに追加する bindep.txt ファイルの例です。

例2.5 bindep.txt ファイル

libxml2-devel [platform:rpm]
subversion [platform:rpm]

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

prepend コマンドと append コマンドは、additional_build_steps セクションで指定できます。これにより、メインのビルド手順が実行される前または後に実行する Containerfile にコマンドが追加されます。

additional_build_steps の構文は以下のいずれかである必要があります。

  • 複数行の文字列

    例2.6 複数行の文字列エントリー

    RUN whoami
RUN cat /etc/os-release

  • リスト

    例2.7 リストエントリー

    - RUN echo This is a post-install command!
- RUN ls -la /etc

2.5. 任意のビルドコマンド引数

-t フラグは、自動化実行環境イメージに特定の名前を付けます。たとえば、以下のコマンドは my_first_ee_image という名前のイメージを構築します。 

$ ansible-builder build -t my_first_ee_image

複数の定義ファイルがある場合は、-f フラグで、使用する定義ファイルを指定できます。 

$ ansible-builder build -f another-definition-file.yml -t another_ee_image

上記の例 では、Ansible Builder が、デフォルトの execution-environment.yml の代わりに another-definition-file.yml ファイルで提供される仕様を使用して、another_ee_image という名前の自動実行環境イメージを構築します。

build コマンドで使用できるその他の仕様とフラグについては、ansible-builder build --help と入力して、追加オプションのリストを表示してください。

2.6. イメージの構築なしで Containerfile の作成

イメージをビルドせずに共有可能な Containerfile を作成するには、以下を実行します。 

$ ansible-builder create

第3章 自動化実行環境の公開

3.1. 実行環境コンテナーイメージを自動化ハブにプッシュ

前提条件

  • 自動化ハブで実行環境のパーミッションがあり、新しいコンテナーを作成したり、既存のコンテナーにプッシュすることを許可している。

コンテナーレジストリーはコンテナーイメージを保存するためのリポジトリーです。自動化実行環境イメージを構築すると、そのコンテナーイメージを自動化ハブのインスタンスのレジストリー部分にプッシュする準備が整います。

自動化ハブの URL を使用して以下のコマンドを実行し、Podman にログインし、ユーザー名、パスワード、および自動化のハブ URL に置き換えてください。 

$ podman login -u=username -p=password automation-hub-url

Podman にログインしたら、以下のコマンドを実行してコンテナーイメージを自動化ハブのコンテナーレジストリーにプッシュします。 

$ podman push automation-hub-url/ee-image-name
注記

自動化実行環境イメージ名は、ansible-builder build コマンドに -t 引数で指定します。-t フラグを使用してカスタムイメージ名を指定しない場合、デフォルトのイメージタグは ansible-execution-env:latest になります。

3.2. 保護されたレジストリーからのプル

パスワードまたはトークンで保護されるレジストリーからコンテナーイメージをプルするには、自動化コントローラーで認証情報を作成します。

手順

  1. Automation Controller に移動します。
  2. サイドメニューバーの Resources → Credentials をクリックします。
  3. Add をクリックして、新規の認証情報を作成します。
  4. 認証 URL、ユーザー名、およびパスワードを指定します。Save をクリックします。

詳細は、実行環境のドキュメントの Pulling from Protected Registries セクションを参照してください。

第4章 Red Hat Ansible Automation Platform が提供する既存のベース EE を基に構築

4.1. システムレベルの依存関係の収集

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

以下は、有効な bindep.txt ファイルからのコンテンツの例です。

例4.1 bindep.txt ファイル

python38-devel [platform:rpm compile]
subversion [platform:rpm]
git-lfs [platform:rpm]

複数のコレクションからのエントリーは単一ファイルに統合されます。これは bindep により処理され、その後 dnf に渡されます。プロファイルのない要件や、ランタイム要件がイメージにインストールされません。

4.2. 既存の実行環境イメージのカスタマイズ

Ansible コントローラーには、以下の 3 つのデフォルト実行環境が同梱されています。

  • Ansible 2.9 - Controller モジュール以外のコレクションがインストールされない
  • Minimal - 最新の Ansible 2.12 リリースと Ansible Runner が含まれていますが、コレクションやその他の追加コンテンツは含まれていません。
  • EE Supported: Red Hat がサポートするコンテンツがすべて含まれる

これらの環境は多くの自動化ユースケースに対応しますが、追加の項目を追加して、特定のニーズに合わせてこれらのコンテナーをカスタマイズできます。以下の手順では、kubernetes.core コレクションを ee-minimal デフォルトイメージに追加します。

手順

  1. Podman を使用して registry.redhat.io にログインします。 

    $ podman login -u="[username]" -p="[token/hash]" registry.redhat.io

  2. Automation Execution Environment イメージをプルする 

    podman pull registry.redhat.io/ansible-automation-platform-21/ee-minimal-rhel8:latest

  3. Ansible Builder ファイルを、ee-minimal をベースとする新しい実行環境イメージに追加する追加のコンテンツを指定するように設定します。

    1. たとえば、Kubernetes Core Collection を Galaxy から イメージに追加するには、以下のように requirements.yml ファイルを入力します。 

      collections:
  - kubernetes.core
    2. 定義ファイルとそのコンテンツの詳細は、定義ファイルの内訳 セクションを参照してください。

  4. 実行環境定義ファイルの EE_BASE_IMAGE フィールドで、元の ee-minimal コンテナーファイルへのパスを指定します。その場合、最終的な execution-environment.yml ファイルは以下のようになります。

    例4.2 カスタマイズされた execution-environment.yml ファイル

    version: 1

build_arg_defaults:
  EE_BASE_IMAGE: 'example.registry.com/my-base-ee'

dependencies:
  galaxy: requirements.yml
    注記

    この例では、自動化ハブからの認定コレクションではなく、コミュニティーバージョンの kubernetes.core を使用するため、ansible.cfg を作成したり、定義ファイルで参照したりする必要はありません。

  5. 以下のコマンドを使用して、新しい実行環境イメージを構築します。 

    $ ansible-builder build -t registry.redhat.io/[username]/new-ee

    ここで、[username] はユーザー名を指定し、new-ee は新しいコンテナーイメージの名前を指定します。

    1. podman images コマンドを使用して、新しいコンテナーイメージが一覧に表示されていることを確認します。

      例4.3 new-ee イメージを使用した podman images コマンドの出力

      REPOSITORY          TAG     IMAGE ID      CREATED        SIZE
localhost/new-ee    latest  f5509587efbb  3 minutes ago  769 MB
  6. Ansible Navigator で新たに作成した実行環境イメージを確認します。

  7. Automation Hub で使用するイメージにタグを付けます。 

    $ podman tag registry.redhat.io/_[username]_/_new-ee_ [automation-hub-IP-address]/_[username]_/_new-ee_

  8. Podman を使用して Automation Hub にログインします。

    注記

    コンテナーをプッシュするには、Automation Hub の admin または適切なコンテナーリポジトリーのアクセス許可が必要です。 を参照Managing containers in private automation hub詳細については、Red Hat Ansible Automation Platform ドキュメント の を参照してください。 

    $ podman login -u="[username]" -p="[token/hash]" [automation-hub-IP-address]

  9. イメージを自動化ハブのコンテナーレジストリーにプッシュします。 

    $ podman push [automation-hub-IP-address]/_[username]_/_new-ee_

  10. 新しいイメージを自動化コントローラーインスタンスにプルします。

    1. Automation Controller に移動します。
    2. ナビゲーションバーから、Administration → Execution Environments の順にクリックします。
    3. Add をクリックします。

    4. 適切な情報を入力して Save をクリックし、新規イメージにプルします。

      注記

      自動化ハブのインスタンスがパスワードまたはトークンで保護されている場合は、適切なコンテナーレジストリーの認証情報が設定されていることを確認してください。

法律上の通知

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.