Red Hat Ansible Automation Platform Creator ガイド

Red Hat Ansible Automation Platform 2.0-ea

本ガイドは、自動化にコンテンツを作成する際に Ansible を使用する方法を学習する開発者向けのものです。

Red Hat Customer Content Services

概要

フィードバックの提供:
本書を改善するための提案がある場合、またはエラーを見つけた場合は、http://issues.redhat.com で案件を作成してください。Ansible Automation Platform プロジェクトを選択し、Documentation コンポーネントを使用します。

第1章 序文

自動化実行環境を使用した Red Hat Ansible Automation Platform 内のコンテンツの自動化

再現可能な移植性、一貫性があり、共有可能なコンテナーイメージとして、実行環境を使用できます。これは、コレクション形式で、システム依存関係、Python の依存関係、Ansible バージョン、および Ansible コンテンツから、Ansible Automation Platform ジョブのランタイム環境の依存関係をすべて制御します。

第2章 コンテンツ作成者のワークフローおよび自動化実行環境の概要

2.1. コンテンツワークフローについて

Red Hat Ansible Automation Platform 2.0 より前は、自動化コンテンツ開発者は非常に多くの Python 仮想環境を必要としていたため、それらを管理するために独自の自動化が必要でした。このレベルの複雑性を軽減するため、Ansible Automation Platform 2.0 は仮想環境から離れ、代わりに自動化実行環境と呼ばれるコンテナーを使用しています。コンテナーは構築と管理が簡単で、チーム間や組織間で共有しやすいためです。

自動化コントローラーが自動化実行環境の使用に移行すると、自動化コンテンツナビゲーターやAnsible Builder などのツールにより、独自の開発システム内でこれらの自動化実行環境をローカルで利用できるようになります。

2.2. アーキテクチャーの概要

次の一覧は、Ansible Automation Platform 2.0 で利用可能なツールの配置と使用、およびそれらの使用方法を示しています。

  • 自動化コンテンツナビゲーターだけが、現在 Ansible Automation Platform 1.2 で使用できます。
  • 自動化コンテンツナビゲーターと、ダウンロードした自動化実行環境は、ラップトップまたはワークステーションで直接使用されます。
  • 自動化コンテンツナビゲーター、ダウンロードされた自動化実行環境、自動化コントローラーをローカルからリモートにプッシュまたは実行します。
  • 自動化コンテンツナビゲーター、自動化コントローラー、Ansible Builder、およびレイヤー化されたカスタム EE は、自動化ジョブの実行方法に使用されるコンテンツをさらに細かく制御できます

第3章 Ansible の概念について

自動化開発者は、以下の Ansible の概念を確認し、Ansible 開発プロジェクトの開始前に、成功した Ansible Playbook と自動化実行環境を作成します。

3.1. 前提条件

  • Ansible がインストールされている。Ansible のインストールに関する情報は、Ansible ドキュメントの「Ansible のインストール」を参照してください。

3.2. Ansible Playbook について

Playbook は、特定の人間が判読可能な命令のセットを含む YAML で書かれたファイルです。これには、単一ターゲットまたはターゲットグループで実行するように送信されます。

Playbook を使用して、リモートマシンの構成とデプロイメントを管理したり、ローリング更新を含む多層ロールアウトを順序付けたりすることができます。Playbook を使用して、アクションを他のホストに委譲し、途中で監視サーバーやロードバランサーと対話します。作成した Playbook は、自動化のために企業全体で繰り返し使用できます。

3.3. Ansible ロールについて

ロールは、自動化コンテンツをバンドルするだけでなく、既知のファイル構造を利用して関連する変数、ファイル、タスク、ハンドラー、およびその他のアーティファクトを自動的に読み込む Ansible の方法です。何百ものプレイで巨大な Playbook を作成する代わりに、ロールを使用して、タスクをより小さく、より個別の作業単位に分割することができます。

インフラストラクチャーのプロビジョニング、アプリケーションのデプロイ、および Ansible Galaxy で各タスクを実行するすべてのタスクにロールがあります。Type で検索にフィルターを設定し、Role を選択します。対象のロールを見つけたら、Ansible に同梱されている ansible-galaxy コマンドを使用してダウンロードできます。

$ ansible-galaxy install username.rolename

3.4. コンテンツコレクションについて

Ansible Content Collection は、自動化用の使いやすいツールキットです。Playbook、ロール、モジュール、プラグインなど、複数の種類のコンテンツがすべて 1 か所に含まれています。以下の図は、コレクションの基本構造を示しています。

