はじめに

Automation Controller 4.4 (AAP 2.4)で、一括でドカッと処理させたいときに便利な Bulk API というものが導入されました。

ホストの一括追加 /api/v2/bulk/host_create/
ホストの一括削除 /api/v2/bulk/host_delete/
- Automation Controller 4.4 のリリースノートや 4.5、4.6 のリリースノートには見当たらないですが、Automation Controller 4.6 系には機能あり
ジョブテンプレートの一括開始 /api/v2/bulk/job_launch/

これまでも1つずつにホストを追加したり、ジョブテンプレートを起動したりすることはできましたが。一方 Bulk API を利用するを一括で実行する分、早く処理されることが期待できます。

そして、Bulk API を利用した Ansible のモジュールもあります。

ホストの一括追加であれば ansible.controller.bulk_host_create モジュールです（AWX 向けは awx.awx.bulk_host_create モジュール）。

この記事では、ansible.controller.bulk_host_create モジュールで試したことをまとめます。

デフォルトでは最大 100件、冪等性がない、なといくつか注意点もありました。

検証環境
- AAP 2.5 2025/04/09 パッチリリース
  - Automation Controller 4.6.11
- ansible.controller コレクション 4.6.11
- ansible-core 2.16.6

基本的な使い方

inventory オプションでは既存のインベントリ名や ID を指定して、hosts オプションで追加したいホストの情報を指定します（ここが複数可）。

hosts 配下のリスト内のディクショナリは、name だけが必須で他は任意です。ここでは雰囲気で指定しています。

---
- name: Bulk host create
  hosts: aap25
  gather_facts: false

  vars:
    ansible_python_interpreter: "{{ ansible_playbook_python }}"

  environment:
    CONTROLLER_HOST: https://{{ ansible_host }}  # 各変数はインベントリで定義済み
    CONTROLLER_USERNAME: "{{ ansible_user }}"
    CONTROLLER_PASSWORD: "{{ ansible_password }}"
    CONTROLLER_VERIFY_SSL: false

  tasks:
    - name: Bulk host create
      ansible.controller.bulk_host_create:
        inventory: network_devices
        hosts:
          - name: rt_core01     # 1つ目のホスト（最小限のオプション）
          - name: rt_core02     # 2つ目のホスト
            description: Core Router 02
            variables:          # ホスト変数も指定できる
              hoge: fuga

name オプション配下には、enabled や instance_id オプションがありますが、ホストが所属するグループを指定するオプションはありません。別途、ansible.controller.groupモジュールの hosts オプションで指定します。このあたりの事情は、一つずつホストを操作する ansible.controller.hostモジュールと同じです。

それでは Playbook を実行します。なお、ここではインベントリ network_devices は作成済みの状態です。

% ansible-playbook -i inventory.yml bulk_host.yml

PLAY [Bulk host create] ****************************************************************************

TASK [Bulk host create] ****************************************************************************
changed: [aap25]

PLAY RECAP *****************************************************************************************
aap25       : ok=1    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

画面を確認してみると、無事に追加されていました。

留意点

調べたり試して気付いた、いくつかのポイントです。

冪等性はない

試してみて初めて気がついたのですが、ansible.controller.bulk_host_create モジュールには冪等性がありません。

ここでいう冪等性がない、というのは毎回 changed になるということではなく、2回目の実行はエラーになるということを示しています。

具体的には、hosts オプションで指定した、追加したいホスト一覧の中に、既存のホスト含まれているとエラーになります（同一インベントリ内の同一 name が条件）。

少し言い方を変えると ansible.controller.bulk_host_create モジュールを使ったホスト追加の Playbook を2回実行するとエラーになります。

その際のエラーメッセージは以下のようになります。

TASK [Bulk host create] ********************************************************************************
fatal: [aap25]: FAILED! => {"changed": false, "msg": "Failed to create hosts, see response for details", "response": {"json": {"__all__": ["Hostnames must be unique in an inventory. Duplicates found: ['rt_core01', 'rt_core02']"]}, "status_code": 400}}

デフォルトの件数上限は 100 件

一度にホスト追加できる上限はデフォルトで 100件です。

試しに 110 件を超えて追加しようとしたら、以下のようなエラーになりました。

TASK [Bulk host create 110] ****************************************************
fatal: [aap25]: FAILED! => {"changed": false, "msg": "Failed to create hosts, see response for details", "response": {"json": {"__all__": ["Number of hosts exceeds system setting BULK_HOST_MAX_CREATE"]}, "status_code": 400}}

件数上限の変更方法

公式ブログの記事によると BULK_HOST_MAX_CREATE という設定項目で変更できるそうです。ただ、「設定 > ジョブ」のように画面から編集できるタイプの設定項目ではないようでした。

