Documentation

11. ジョブテンプレートの起動

Ansible Tower では、Tower API からのジョブテンプレートをもとに、あるいは tower-cli コマンドラインツールを使用してジョブを簡単に起動できます。

ジョブテンプレートを起動すると、以下の設定が行われます。

  • ジョブレコードを作成します。
  • ジョブテンプレート上の属性すべてをジョブレコードに指定し、その起動エンドポイント (「ランタイム」データ) で指定可能な特定のデータと統合します。
  • JT およびランタイムデータからの統合データで Ansible を実行します。

ランタイムデータは、ジョブテンプレートの ask_ _on_launch が True に設定されている場合にジョブテンプレートデータより優先されます。たとえば、ランタイムの認証情報は、ジョブテンプレートで ask_credential_on_launch が True に設定されている場合のみ受け入れられます。

API 経由でジョブテンプレートを起動する場合には、以下のワークフローに従ってください。

  • GET https://your.tower.server/api/v2/job_templates/<your job template id>/launch/: 応答には、ジョブテンプレートに関する情報を提供する job_template_data および defaults などのデータが含まれます。

  • 返されたデータに起動に必要なランタイムデータがないか確認します。また、起動エンドポイントの OPTIONS を検査すると、POST フィールドで許可されている内容を推測しやすくなる場合があります。

    警告

    特定のランタイム認証情報を指定すると、passwords_needed_to_start で提示されていないパスワードが必要になってくる場合があります。

    • passwords_needed_to_start: 必要なパスワードの一覧
    • credential_needed_to_start: ブール値
    • inventory_needed_to_start: ブール値
    • variables_needed_to_start: extra_vars ディクショナリー内に渡す必要のあるフィールド一覧
  • ユーザーが求めたランタイムデータでオプションで許可できるものがあるか、返されたデータを確認します。

    • ask_variables_on_launch: extra_vars 内の Ansible に渡す追加の変数を入力するようにユーザーに求めるかどうかを指定するブール値
    • ask_tags_on_launch: 起動時に job_tags の入力をユーザーに求めるかどうかを指定するブール値 (便宜上 skip_tags の使用が可能)
    • ask_job_type_on_launch: 起動時に job_type の入力をユーザーに求めるかどうかを指定するブール値
    • ask_limit_on_launch: 起動時に limit の入力をユーザーに求めるかどうかを指定するブール値
    • ask_inventory_on_launch: 起動時に関連の inventory フィールドの入力をユーザーに求めるかどうかを指定するブール値
    • ask_credential_on_launch: 起動時に関連の credential フィールドの入力をユーザーに求めるかどうかを指定するブール値
    • survey_enabled: 以下のジョブテンプレートの survey_spec Q&A 形式に準拠する追加の extra_vars の入力をユーザーに求めるかどうかを指定するブール値
  • 以前の手順で収集した必須データを使用して POST https://your.tower.server/api/v2/job_templates/<your job template id>/launch/ を実行します。このアクションの要求データで渡すことができる変数には以下が含まれます。

    • extra_vars: 調査の質問への回答など、ユーザーが指定する変数を含む JSON または YAML 形式のディクショナリーで表現する文字列 (エスケープした括弧)。
    • job_tags: 実行する playbook にコンマ区切りのタグ一覧を表現する文字列
    • limit: 稼働するホストまたはグループ (コンマ区切りリスト) を表現する文字列
    • inventory: このジョブランで使用するインベントリーの外部キーの整数値
    • credential: このジョブランで使用する認証情報の外部キーの整数値

POST は、ジョブに関するデータと、ランタイムデータが受け入れられるかどうかの情報を返します。ジョブ ID は、3.0 以前に記述されたツールとの互換性を保つために job フィールドで指定します。応答は以下のようになります。

{
  "ignored_fields": {
    "credential": 2,
    "job_tags": "setup,teardown"
  }
  "id": 4,
  ...more data about the job...
  "job": 4,
}

この例では、credential および job_tags の値を指定し、ジョブテンプレートの ask_credential_on_launchask_tags_on_launch は False と指定しました。ジョブテンプレートの作成者がランタイムの値を使用する許可を行わなかったので、これらは却下されました。

この応答でジョブに関する詳細を確認できます。更新済みのステータスを取得するには、ジョブページ /jobs/4 への GET 要求を行うか、応答内の url リンクに従う必要があります。キャンセル、再起動などの関連のリンクも含まれます。

注釈

非実行ノードでジョブをクエリーすると、result_stdout フィールドおよび関連の stdout ページでエラーメッセージ「stdout capture is missing」が表示されます。stdout を生成するには、関連の stdout ページに format=txt_download クエリーパラメーターを使用してください。これにより、stdout ファイルが作成され、ジョブへの更新がされるか、関連の std がジョブ出力に表示されます。

注釈

スキャンジョブに対して起動する際には、新規インベントリーを割り当てることはできません。スキャンジョブは固定のインベントリーに紐付けする必要があります。

注釈

このタイプの “scan” に/から起動する際は、ジョブタイプを変更できません。ask_job_type_on_launch オプションのみが起動時に “run” と “check” の切り替えが可能です。

11.1. tower-cli ジョブテンプレートの起動

Tower コマンドラインから、ジョブテンプレートの起動方法として tower-cli を使用できます。

tower-cli の起動に関するヘルプは以下を使用します。

tower-cli job launch --help.

ジョブテンプレートから起動するには、以下と同様に tower-cli を呼び出します。

API の使用例として、-v フラグを追加することもできます。

tower-cli job launch --job-template=4 -v