├── docs
├── galaxy.yml
├── playbooks
│   ├── files
│   ├── tasks
│   ├── templates
│   └── vars
├── plugins
│   ├── modules
│   │   ├── module1.py
│   │   └── module2.py
│   ├── lookups
│   └── filters
├── titles
│   ├── role1
│   └── role2
└── tests

Red Hat Ansible Automation Platform では、自動化ハブは、Ansible 認定コンテンツコレクションのソースとして機能します。

3.5. 実行環境について

自動化実行環境は、Ansible コントロールノードとして機能する一貫性のある共有可能なコンテナーイメージです。自動化実行環境は、デフォルト以外の依存関係を必要とする Ansible コンテンツで課題を修正します。

自動化実行環境には、以下が含まれます。

  • Ansible
  • Ansible Runner
  • Ansible コレクション
  • Python またはシステムの依存関係

    • コレクション内のモジュール/プラグイン
    • ansible-core のコンテンツ
    • カスタムのユーザーニーズ

Ansible Builder を使用して自動化実行環境を定義および作成することができます。

第4章 ツールおよびコンポーネント

自動化実行環境の作成に使用する Red Hat Ansible Automation Platform ツールおよびコンポーネントについて参照してください。

4.1. Ansible Builder について

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

4.2. 自動化コンテンツナビゲーターについて

自動化コンテンツナビゲーターは、次のことができるテキストベースのユーザーインターフェースを備えたコマンドラインのコンテンツクリエーターに焦点を当てたツールです。

  • ジョブおよび Playbook を起動し、監視します。
  • 保存され、完成した Playbook とジョブ実行アーティファクトを JSON 形式で共有します。
  • 自動化実行環境を閲覧およびイントロスペクションします。
  • ファイルベースのインベントリーを参照します。
  • Ansible モジュールのドキュメントをレンダリングし、Playbook で使用できるサンプルを展開します。

4.2.1. 自動化コンテンツナビゲーターを使用する理由

現在、ansible-playbook コマンドなど、Ansible コアの一部である Ansible コマンドは、コンテナーで実行できません。このニーズを満たすために、自動化コンテンツナビゲーターは、自動化実行環境でこれらの Ansible CLI コマンドセットを有効にします。Automation コンテンツナビゲーターには、テキストベースのユーザーインターフェース内にさらに詳細な出力が含まれます。

4.3. Automation Hub について

Automation Hub provides a place for Red Hat subscribers to quickly find and use content that is supported by Red Hat and our technology partners to deliver additional reassurance for the most demanding environments.
At a high level, Automation Hub provides an overview of all partners participating and providing certified, supported content.
From a central view, users can dive deeper into each partner and check out the collections.
Additionally, a searchable overview of all available collections is available.

4.4. Ansible コマンドラインインターフェースについて

コマンドラインで Ansible を使用すると、非常に頻繁に繰り返されないタスクを実行するために便利な方法になります。タスクを繰り返す場合は、Playbook を作成することが推奨されます。

コマンドラインにおける Ansible 用のアドホックコマンドは、以下の構造に従います。

$ ansible [pattern] -m [module] -a "[module options]"

4.5. 追加情報

第5章 開発環境の設定

このセクションの手順に従って、自動化実行環境を作成するための開発環境をセットアップできます。

5.1. Ansible Builder のインストール

Red Hat Subscription Management を使用して Ansible Builder をインストールして、Red Hat Ansible Automation Platform サブスクリプションに登録および割り当てることができます。端末で、以下のコマンドを実行します。

$ dnf install ansible-builder

Python Package Index (PyPI) から Ansible Builder をインストールすることもできます。この設定でインストールするには、以下を実行します。

$ pip install ansible-builder

5.2. RPM からの RHEL への自動化コンテンツナビゲーターのインストール

RPM から、Red Hat Enterprise Linux (RHEL) に自動化コンテンツナビゲーターをインストールできます。

前提条件

  • Red Hat Subscription Manager でシステムを登録している。

手順

  1. RHEL 8 のリポジトリーを有効にします。

    $ sudo subscription-manager repos --enable automation-platform-2.0-for-rhel-8-x86_64-rpms
  2. 自動化コンテンツナビゲーターをインストールします。

    $ dnf install ansible-navigator

検証

  • 自動化コンテンツナビゲーターのインストールを確認します。

    $ ansible-navigator --help

自動化コンテンツナビゲーターの主な機能を説明するヘルプ出力が表示されます。

