Documentation

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

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

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

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

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

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

  • GET https://your.tower.server/api/v1/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/v1/job_templates/<your job template id>/launch/ を実行します。このアクションの要求データで渡すことができる変数には以下が含まれます。

    • extra_vars: 調査の質問への回答など、ユーザーが指定する変数を含む JSON または YAML 形式のディクショナリーで表現する文字列 (エスケープした括弧)。
    • job_tags: 実行するプレイブックにコンマ区切りのタグ一覧を表現する文字列
    • 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” の切り替えが可能です。

10.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