レッドハットの杉村です。Ansible のテクニカルサポートをしています。毎月1つは何か書くことを目標にしています。
今月は Ansible Automation Controller (旧称 Ansible Tower) で扱うプロジェクトについて、特に Git との連携の観点から少々解説しようと思います。今回は Controller 4.0.0 で説明しますが、従来の Ansible Tower 3.8 でも新機能や新画面を除いては同様の動きをします。
プロジェクトに含まれるもの
プロジェクトは Ansible が実行しようとする処理をまとめたディレクトリやファイルです。例を挙げるとこのような構成になっています。プレイブックやダイナミックインベントリのための定義などが含まれています。
Controller のサーバ上では、/var/lib/awx/projects/ ディレクトリ以下に格納されます。プロジェクトはジョブを実行するたびに /tmp ディレクトリにまるごとコピーされ、複数のジョブを起動してもお互いに影響しないようになっています。
この毎回まるごとコピーされる仕様は、ジョブ間のリソースの競合によるロックをできるだけ排除するために Tower 3.6 から導入されました。そのため、プロジェクトのディレクトリは大きくしすぎないようにすることをお勧めします。例えば GBytes の大きさにもなる OS の ISO イメージをプロジェクト内に置いておくというような使い方は避けるようにしてください。
プロジェクトはソースコントロールシステム (SCM) から取得して管理することが想定されています。いくつかの種類に対応しています。
- Manual (直接ディレクトリを /var/lib/awx/projects/ 以下に作成して配置)
- Git
- Subversion
- Red Hat Insights (先月書いた記事のものです)
- Remote Archive (tar.gz や zip にまとめたものを Git などに置いて使う)
ここでは、主に Git を使ったプロジェクトについて紹介します。
プロジェクトを使うもの
プロジェクトはいくつかの場面で使われます。
ジョブテンプレート
これがもっとも一般的な利用方法で、プレイブックを実行するためのものです。プレイブックを1つ以上含むプロジェクトを選択すると、Playbook のフォームのプルダウンから選択できるようになります。
ワークフローテンプレート
ワークフローテンプレートは処理をノードとして組み合わせてワークフローを作る機能です。
プロジェクトを同期してジョブテンプレートを実行するというようなものを作ってみますとこのようになります。
ただ、これはいい例ではありません。普通はこのようなワークフローを作らなくても、プロジェクトに設定をすることで、ジョブテンプレートを実行するときにプロジェクトを更新させることができます。ワークフローにするときは例えば間に承認プロセスを挟みたい場合や、複数のジョブテンプレートを組み合わせたい場合などが考えられます。
インベントリーソース
プロジェクトはインベントリソースとしても使うことができます。インベントリは Ansible がアクセスする処理対象を設定するものなのですが、動的にクラウドサービスなどから条件を指定して接続先の情報を取得することができます。
こちらのスクリーンショットのようにさまざまなサービスからの取得に対応していますが、プロジェクトの中にインベントリの設定ファイルを置くことで、独自にインベントリプラグインを利用して処理対象を取り出していくことができます。単にインベントリ情報を JSON や INI ファイルで記述したものを Git で管理して、都度更新しながら使うという使い方もできます。
プロジェクトの設定による違い
ジョブテンプレートを実行したときには対応するプロジェクトディレクトリが /var/lib/awx/projects/ ディレクトリにすでにあるかどうかを確認し、取得していなかったときには Git から取ってくるという動きをします。
プロジェクトにはオプションがいろいろとあります。
クリーニング
普通の使い方ではここを意識する必要はないのですが、プロジェクトディレクトリに Controller のサーバ内で変更を加えた場合には Git の元のリポジトリと競合する場合がありますので、このオプションを有効にしておくとローカルの変更を戻してから同期処理を進めるようになります。
削除
プロジェクトディレクトリを完全に削除してから再度全体を同期します。例えばリポジトリを再構成して連続性がなくなった場合には、履歴情報の管理が崩れますので一旦全部削除してからやり直すことになります。
サブモジュールを追跡する
git submodule update --remote
相当の処理を実行します。
起動時のリビジョン更新
ジョブを起動したときに git update
やそれに付随する処理を実行します。毎回最新のプレイブックを使って処理を実行したいときにはここを有効にしておくことで、ワークフローを構成しなくても自動的に更新してからジョブを実行することができます。
ブランチの上書き許可
プロジェクト側ではまず git clone
しますが、このオプションを有効にしてプロジェクトを同期しますと、ジョブテンプレート側でもブランチを選択して指定することができます。
複数のブランチを管理する Git リポジトリから一つのプロジェクトとして同期して、ジョブテンプレートを複数作ってそれぞれ使い分けたいというような場合に利用いただけます。本番環境と検証環境で分ける、などが考えられます。
プロジェクト外の roles や collections の利用
Git のリポジトリの中に roles/requirements.yml や collections/requirements.yml ファイルを置くことで、プロジェクトの同期時に ansible-galaxy コマンドを実行してプロジェクトの外から roles や collections を取ってくるということができます。具体的には、これらのコマンドをそれぞれ実行します。
$ ansible-galaxy role install -r roles/requirements.yml -p <project-specific cache location>/requirements_roles -vvv $ ansible-galaxy collection install -r requirements.yml -p <job tmp location>
こちらの記事もご覧ください。
設定
「ジョブ設定」の画面にはこのプロジェクトについての設定がいくつかあります。
Default Project Update Timeout
プロジェクトの更新にタイムアウトを設定します。
Run Project Updates With Higher Verbosity
プロジェクトの更新ジョブの結果を詳細に出力します。プロジェクトの更新も内部的にはプレイブックを実行しています。
このプレイブックは /var/lib/awx/venv/awx/lib/python3.8/site-packages/awx/playbooks/project_update.yml にありますので、もしご興味ありましたらご覧ください。
Ignore Ansible Galaxy SSL Certificate Verification
Collections を取ってくる先が private Automation Hub などに設定されていて TLS/SSL の証明書を自己署名にしているなどの理由で検証ができない場合には、このオプションを有効にすることで証明書の検証をしないようにすることができます。
Enable Role Download
このオプションをオフにしますと、roles/requirements.yml がプロジェクトに含まれていても取りに行かなくなります。
Enable Collection(s) Download
上のオプションと同様に、このオプションをオフにしますと、collections/requirements.yml がプロジェクトに含まれていても取りに行かなくなります。
Follow symlinks
ジョブテンプレートの設定ではプロジェクトからプレイブックを検出する処理を行うのですが、このオプションを有効にしますと、プロジェクトに含まれる symlink も追跡していくようになります。間違った設定が入っているときにはループしますので、これは有効にしないことをおすすめします。
おわりに
Ansible Automation Platform の Controller (旧 Tower) で使われるプロジェクトについて一通り解説しました。
原理的にはプレイブック一式を Git で管理して取ってきて実行するということだけではあるのですが、Git との連携は利用目的や運用方法に応じて細かく制御することができるので、いろいろ使い方を検討いただけましたらと思います。
プレイブックを更新したときにどうプロジェクトに反映していくのがいいのかということもよく話題になりますが、「起動時のリビジョン更新」を有効にしていただいてジョブを実行したときの更新に任せることがまずは基本的な使い方です。他の方法が適している場合もあると思いますので、ここで解説したオプションを組み合わせることで実現できるかどうか、いろいろとご検討ください。
Ansible Automation Platform は Developer Subscription でもお試しいただけますので、ご興味持たれましたら試してみてください。
Happy Automation!