5.3. ベース自動化実行環境のダウンロード

AAP 2.0 に同梱されるベースイメージは、Red Hat Ecosystem Catalog (registry.redhat.io) でホストされているものです。

前提条件

  • 有効な Red Hat Ansible Automation Platform サブスクリプションがある。

手順

  1. registry.redhat.io にログインします。

    $ podman login registry.redhat.com
  2. レジストリーからベースイメージをプルします。

    $ podman pull registry.redhat.io/aap/<image name>

第6章 コンテンツの作成

Red Hat Ansible Automation Platform で使用するコンテンツの開発に関する詳細は、作成者ガイド でこのセクションに関するガイドラインを参照してしてください。

6.1. Playbook の作成

Playbook は、3 つの YAML ダッシュ (---) で始まり、その後に次のものが続きます。

  • Name: Playbook の全体的な機能について簡単に説明し、全ユーザーに対して読み取り可能かつ整理された状態を維持するのに役立ちます。
  • Hosts: Ansible が実行するターゲットを特定します。
  • become 文: この任意の文は、権限のエスカレーションをアクティブにするために true/yes に設定できます (例: sudo、su、pfexec、doas、pbrun、dzdo、ksu など)。
  • Tasks: これは、Ansible モジュールへの呼び出しを介して実行されるアクションの一覧です。

Playbook の例

---
- name: Set Up a Project and Job Template
  hosts: host.name.ip
  become: true

  tasks:
    - name: Create a Project
      awx.awx.project:
        name: Job Template Test Project
        state: present
        scm_type: git
        scm_url: https://github.com/ansible/ansible-tower-samples.git

    - name: Create a Job Template
      awx.awx.job_template:
        name: my-job-1
        project: Job Template Test Project
        inventory: Demo Inventory
        playbook: hello_world.yml
        job_type: run
        state: present

6.2. ロールの作成

Ansible にバンドルされている ansible-galaxy コマンドラインツールを使用して、init コマンドでロールを作成できます。

たとえば、以下のコマンドは、現在の作業ディレクトリーに role_name という名前のロールディレクトリー構造を作成します。

$ ansible-galaxy init role_name
The `role_name` directory will contain the following:
.travis.yml
README.md
defaults/
    main.yml
files/
handlers/
    main.yml
meta/
    main.yml
tasks/
    main.yml
templates/
tests/
    inventory
    test.yml
vars/
    main.yml

追加情報

  • ロールの作成に関する詳細は、Ansible Galaxy ドキュメントの「ロールの作成」を参照してください。

6.3. コレクションの作成

Ansible Galaxy CLI ツールを使用して、独自のコレクションをローカルで作成できます。コレクション固有のコマンドはすべて、collection サブコマンドを使用してアクティベートできます。

前提条件

  • 開発環境に Ansible バージョン 2.9 以降がインストールされている。

手順

  1. 端末で、名前空間の root ディレクトリーの場所に移動します。
  2. 以下のコマンドを実行して、my_namespacemy_collection_name を選択した値に置き換えます。

    $ ansible-galaxy collection init <my_namespace>.<my_collection_name>
    注記

    galaxy.ansible.com または cloud.redhat.com/ansible/automation-hub の「My Content」タブの下で、名前空間にアップロードする適切なパーミッションがあることを確認してください。

上記のコマンドは、上記の名前空間引数から名前が付けられたディレクトリーが存在しない場合は作成し、そのディレクトリーに Collection 名を指定してディレクトリーを作成します。そのディレクトリー内では、デフォルトまたは「スケルトン」Collection になります。ここでは、ロールまたはプラグインを追加し、独自の Collection 開発に取り掛かることができます。

実行環境に関連して、コレクション開発者は Ansible Builder で適切なメタデータを提供することで、コンテンツの要件を宣言できます。

Collection からの要件は、以下の方法で認識できます。

  • meta/execution-environment.yml ファイルが Python または bindep 要件ファイル、もしくはその両方を参照します。
  • Python の依存関係に関する情報を含む requirements.txt という名前のファイルは、Collection のルートディレクトリーにある場合があります。
  • システムレベルの依存関係を含む bindep.txt という名前のファイルは、Collection のルートレベルに存在する場合があります。
  • これらのファイルのいずれかが Collection の build_ignore にある場合、このセクションはビルドアーティファクトに含めるべきではないファイルまたはディレクトリーにフィルターを設定するために使用されるため、Ansible Builder はこれらを取得しません。

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

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

