16. プロジェクト¶
Project は、Ansible Playbook の論理コレクションです。
Playbook および Playbook ディレクトリーをプロジェクトのベースパスに手動で配置するか、または Playbook を automation controller がサポートするソースコード管理 (SCM) システム (例: Git、Subversion、および Red Hat Insights) に置くことで、Playbook と Playbook ディレクトリーを管理できます。Red Hat Insights プロジェクトを作成するには、Insights の修正の設定 を参照してください。
注釈
デフォルトで、プロジェクトのベースパスは /var/lib/awx/projects ですが、管理者によって変更されている可能性があります。これは /etc/tower/conf.d/custom.py で設定されます。設定が正しくないとインストールを無効にする可能性があるため、注意してこのファイルを編集してください。
プロジェクトページでは、現在利用可能なプロジェクトの一覧を表示します。デフォルトビューは折りたたまれており (縮小)、プロジェクト名とそのステータスが折りたたまれた状態で表示されますが、各エントリーの横にある矢印を使用して詳細情報を表示することができます。
一覧表示される各プロジェクトについて、各プロジェクトの隣にあるそれぞれのアイコンを使用して、最新の SCM リビジョンの取得 (
) し、プロジェクトの編集 (
)、またはプロジェクトの属性のコピー (
) を行うことができます。プロジェクトは、関連するジョブの実行中でも更新することができます。大規模なプロジェクト (約 10 GB) がある場合は、/tmp のディスク容量が問題になることがあります。
ステータス はプロジェクトの状態を示し、以下のいずれかになる可能性があります (特定のステータスタイプでビューをフィルターできることにも留意してください)。
保留中: ソースコントロールの更新は作成されていますが、まだキューに入れられていないか、または開始されていません。すべてのジョブ (ソースコントロールの更新に限らない) はシステムで実際に実行可能になるまで保留中の状態になります。ジョブが保留にされる理由には、依存関係にある実行中のジョブの終了を待機する必要があることや、設定された場所にジョブの実行容量が十分にないことがあります。
待機中: ソースコントロールの更新はキューに入れられており、実行を待機中です。
実行中: ソースコントロールの更新が進行中です。
成功: このプロジェクトの最後のソースコントロールの更新が成功しました。
失敗: このプロジェクトの最後のソースコントロールの更新が失敗しました。
エラー: 最後のソースコントロールの更新ジョブの実行に失敗しました (非推奨になる予定)。
取り消し: このプロジェクトの最後のソースコントロールの更新が取り消されました。
未更新: このプロジェクトはソースコントロール用に設定されていますが、更新されていません。
OK: プロジェクトはソースコントロール用に設定されていませんが、正常に実施されています (非推奨になる予定)。
不明: プロジェクトがプロジェクトベースパスの
/var/lib/awx/projectsにありません (手動またはソースコントロールで管理されたプロジェクトで適用可能です)。
注釈
認証情報タイプが「手動」のプロジェクトでは、SCM タイプの認証情報として再設定されない限りソースコントロールベースのアクションを更新したり、スケジュールしたりすることはできません。
注釈
他の作業アイテムが使用するアイテムを削除する場合は、メッセージが開き、削除されるアイテムと、削除の確認を促すプロンプトが表示されます。画面によっては、無効なアイテムや、過去に削除されたアイテムが含まれる場合があるので、それらのアイテムは実行に失敗します。以下は、これらのメッセージ例です。
16.1. 新規プロジェクトの追加¶
新規プロジェクトを作成するには、以下を実行します。
追加 ボタンをクリックします。これにより、プロジェクトの作成 ウィンドウが起動します。
以下の必須フィールドに適切な情報を入力します。
名前
説明 (オプション)
組織: プロジェクトには 1 つ以上の組織がなければなりません。ここで 1 つの組織を選択してプロジェクトを作成し、プロジェクトの作成後にさらに組織を追加できます。
デフォルトの実行環境 (オプション): 実行環境の名前を入力するか、既存の実行環境の一覧から検索して、このプロジェクトを実行します。詳細は Ansible Automation Platform Upgrade and Migration Guide の Execution Environments へのアップグレード を参照してください。
ソースコントロール認証情報タイプ: ドロップダウンメニューリストから、このプロジェクトに関連付けられている SCM タイプを選択します。後に続くセクションでは、選択したタイプにより、利用可能なオプションが異なります。詳細は、後続のセクションの 「Playbook の手動による管理」または「ソースコントロールの使用による Playbook の管理」を参照してください。
注釈
手動プロジェクトを追加する場合には、プロジェクトのルートフォルダー内の各プロジェクトパスは 1 つのプロジェクトにしか割り当てることができません。以下のメッセージが表示される場合には、プロジェクトパスが既存プロジェクトにまだ割り当てられていないことを確認してください。
All of the project paths have been assigned to existing projects, or there are no directories found in the base path.You will need to add a project path before creating a new project.
完了したら 保存 をクリックします。
16.1.1. Playbook の手動による管理¶
Playbook を保管する 1 つ以上のディレクトリーをプロジェクトのベースパス (例: /var/lib/awx/projects/) に作成します。
Playbook ファイルを作成し、これを Playbook ディレクトリーにコピーします。
Playbook ディレクトリーおよびファイルが、automation controller サービスを実行するのと同じ UNIX ユーザーおよびグループで所有されていることを確認します。
パーミッションが Playbook ディレクトリーおよびファイルについて適切であることを確認します。
プロジェクトパスを追加する際に問題がある場合は、プロジェクトディレクトリーおよびファイルのパーミッションおよび SELinux コンテキスト設定を確認します。
警告
Ansible Playbook ディレクトリーをベースプロジェクトパスに追加していない場合は、以下のメッセージが送信されます。
適切な Playbook ディレクトリーを作成し、SCM から Playbook をチェックアウトするか、または Playbook を適切な Playbook ディレクトリーにコピーしてこの問題を修正します。
16.1.2. ソースコントロールの使用による Playbook の管理¶
16.1.2.1. SCM タイプ - Git および Subversion¶
ソースコントロールを使用するように Playbook を設定するには、プロジェクトの 詳細 タブで以下を行います。
SCM タイプ ドロップダウンメニューリストから適切なオプション (Git または Subversion) を選択します。
以下のフィールドに該当する詳細を入力します。
SCM URL - ヒント
の例を参照してください。
SCM ブランチ/タグ/コミット: オプションで、ソースコントロール (Git または Subversion) からチェックアウトする SCM ブランチ、タグ、コミットハッシュ値、任意の参照 (ref)、リビジョン番号 (該当する場合) を入力します。コミットハッシュ値および参照の中には、次のフィールドでカスタムの refspec も指定しないと使用できないものがあります。空白のままにすると、デフォルトは HEAD になります。これは、このプロジェクトで最後にチェックアウトされたブランチ/タグ/コミットです。
SCM Refspec: このフィールドは git ソースコントロール専用のオプションであり、git の知識があり、問題なく使用できる上級ユーザーのみが、リモートリポジトリーからダウンロードする参照を指定する必要があります。詳細については、「job branch overriding」を参照してください。
SCM Credential (SCM 認証情報): 認証が必要な場合には、適切な SCM 認証情報を選択します。
SCM 更新オプション で起動動作を任意で選択します (該当する場合)。
クリーニング: 更新の実行前にローカルの変更を削除します。
更新時の削除: 更新の実行前にローカルリポジトリーを完全に削除します。リポジトリーのサイズによっては、更新の完了までにかかる時間が大幅に増大します。
起動時のリビジョン更新: リモートソースコントロールのプロジェクトのリビジョンを現在のリビジョンに更新し、ロールディレクトリーのキャッシュを Galaxy または Collections から取得します。Automation controller は、ローカルリビジョンが一致し、ロールおよびコレクションが最終更新で最新の状態になるようにします。また、プロジェクトの同期よりも迅速にジョブを起動した場合にジョブがオーバーフローになるのを回避するために、これを選択して、プロジェクトが同期するまでにキャッシュする具体的な秒数について、キャッシュのタイムアウトを設定できます。
ブランチの上書きを許可する: このプロジェクトを使用するジョブテンプレートが、指定の SCM ブランチまたは、プロジェクトのリビジョン以外のリビジョンで起動できるようにします。詳細については、「job branch overriding」を参照してください。
保存 をクリックしてプロジェクトを保存します。
ちなみに
GitHub リンクを使用すると、Playbook を簡単に使用できます。使用を開始するには、
helloworld.ymlファイル (https://github.com/ansible/tower-example.git より利用可能) を使用します。このリンクから、Ansible Tower Quick Start Guide の説明に従って手動で作成されたものに非常に似ている Playbook を追加することができます。これを使用しても、システムが変更されたり、破損することはありません。
16.1.2.2. SCM タイプ - Red Hat Insights¶
Red Hat Insights を使用するように Playbook を設定するには、プロジェクトの 詳細 タブで以下を実行します。
SCM タイプ ドロップダウンメニューリストから Red Hat Insights を選択します。
Red Hat Insights では、認証に認証情報が必要です。Red Hat Insights で使用できるように、認証情報 フィールドから適切な認証情報を選択します。
SCM 更新オプション で起動動作を任意で選択します (該当する場合)。
クリーニング: 更新の実行前にローカルの変更を削除します。
更新時の削除: 更新の実行前にローカルリポジトリーを完全に削除します。リポジトリーのサイズによっては、更新の完了までにかかる時間が大幅に増大します。
起動時のリビジョン更新: リモートソースコントロールのプロジェクトのリビジョンを現在のリビジョンに更新し、ロールディレクトリーのキャッシュを Galaxy または Collections から取得します。Automation controller は、ローカルリビジョンが一致し、ロールおよびコレクションが最終更新で最新の状態になるようにします。また、プロジェクトの同期よりも迅速にジョブを起動した場合にジョブがオーバーフローになるのを回避するために、これを選択して、プロジェクトが同期するまでにキャッシュする具体的な秒数について、キャッシュのタイムアウトを設定できます。
保存 をクリックしてプロジェクトを保存します。
16.1.2.3. SCM タイプ - リモートアーカイブ¶
リモートアーカイブを使用する Playbook により、バージョン付けされたアーティファクトを生成するビルドプロセスまたはリリースに基づいてプロジェクトを提供することができます。これには、単一のアーカイブ内のそのプロジェクトのすべての要件が含まれます。
リモートアーカイブを使用するように Playbook を設定するには、プロジェクトの 詳細 タブで以下を行います。
SCM タイプ ドロップダウンメニューリストから リモートアーカイブ を選択します。
以下のフィールドに該当する詳細を入力します。
SCM URL - GitHub Release、Artifactory に保存されているビルドアーティファクトなど、リモートアーカイブへの URL を要求し、それをプロジェクトパスに展開して使用します。
SCM Credential (SCM 認証情報): 認証が必要な場合には、適切な SCM 認証情報を選択します。
SCM 更新オプション で起動動作を任意で選択します (該当する場合)。
クリーニング: 更新の実行前にローカルの変更を削除します。
更新時の削除: 更新の実行前にローカルリポジトリーを完全に削除します。リポジトリーのサイズによっては、更新の完了までにかかる時間が大幅に増大します。
起動時のリビジョン更新: このオプションは、プロジェクトのリビジョンをリモートソースコントロールの現在のリビジョンに更新し、ロールディレクトリーを Galaxy または Collections からキャッシュするため、推奨されません。
ブランチの上書きを許可する: このオプションは、このプロジェクトを使用するジョブテンプレートが、指定の SCM ブランチ、またはプロジェクトのリビジョン以外のリビジョンで起動できるようするため推奨されません。
注釈
この SCM タイプは、アーティファクトの変更のない概念をサポートすることが意図されているため、(少なくてもロールに対して) Galaxy 統合を無効にすることが推奨されます。
保存 をクリックしてプロジェクトを保存します。
16.2. ソースコントロールからのプロジェクトの更新¶
プロジェクトを選択し、
ボタンをクリックして、既存の SCM ベースのプロジェクトを更新します。
注釈
ソースコントロールを使用するためにプロジェクト設定を追加した直後に「同期」が開始され、設定されたソースコントロールからプロジェクト詳細の取り込みが実行されることに注意してください。
ステータス 列のプロジェクトのステータスをクリックすると、更新プロセスの詳細が表示されます。
16.3. パーミッションの使用¶
このプロジェクトに割り当てられており、プロジェクト、インベントリー、ジョブテンプレート、およびその他の automation controller 要素の読み取り、変更、および管理を行う機能を提供するパーミッションのセット (ロールベースのアクセス制御) は、権限とも呼ばれています。
詳細 タブの隣の アクセス タブを使用して、プロジェクトのパーミッションにアクセスします。この画面では、現在このプロジェクトに対してパーミッションがあるユーザー一覧を表示します。この一覧は、ユーザー名、名 または 姓 別で並び替え、検索が可能です。
16.3.1. パーミッションの追加¶
アクセス タブで 追加 ボタンをクリックします。
追加するユーザーまたはチームを選択し、**次へ**をクリックします。
リストから 1 つまたは複数のユーザーを選択します。これには、メンバーとして追加するユーザーの隣にあるチェックボックスをクリックして、次へ をクリックします。
この例では、追加するユーザーが 2 つ選択されています。
選択したユーザーやチームに割り当てるロールを選択します。役割の一覧は、下にスクロールして確認してください。リソースによって利用できるオプションが異なります。
保存 ボタンをクリックすると、選択したユーザーまたはチームにロールが適用され、メンバーとして追加されます。
ユーザー/チームの追加ウィンドウが閉じ、各ユーザーやチームに割り当てられた更新済みのロールが表示されます。
特定ユーザーのロールを削除するには、そのリソースの横にある「関連付けの解除」(x) ボタンをクリックします。
これにより確認ダイアログが起動し、関連付けの解除を確定するように求められます。
16.4. 通知の使用¶
通知 タブをクリックすると、設定した通知の統合を確認できます。
トグルを使用して、特定のプロジェクトで使用する通知を有効または無効にします。詳細については、「通知の有効化と無効化」を参照してください。
通知が設定されていない場合は、左ナビゲーションバーの 通知 リンクから設定し、新しい通知を作成することができます。
さまざまな通知タイプの設定に関する追加の情報は、「通知タイプ」を参照してください。
16.5. ジョブテンプレートの使用¶
ジョブテンプレート をクリックし、ジョブテンプレートや、このプロジェクトに関連付けられているワークフローテンプレートを追加および確認できます。
そのテンプレートを使用して実行したジョブのステータスをクリックすると、その詳細やその他の有用な情報を見ることができます。このリストは、さまざまな条件で並べ替えたり、検索を実行して目的のテンプレートを絞り込むことができます。
このビューから、テンプレートの設定を起動 (
) または編集 () できます。
16.7. Ansible Galaxy サポート¶
プロジェクト更新の終了時に、automation controller は、<project-top-level-directory>/roles/requirements.yml の roles ディレクトリーで requirements.yml という名のファイルを検索します。このファイルが見つかると、以下のコマンドが自動的に実行されます。
ansible-galaxy role install -r roles/requirements.yml -p <project-specific cache location>/requirements_roles -vvv
このファイルを使用すると、Galaxy ロールや、他のリポジトリー内のロールを参照できます。このロールは、独自のプロジェクトと組み合わせてチェックアウトできます。この Ansible Galaxy サポートを追加することで、この結果を達成するために git サブモジュールを作成する必要がなくなります。SCM プロジェクト (およびロール/コレクション) がプライベートジョブ環境からプルされ、そこから実行される場合は、/tmp 内のプロジェクトに固有の <private job directory> がデフォルトで作成されます。ただし、設定ウィンドウのジョブの設定タブで、お使いの環境に基づいて別の ジョブの実行パス を指定することができます。
キャッシュディレクトリーはグローバルプロジェクトディレクトリー内のサブディレクトリーで、コンテンツはキャッシュの場所から <job private directory>/requirements_roles の場所にコピーできます。
デフォルトでは、automation controller にシステム全体の設定があり、この設定で SCM プロジェクト用に roles/requirements.yml ファイルからロールを動的にダウンロードできます。ロールのダウンロードを有効にする の切り替えボタンを オフ にすることで、設定メニューの **ジョブ設定**画面にあるこの設定をオフにできます。
プロジェクトの同期が実行するたびに、automation controller は、プロジェクトのソースと、Galaxy や Collections のロールがプロジェクトで古くなっているかどうかを判断します。プロジェクトの更新により、更新内のロールがダウンロードされます。
ジョブがアップストリームロールに加えられた変更を取得する必要がある場合は、プロジェクトを更新すると、これが確実に行われます。ロールの変更は、新しいコミットが provision-role ソースコントロールにプッシュされたことを意味します。この変更をジョブで有効にするために、playbooks リポジトリーに新しいコミットをプッシュする必要はありませんが、ロールをローカルキャッシュにダウンロードするプロジェクトを更新する 必要があります。たとえば、ソースコントロールに 2 つの git リポジトリーがあるとします。1 つ目は playbooks で、automation controller のプロジェクトはこの URL を指しています。2 つ目は provision-role であり、playbooks git リポジトリー内の roles/requirements.yml ファイルにより参照されます。
つまり、ジョブは、すべてのジョブの実行前に最新のロールをダウンロードします。ロールとコレクションは、パフォーマンス上の理由でローカルでキャッシュされます。また、プロジェクトの SCM 更新オプション で 起動時のリビジョン更新 を選択し、各ジョブの実行前にアップストリームロールを再ダウンロードするようにする必要があります。
更新は同期よりもはるかに前のプロセスで行われるため、これによりエラーと詳細がより速く、より論理的な場所で詳細が表示されます。
requirements.yml の構文に関する詳細情報と例については、Ansible ドキュメントの「role requirements section」セクションを参照してください。
16.7.1. Isolation functionality and variables¶
Automation controller uses container technology to isolate jobs from each other. By default, only the current project is exposed to the container running a job template.
You may find that you need to customize your playbook runs to expose additional directories. To fine tune your usage of job isolation, there are certain variables that can be set.
By default, automation controller will use the system's tmp directory (/tmp by default) as its staging area. This can be changed in the Job Execution Path field of the Jobs settings screen, or in the REST API at /api/v2/settings/jobs:
AWX_ISOLATION_BASE_PATH = "/opt/tmp"
The host trusted cert store is exposed to execution environments by default:
AWX_ISOLATION_SHOW_PATHS = [
'/etc/pki/ca-trust:/etc/pki/ca-trust:O',
'/usr/share/pki:/usr/share/pki:O',
]
If there are any additional directories that should specifically be exposed from the host to the container that playbooks run in, you can specify those in the Paths to Expose to Isolated Jobs
field of the Jobs setting scren, or in the REST API at /api/v2/settings/jobs:
AWX_ISOLATION_SHOW_PATHS = ['/list/of/', '/paths']
注釈
Playbook が
/var/lib/awx/.sshで定義した鍵や設定を使用する必要がある場合には、このファイルを主要ファイルとして、AWX_ISOLATION_SHOW_PATHSに追加してください。
The above fields can be found in the Jobs Settings window:
注釈
プライマリー Galaxy Server のユーザー名* フィールドおよび プライマリー Galaxy Server のパスワード フィールドは automation controller 3.8 では設定できなくなりました。Galaxy または Automation Hub にアクセスするには、代わりにトークンを使用することが推奨されます。
16.8. コレクションのサポート¶
Automation controller は、ジョブの実行時におけるプロジェクト固有の Ansible コレクションをサポートします。SCM に collections/requirements.yml という名前のコレクション要件ファイルを指定すると、automation controller は、ジョブ実行前に暗黙的なプロジェクトを同期する際に、そのファイルで指定したコレクションをインストールします。コレクションの要件は次のように指定します。
ansible-galaxy collection install -r requirements.yml -p <job tmp location>
デフォルトでは、automation controller にシステム全体の設定があり、この設定で SCM プロジェクト用に collections/requirements.yml ファイルからコレクションを動的にダウンロードできます。コレクションのダウンロードを有効にする の切り替えボタンを オフ にすることで、設定メニューの ジョブ設定 タブにあるこの設定をオフにできます。
ロールとコレクションはパフォーマンス上の理由からローカルにキャッシュされるため、以下を確実に行うためには、プロジェクトの SCM 更新オプションで 起動時のリビジョン更新 を選択する必要があります。
16.8.1. Hub でのコレクションの使用¶
automation controller がコレクションコンテンツのデフォルトのソースとして Automation Hub を使用できるようにするには、Automation Hub UI で API トークンを作成する必要があります。これにより、automation controller 内で指定することができるようになります。非公開の Automation Hub コレクションまたは公開 Automation Hub コレクションに接続できますが、指定する URL のみが異なります。
https://cloud.redhat.com/ansible/automation-hub/token に移動し、Load token をクリックします。
コピーアイコンをクリックして、API トークンをクリップボードにコピーします。
公開 Automation Hub を使用するには、コピーしたトークンを使用して Automation Hub 認証情報を作成し、トークンページの Server URL フィールドおよび SSO URL フィールドにある URL を指定します。
Galaxy Server URL =
https://cloud.redhat.com/api/automation-hub/認証サーバー URL =
https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
非公開の Automation Hub を使用するには、ローカルの Automation Hub のリポジトリー管理ダッシュボードから取得したトークンを使用して Automation Hub 認証情報を作成し、以下のように公開されたリポジトリーの URL を指定します。
異なる名前空間/コレクションで異なるリポジトリーを作成できます。Automation Hub のリポジトリーごとに、別の Automation Hub 認証情報を作成する必要があります。https://$<hub_url>/api/galaxy/content/<repo you want to pull from> 形式の Automation Hub UI から、Ansible CLI URL を 認証情報の作成 フォームの Galaxy Server URL フィールドにコピーします。
Automation Hub UI 固有の手順については、「Managing Red Hat Certified and Ansible Galaxy Collections in Ansible Hub」を参照してください。
Automation Hub からコンテンツの同期が可能な組織に移動し、新しい Automation Hub 認証情報を組織に追加します。このステップでは、各組織を。コンテンツを使用できる Automation Hub 認証情報 (つまりリポジトリー) に関連付けることができます。
注釈
リポジトリーが 2 つあるとします。
Prod:
Namespace 1およびNamespace 2(それぞれコレクションAおよびBが含まれます (namespace1.collectionA:v2.0.0およびnamespace2.collectionB:v2.0.0)Stage: コレクション
AのみがあるNamespace 1(Automation Hub のnamespace1.collectionA:v1.5.0)。Prod および Stage のリポジトリー URL があります。
それぞれに Automation Hub 認証情報を作成できます。次に、さまざまな組織にさまざまなレベルのアクセスを割り当てることができます。たとえば、開発者組織が両方のリポジトリーにアクセスできるのに対し、運用組織は |ah|の Prod リポジトリーにのみアクセスできるようにすることができます。
Automation Hub UI 固有の手順については、「Managing User Access in Ansible Hub」を参照してください。
Automation Hub に自己署名証明書がある場合は、トグルをクリックして設定 Ansible Galaxy SSL 証明書の検証を無視する を有効にします。署名した証明書を使用する 公開 Automation ハブ では、代わりにトグルをクリックして無効にします。これは、グローバル設定になります。
ソースリポジトリーが
collections/requirements.ymlファイルにある要件ファイルに必要なコレクションを指定するプロジェクトを作成します。Ansible のドキュメント https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#install-multiple-collections-with-a-requirements-file で説明されている構文を参照してください。
プロジェクトリストのビューで
をクリックして、このプロジェクトに対して更新を実行します。Automation controller は collections/requirements.ymlファイルから Galaxy コレクションを取得し、それを変更されたものとして報告します。このプロジェクトを使用するジョブテンプレートに対してコレクションがインストールされます。
注釈
Galaxy またはコレクションから更新が必要な場合は、必要なロールをダウンロードし、/tmp ファイルでより多くの領域を消費する同期が実行されます。大規模なプロジェクト (約 10 GB) があると、/tmp のディスク容量が問題になる可能性があります。
コレクションの詳細は、「Using Collections」を参照してください。Red Hat がこれらの公式コレクションのいずれかを公開する方法 (automation controller のインストールを直接自動化するために使用できます) は、AWX Ansible Collection のドキュメントを参照してください。このページは、Red Hat Ansible Automation Platform サブスクリプションでご利用になれるため、Red Hat のカスタマー認証情報を使用してアクセスしてください。