API なら設定変更できるかなと思って https://{Platform GatewayのIPアドレス}/api/controller/v2/ 探してみると、それらしい /api/controller/v2/settings/bulk/ が見つかりました。

なお、Automation Controller の API リファレンスにも、Retrieve a Setting としての GET /api/v2/settings/{category_slug}/ などが見つけられました。BULK_HOST_MAX_CREATE という項目の説明として、「Max number of hosts to allow to be created in a single bulk action (integer)」と記載がありました。AAP 2.5 では基本的に Platform Gateway 経由で API リクエストしますので、Automation Controller への /api/v2/〜 は Platform Gatewayへの /api/controller/v2/〜 に読み替えます（参考記事）。

それではまず、GET で現在の設定値（デフォルトまま）を確認します。

% curl -s -k https://{Platform GatewayのIPアドレス}/api/controller/v2/settings/bulk/ -u xxx:yyy | jq . 
{
  "BULK_JOB_MAX_LAUNCH": 100,
  "BULK_HOST_MAX_CREATE": 100,
  "BULK_HOST_MAX_DELETE": 250
}

BULK_HOST_MAX_CREATE を確認すると、公式ブログの Automation Controller 4.4 (AAP 2.4) の頃と同じく 100 ですね。

試しに 110 に変更します。他の設定は変更する必要がないため、BULK_HOST_MAX_CREATE だけを指定して PATCH を利用します（PUT ではなく）。

% curl -k -X PATCH https://{Platform GatewayのIPアドレス}/api/controller/v2/settings/bulk/ -u xxx:yyy -H "Content-Type: application/json" -d '{"BULK_HOST_MAX_CREATE": 110}'
{"BULK_JOB_MAX_LAUNCH":100,"BULK_HOST_MAX_CREATE":110,"BULK_HOST_MAX_DELETE":250}%

続いて、デフォルトの 100 ではエラーになってしまった 110 件のホストを追加する Playbook を実行してみます。

TASK [Bulk host create 110] ****************************************************************************
changed: [aap25]

PLAY RECAP *********************************************************************************************
aap25           : ok=1    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

無事に追加でき、BULK_HOST_MAX_CREATE の設定値を変更できたことを確認できました。

ちなみに、Web ブラウザで https://{Platform GatewayのIPアドレス}/api/controller/v2/settings/bulk/ を認証済みで開いた画面でも、現在値の確認や PATCH や PUT ができます。

デフォルトのサイズ制限

本 API エンドポイントに限った話ではありませんが、API リクエストのペイロードのサイズには上限があります。nginx としての設定値です。

このサイズ制限の件も公式ブログに記載されていて、デフォルトで最大１MB とあります。しかしこの 1MB という設定値は Automation Controller 4.4 (AAP 2.4) の頃のもののようです。

私が今回の環境、AAP 2.5 2025/04/09 パッチリリース（Automation Controller 4.6.11）で試す限り、5MB のようでした。

ややざっくりですが、1つのホスト追加のみにして、変数値（hosts > variables）に 4.9 MB の値を割り当てた場合ではエラーにはならず、5.1 MB では以下のエラーになりました。

TASK [Bulk host create] *******************************************************************************************************
fatal: [aap25]: FAILED! => {"changed": false, "msg": "Failed to create hosts, see response for details", "response": {"status_code": 413, "text": "<html>\r\n<head><title>413 Request Entity Too Large</title></head>\r\n<body>\r\n<center><h1>413 Request Entity Too Large</h1></center>\r\n<hr><center>nginx</center>\r\n</body>\r\n</html>\r\n"}}

前述の件数条件に引っかからない場合でも、変数の指定（hosts > variables）次第では制限に引っかかることは、まあまあ有り得そうです。

サイズ上限の変更方法

AAP 2.5 のドキュメントを見ると、コンテナ版インストーラーのそれらしい設定の変数として以下の 2つがありました。いずれもデフォルトは 5m です。

controller_nginx_client_max_body_size
gateway_nginx_client_max_body_size

この設定値は、それぞれ Automation Controller、Platform Gateway の nginx の .conf の client_max_body_size に反映されます。

上記2つの設定の組み合わせを試した限り controller_nginx_client_max_body_size の方が、今回のサイズ上限の変更に効きました。今回利用した ansible.controller コレクション 4.6.11 では、Platform Gateway 経由で、Automation Controller の操作ができますが、奥にいる Automation Controller 側の設定が効いたイメージです。

*_nginx_client_max_body_size という変数名がなんだか見覚えがあるな思ったら、以前 Automation Controller 4.1 の頃にサイズが大きめのマニフェストファイルを適用したときのエラー対策として修正した変数でした。当時はデフォルトが 1m でした。