追加情報

  • コレクションの作成に関する詳細は、Ansible 開発者ガイドの「コレクションの作成」を参照してください。

6.4. 自動化実行環境の作成

自動化実行環境定義ファイルでは、以下を指定します。
  • Ansible バージョン
  • Python バージョン (デフォルトはシステム Python)
  • 必要な Python ライブラリーのセット
  • ゼロ以上の Content Collection (任意)
  • その特定の Collection の Python 依存関係

環境に Collection のセットを指定する概念は、依存関係を解決し、インストールすることです。Collection 自体は、自動化実行環境を生成するマシンにインストールする必要はありません。

自動化実行環境は、この定義から構築され、コンテナーイメージが作成されます。これらのイメージの作成手順については、Ansible Builder のドキュメントを参照してください。

第7章 既存のコンテンツの移行

以下のセクションで、awx-manage コマンドを使用して、Red Hat Ansible Automation Platform 2.0 および自動化コントローラー 4.0 にアップグレードした後に、移行プロセスの追加手順を支援する方法を説明します。また、Ansible のバージョン間での移行についても確認してください。

7.1. 仮想環境を自動化実行環境に移行

Red Hat Ansible Automation Platform 2.0 および自動化コントローラー 4.0 にアップグレードしたら、移行プロセスの追加手順について、以下のセクションを使用します。

7.1.1. カスタムの仮想環境の構築

awx-manage コマンドを使用して、自動化コントローラーインスタンスの仮想環境を一覧表示できます。

手順

  1. 自動コントローラーインスタンスに SSH 接続して実行します。

    $ awx-manage list_custom_venvs

検出された仮想環境の一覧が表示されます。

# Discovered virtual environments:
/var/lib/awx/venv/testing
/var/lib/venv/new_env

To export the contents of a virtual environment, re-run while supplying the path as an argument:
awx-manage export_custom_venv /path/to/venv

7.1.2. カスタムの仮想環境に関連付けられたオブジェクトの表示

awx-manage コマンドを使用して、カスタムの仮想環境に関連付けられた組織、ジョブ、インベントリーソースを表示します。

手順

  1. 自動コントローラーインスタンスに SSH 接続して実行します。

    $ awx-manage custom_venv_associations /path/to/venv

関連付けられたオブジェクトの一覧が表示されます。

inventory_sources:
- id: 15
  name: celery
job_templates:
- id: 9
  name: Demo Job Template @ 2:40:47 PM
- id: 13
  name: elephant
organizations
- id: 3
  name: alternating_bongo_meow
- id: 1
  name: Default
projects: []

7.1.3. エクスポートするカスタムの仮想環境の選択

awx-manage export_custom_venv コマンドを使用して、エクスポートするカスタムの仮想環境を選択します。

手順

  1. 自動コントローラーインスタンスに SSH 接続して実行します。

    $ awx-manage export_custom_venv /path/to/venv

このコマンドにより、指定した仮想環境に含まれる pip freeze が表示されます。この情報は、Ansible Builder の requirements.txt ファイルにコピーして、新しい自動化実行環境イメージを作成するのに使用できます。

numpy==1.20.2
pandas==1.2.4
python-dateutil==2.8.1
pytz==2021.1
six==1.16.0

To list all available custom virtual environments run:
awx-manage list_custom_venvs
注記

'awx-manage list_custom_venvs' を実行して出力を減らしたときに -q フラグを渡します。

7.2. Ansible Core バージョン間の移行

Ansible Core のバージョン間で移行するには、Playbook、プラグイン、その他の Ansible インフラストラクチャーの他の部分を更新して、最新バージョンで機能するようにする必要があります。このプロセスでは、変更が Ansible Core の連続する各バージョンに対して行われる更新に対して検証されている必要があります。Ansible 2.9 から Ansible 2.11 に移行する場合は、最初に Ansible 2.10 の要件を満たしていることを確認し、そこから 2.11 に更新する必要があります。

7.2.1. Ansible 移植ガイド

Ansible 移植ガイド は、連続する Ansible バージョン間での動作変更に関する情報を提供する一連のドキュメントです。Ansible のバージョンから新しいバージョンに移行する場合は、ガイドを参照してください。

7.2.2. 追加情報

  • Ansible 2.8 から Ansible 2.9 における動作の変更については、「Ansible 2.9」を参照してください。
  • Ansible 2.9 から Ansible 2.10 における動作の変更については、「Ansible 2.10」を参照してください。

第8章 Automation content navigator によるコンテンツの実行

