Ansible
Semaphore UI を使用すると、Ansible の playbook を実行できます。そのためには、Ansible Playbook テンプレートを作成する必要があります。
- タスクテンプレート セクションに移動し、新しいテンプレート、続いて Ansible Playbook をクリックします。
- テンプレートを設定します。
テンプレートでは、次のパラメーターを指定できます。
- リポジトリ
- playbook ファイルのパス
- 作業ディレクトリ（任意）
- インベントリ
- 変数グループ
- Vault
- 追加の CLI 引数（tags、skip-tags、limit、詳細度）
- 環境変数
作業ディレクトリ
作業ディレクトリ を使用すると、テンプレートのリポジトリのサブディレクトリから Ansible コマンドを実行できます。リポジトリルートからの相対パスを入力してください。たとえば ansible.cfg が <repository>/automation に保存されている場合は、automation と入力します。絶対パスやリポジトリ外のパスは拒否されます。省略した場合、Semaphore はリポジトリルートを使用します。
作業ディレクトリは、プロセスのカレントディレクトリに依存する Ansible の動作に影響します。Ansible の設定ファイルの検索順序には、カレントディレクトリの ansible.cfg が含まれます。また、作業ディレクトリは追加の CLI 引数に含まれる相対パスの解決にも影響します。例としては --extra-vars @vars.yml や --private-key key.pem があります。playbook とファイルインベントリのパスは、引き続きそれぞれのリポジトリルートからの相対パスとして扱われます。
作業ディレクトリを変更しても、それだけではそのディレクトリの roles/ や collections/ サブディレクトリが Ansible の検索パスに追加されるわけではありません。playbook を基準としたロールの検出や playbook に隣接するコレクションは、引き続き playbook の場所を 基準とします。ただし、選択された ansible.cfg が roles_path や collections_path を設定している場合は、作業ディレクトリがこれらの検出に間接的に影響することがあります。
テンプレートの種類
ansible-playbook テンプレートは、次のいずれかの種類になります。
タスク
指定したパラメーターで、指定した playbook を実行するだけのものです。
limit 機能を使って API 呼び出しからテンプレートを起動する場合は、必ず Ansible プロンプト: Limit オプションを有効にしてください。有効にしないと、API 呼び出しで指定した limit は無視されます。API でトリガーされたタスクの場合、これによって対話的なプロンプトが表示されることはなく、タスクは無人で実行されます。
ビルド
この種類のテンプレートは、アーティファクトを作成するために使用します。アーティファクトの開始バージョンは、テンプレートのパラメーターで指定できます。実行ごとにアーティファクトのバージョンが増加します。
Semaphore はアーティファクトを標準でサポートしているわけではなく、タスクのバージョニングのみを提供します。アーティファクトの作成は自分で実装する必要があります。その方法については CI/CD の記事を参照してください。
デプロイ
この種類のテンプレートは、アーティファクトを対象のサーバーへデプロイするために使用します。各 deploy テンプレートは、1 つの build テンプレートに関連付けられます。
これにより、特定のバージョンのアーティファクトをサーバーへデプロイできます。
テンプレートのオプション
スケジュール
テンプレートの設定で cron スケジュールを指定すると、タスクのスケジュール実行を設定できます。cron 式の形式についてはドキュメントを参照してください。
リポジトリに新しいコミットが追加されたときにタスクを実行する
cron を使用して、リポジトリの新しいコミットを定期的に確認し、コミットが追加されたときにタスクをトリガーできます。
たとえば、アプリのソースコードが git リポジトリにある場合、それを リポジトリ に追加し、新しいコミットに対してビルドタスクをトリガーできます。
tags、skip-tags、limit
テンプレートは、次の Ansible CLI オプションに対応しています。
--tags--skip-tags--limit
これらはテンプレートで設定でき、タスクの作成時に上書きできます。これらの値を API 経由で渡す予定がある場合は、対応するプロンプトが有効になっていることを確認してください。
Galaxy の requirements
playbook を実行する前に、Semaphore は playbook のディレクトリ、リポジトリルート、およびそれらの roles/ と collections/ サブディレクトリにある requirements.yml ファイルから、ansible-galaxy install --force を使ってロールとコレクションをインストールします。
実行ごとに再インストールしないように、Semaphore は各 requirements ファイルのチェックサムを保存し、ファイルが変更されたときにのみインストールを再実行します。この動作は、Ansible プロンプト の下にある折りたたみ可能な Galaxy インストールオプション セクションの 2 つのテンプレートオプションで制御します。
- Galaxy のインストールをスキップ —
ansible-galaxyをまったく実行しません。requirements がランナーのイメージにあらかじめインストールされている場合に使用します。 - Galaxy のインストールを強制 — 保存されたチェックサムを無視して、常に
ansible-galaxy install --forceを実行します。requirements ファイルが変化する対象（たとえばタグではなくブランチ）を指している場合で、実行ごとに最新バージョンを取得したいときに使用します。
Galaxy のインストールをスキップ は、セクション下部の プロンプト にある同名のチェックボックスを有効にすると、タスクの実行フォームに表示できます。プロンプトが有効な場合、実行時に選択した値がテンプレートの既定値を上書きします。
Galaxy の追加引数
ロールのインストール引数 と コレクションのインストール引数（Ansible プロンプト の下にある折りたたみ可能な Galaxy インストールオプション セクション内。既定では折りたたまれており、横のカウンターにはカスタマイズされている Galaxy 設定の数が表示されます）は、それぞれ ansible-galaxy role install と ansible-galaxy collection install にフラグを追加します。この 2 つのサブコマンドは受け付けるフラグが異なるため、別々に設定します。たとえば --pre はコレクションに対してのみ有効です。
各エントリは 1 つの argv トークンです。値はインライン（--timeout=60）でも、次のエントリとして（--timeout、60）でも指定できます。受け付けられるフラグは次のものだけです。
| 対象 | フラグ |
|---|---|
| 両方 | -c/--ignore-certs、-f/--force、--force-with-deps、-i/--ignore-errors、-n/--no-deps、-s/--server <url>、--timeout <seconds>、-v…-vvvv/--verbose |
| ロールのみ | -g/--keep-scm-meta |
| コレクションのみ | --pre、-U/--upgrade、--offline、--no-cache、--clear-response-cache、--disable-gpg-verify、--keyring <path>、--signature <url>、--required-valid-signature-count <n>、--ignore-signature-status-code(s) <code> |
それ以外の引数は、テンプレートの保存時に拒否されます。特に --token/--api-key は、コマンドライン引数がプロセス一覧から見えてしまうため許可されていません。Galaxy の認証情報は、代わりに変数グループ内の環境変数（たとえば ANSIBLE_GALAXY_SERVER_<NAME>_TOKEN）で設定してください。requirements ファイル（-r）は Semaphore が設定します。また、インストール先のパス（-p、--roles-path、--collections-path）は、テンプレートがリポジトリの外に書き込めないように意図的に受け付けていません。代わりに ansible.cfg で roles_path/collections_path を設定するか、ANSIBLE_ROLES_PATH/ANSIBLE_COLLECTIONS_PATH を使用してください。
並列度 (--forks / -f)
Ansible が並列に接続するホスト数は、テンプレートの 追加の CLI 引数 に --forks または
-f を渡して制御します。引数は有効な JSON である必要があります。
個別のトークンの配列を使用してください。
["--forks", "10"]
短縮形も使用できます。
["-f", "10"]
テンプレートで タスクでの引数の上書きを許可 が有効になっている場合、タスクは
実行時に独自の forks の値を指定できます。Ansible はテンプレートとタスクの
両方の引数を受け取り、コマンドラインの最後にある --forks / -f が有効になります。
引数が有効な JSON でない場合、タスクは実行開始前に、内容を説明する バリデーションエラーとともに失敗します。
認証
playbook 内のホストに対する認証は、インベントリのキーストアにあるユーザー参照を使用して行われます。SSH に使用するユーザーは、キーストア要素の任意指定のユーザーによって決まります。
複数の vault パスワード
キーストアから複数の Vault パスワードをテンプレートに関連付けられます。実行時に、Ansible は指定されたパスワードを使って復号を試みます。
詳細度レベル
トラブルシューティングに役立てるため、テンプレートやタスクのフォームからタスクごとに Ansible の詳細度（たとえば -v、-vvv）を調整できます。