はじめに

お久しぶりです。たそ(taso_int)です。
そう言えば、ネスぺを申し込みました。受けるからには受かる気で取り組みます。
あとは前回今年の目標にしてたところも触り始めてます。継続できれば…
今日はAnsible Automation Controller の REST APIについて触ります。
Ansible Automation ControllerはREST APIに対応しており、ジョブの起動などが出来たりします。
REST APIに対応しているおかげでAnsible Automation Controllerの操作設定ができるAnsibleのコレクションがあったりします。

環境

AWS

OS RHEL8.9
インスタンス m5.large
SG (少なくとも22 443 許可)

AAP

バージョン2.4(RHEL8用)

インストール方法はこちら

今回はAWSのEC2でAPIを実行しています。
Windows環境の場合はPostmanやWSLで行った方がいいです。
また出力を見やすくするためにjqコマンドを使えるようにしておくとよいです。
curl実行文 | jq . でJsonフォーマットとして出力してくれます。

参考情報

恐らく、上がRed Hatが提供しているリファレンスで2つ目がコミュニティのリファレンスのような気がしています。
わかる方いたら教えてください。
またhttps://controller_url/api/でも確認することが可能です。

下準備

APIを実行する際に認証用のTokenが必要になるので生成します。
アクセス→ユーザー→ユーザーを指定(今回はadmin)→トークンの順でクリックし、作成をします。
範囲は書き込みを指定して作成します。

そうするとToken情報が出るのでこれをメモリます。再表示はされないので注意してください。
以下の画像のようにトークンの一覧にパーソナルアクセストークンが出ていれば問題ないです。

今回はトークンを認証情報としてますが、ユーザーとパスワードによるBasic認証でも実行可能です。

実際に触る

ベース

curlでの実行の場合、基本的に以下のような構造になります。
-k オプションを入れているのはAnsible Automation Controller側がデフォルトのインストールだと自己証明書を設定してしまうためSSL証明書の検証を無視します。

curl -k -X HTTPメソッド \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer 生成したtoken" \
     https://controller_url/api/v2/hoge

例えば/api/v2を実行するとAPIのリストが出ます。

今回はジョブ(ジョブテンプレート)の起動と結果確認と結果のデバッグまでを書きます。
次回はジョブ(ワークフロー)の起動と結果確認と失敗したジョブの特定までを書きます。

ジョブの起動

試しにジョブテンプレートのDemo Job Templateを起動させてみます。
ジョブテンプレートを起動する際に各ジョブに割り振られているIDが必要になります。
このIDを知るには直接GUIで知りたいジョブテンプレートを開くとURLにIDが含まれています。
APIのみで完結させたい場合はapi/v2/job_templates/?search=ジョブ名でIDを調べることができます。
Demo Job Templateの場合は以下のような表記になります。

curl -k -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer 生成したtoken" \
     https://controller_url/api/v2/job_templates/?search=Demo+Job+Template

# 抜粋
  "results": [
    {
      "id": 7,
      "type": "job_template",
      "url": "/api/v2/job_templates/7/",
      "related": {
        "created_by": "/api/v2/users/1/",
        "modified_by": "/api/v2/users/1/",
        "labels": "/api/v2/job_templates/7/labels/",
        "inventory": "/api/v2/inventories/1/",
        "project": "/api/v2/projects/6/",
        "organization": "/api/v2/organizations/1/",
        "credentials": "/api/v2/job_templates/7/credentials/",
        "last_job": "/api/v2/jobs/3/",
        "jobs": "/api/v2/job_templates/7/jobs/",
        "schedules": "/api/v2/job_templates/7/schedules/",
        "activity_stream": "/api/v2/job_templates/7/activity_stream/",
        "launch": "/api/v2/job_templates/7/launch/",

      }

IDがわかったので、実際にジョブテンプレートを起動させます。エンドポイントはapi/v2/job_templates/id/launch/になります。
ここでのレスポンスとして返ってくるIDがテンプレートの実行履歴のID(以降、ジョブID)となり、これを使用してジョブの結果を調べます。

curl -k -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer 生成したtoken" \
     https://controller_url/api/v2/job_templates/7/launch

# 抜粋
{
  "job": 76,
  "ignored_fields": {},
  "id": 76,
  "type": "job",
  "url": "/api/v2/jobs/76/",
  "related": {
    "created_by": "/api/v2/users/1/",
    "modified_by": "/api/v2/users/1/",
    "labels": "/api/v2/jobs/76/labels/",
    "inventory": "/api/v2/inventories/1/",
    "project": "/api/v2/projects/6/",
    "organization": "/api/v2/organizations/1/",
    "credentials": "/api/v2/jobs/76/credentials/",
    "unified_job_template": "/api/v2/job_templates/7/",
    "stdout": "/api/v2/jobs/76/stdout/",
    "job_events": "/api/v2/jobs/76/job_events/",
    "job_host_summaries": "/api/v2/jobs/76/job_host_summaries/",
    "activity_stream": "/api/v2/jobs/76/activity_stream/",
    "notifications": "/api/v2/jobs/76/notifications/",
    "create_schedule": "/api/v2/jobs/76/create_schedule/",
    "job_template": "/api/v2/job_templates/7/",
    "cancel": "/api/v2/jobs/76/cancel/",
    "relaunch": "/api/v2/jobs/76/relaunch/"
  }

実際にGUIでも実行されていることがわかりました。画面上の数字とジョブIDが一致していますね。

ジョブの確認

このAPIは起動するだけなので、実際の結果は別で確認することが必要です。
結果のエンドポイントはapi/v2/jobs/id/になります。このIDはジョブIDを指します。

curl -k -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer 生成したtoken" \
     https://controller_url/api/v2/jobs/76/

# 抜粋
  "launch_type": "manual",
  "status": "successful",
  "execution_environment": 2,
  "failed": false,
  "started": "2024-02-18T12:53:27.139004Z",
  "finished": "2024-02-18T12:53:30.991682Z",

ここでstatusがsuccessfulかつfailedがTrueであれば成功になります。
statusがrunningであれば実行中でfailedであれば失敗になります。

ジョブの標準出力

ここまででジョブ(ジョブテンプレート)の起動と結果確認がわかりました。
念のため起動したジョブの標準出力を確認します。

エンドポイントはapi/v2/jobs/id/stdoutでテキストフォーマットにしたいので、?format=txtを追加します。

curl -k -X GET \
     -H "Authorization: Bearer 生成したtoken" \
     https://controller_url/api/v2/jobs/76/stdout/?format=txt

PLAY [Hello World Sample] ******************************************************

TASK [Gathering Facts] *********************************************************
ok: [localhost]

TASK [Hello Message] ***********************************************************
ok: [localhost] => {
    "msg": "Hello World!"
}

PLAY RECAP *********************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

見覚えのある標準出力が出ましたね。これでAPIでも実行から結果確認ができます。