これで自動化実行環境が構築されたので、Ansible コンテンツナビゲーターを使用して、自動化コントローラーが実行するのと同じ方法でコンテンツが実行することを検証できます。

8.1. 自動化コンテンツナビゲーターを使用した Ansible Playbook の実行

コンテンツ作成者は、自動化コンテンツナビゲーターを使用して Ansible Playbook を実行し、各プレイとタスクの結果をインタラクティブに調べて、Playbook を検証またはトラブルシューティングすることができます。また、実行環境内で Ansible Playbook を実行して、実行環境なしでも、問題を比較し、トラブルシューティングすることもできます。

8.1.1. 自動化コンテンツナビゲーターからの Playbook の実行

自動化ナビゲーターのテキストベースのユーザーインターフェースで Ansible Playbook を実行して、タスクの実行を追跡し、各タスクの結果を詳しく調べることができます。

前提条件

  • Playbook
  • localhost または inventory プラグインを使用しない場合の、有効なインベントリーファイルです。

手順

  1. 自動化コンテンツナビゲーターの起動

    $ ansible-navigator
  2. Playbook を実行します。必要に応じて、ansible-navigator を ansible-navigator run simple-playbook.yml -i inventory.yml を実行して Playbook を直接実行することができます。

    $ :run
  3. インベントリーおよびその他のコマンドラインパラメーターを確認または追加します。

    INVENTORY OR PLAYBOOK NOT FOUND, PLEASE CONFIRM THE FOLLOWING
    ─────────────────────────────────────────────────────────────────────────
       Path to playbook: /home/ansible-navigator_demo/simple_playbook.yml
       Inventory source: /home/ansible-navigator-demo/inventory.yml
      Additional command line parameters: Please provide a value (optional)
    ──────────────────────────────────────────────────────────────────────────
                                                               Submit Cancel
  4. Tab キーを押して Submit に移動し、Enter キーを押します。実行中のタスクが表示されるはずです。

    navigator play list
  5. プレイ結果にステップインするプレイの横に番号を入力します。9 を超える数字の場合は :<number> と入力します。

    navigator task list

    自動化コンテンツナビゲーターで色を有効にしている場合は、失敗したタスクが赤で表示されることに注意してください。

  6. タスクの結果を確認するタスクの横に番号を入力します。9 を超える番号の場合は :<number> と入力します。

    navigator task output failed
  7. 必要に応じて、:doc と入力し、トラブルシューティングを支援するタスクで使用されるモジュールまたはプラグインのドキュメントを起動します。

    ANSIBLE.BUILTIN.PACKAGE_FACTS (MODULE)
      0│---
      1│doc:
      2│  author:
      3│  - Matthew Jones (@matburt)
      4│  - Brian Coca (@bcoca)
      5│  - Adam Miller (@maxamillion)
      6│  collection: ansible.builtin
      7│  description:
      8│  - Return information about installed packages as facts.
    <... output omitted ...>
     11│  module: package_facts
     12│  notes:
     13│  - Supports C(check_mode).
     14│  options:
     15│    manager:
     16│      choices:
     17│      - auto
     18│      - rpm
     19│      - apt
     20│      - portage
     21│      - pkg
     22│      - pacman
    
    <... output truncated ...>

8.1.2. 自動化コンテンツナビゲーターアーティファクトファイルを使用した Playbook の結果の確認

Automation コンテンツナビゲーターは、JSON アーティファクトファイルに Playbook 実行の結果を保存します。このファイルを使用して、Playbook の結果を他の人と共有したり、セキュリティーやコンプライアンスの理由で保存したり、後で確認してトラブルシューティングしたりできます。Playbook の実行を確認するためにアーティファクトファイルのみが必要になります。Playbook 自体またはインベントリーアクセスにアクセスする必要はありません。

前提条件

  • Playbook 実行からの自動化コンテンツナビゲーターアーティファクトの JSON ファイル。

手順

  • アーティファクトファイルによる自動化コンテンツナビゲーターの開始

    $ ansible-navigator replay simple_playbook_artifact.json
    1. Playbook の実行時に一致する Playbook の結果を確認します。

      navigator artifact replay

Playbook を実行した後と同じように、プレイとタスクの横に番号を入力して、それぞれにステップインして結果を確認できるようになりました。

第9章 まとめ

これで、特定の自動化のニーズに対応する自動化実行環境をカスタマイズし、コンテナーレジストリーで共有し、使用できるようになりました。

法律上の通知

Copyright © 2021 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.