はじめに

Automation Controller と同じく、EDA Controller にも REST API が備わっていることを知りましたので、ちょっと触ってみました。

本記事では、API の叩き方を調べ方と、API でのプロジェクトとアクティベーションの作成の仕方について扱います。

環境
- EDA Controller 1.0.0
  - バージョン番号は rpm のファイル名から類推
  - AAP 2.4 のインストーラーで構築したもの

本記事では、REST API を叩くのには curl コマンドを利用します。

お作法

API を利用するとき、（個人的に）最初につまずきがちなお作法の件。

メソッド・エンドポイント・ペイロード

以下のアドレスで見れる、REST API のドキュメント UI （心の中ではずっと Swagger UIと呼んでいます）を見て、メソッドやエンドポイント、ペイロードを調べます。

https://(EDA Controllerのアドレス)/api/eda/v1/docs

例えば、プロジェクトの一覧を取得したいのであれば、https://(EDA Controllerのアドレス)/api/eda/v1/projects/ を GET すればいいことが分かります。

EDA Controller の画面を操作すると API をバシバシ叩くので、この様子をブラウザの開発者ツールなどで調べる方法もあります。画面でやるあの操作は API をどう叩いているんだろう？と調べるときにとても便利です。

認証方式

API 用のトークンを作成する手順などは見当たりませんでした。

一方、EDA Controller の操作を自動化する Ansible モジュールを作成している方のコードで Basic 認証を使っている箇所を見かけたので、今回は Basic 認証でやってみることにします。

具体的には、以下のヘッダーを追加します。（括弧は不要）

Authorization: Basic (ユーザー:パスワードのBase64エンコード文字列)

curl であれば −u オプション使っても大丈夫です。

使ってみる

全体的なお作法と調べ方が分かったので、実際に API を利用します。

プロジェクトの作成

画面ぽちぽちの代わりに API を利用してプロジェクトを作成します。もともと画面上の入力項目は少ないですが、試すには気軽でちょうどよいです。

REST API のドキュメント UI によるとプロジェクトの作成は POST で /api/eda/v1/projects/ をリクエストすれば良いですようです。

以下の curl コマンドでプロジェクトを作成します。（| python3 -m json.tool はレスポンスの整形用です）

リクエスト:

% curl -X POST -l 'https://(EDA Controllerのアドレス)/api/eda/v1/projects/' -k -s \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic (ユーザー:パスワードのBase64エンコード文字列)' \
  -d '{
    "url": "https://github.com/akira6592/rulebook-sample",
    "name": "rulebook-sample"
  }' \
  | python3 -m json.tool

レスポンス:

{
    "name": "rulebook-sample",
    "description": "",
    "credential_id": null,
    "id": 1,
    "url": "https://github.com/akira6592/rulebook-sample",
    "git_hash": "",
    "import_state": "pending",
    "import_error": null,
    "import_task_id": "a7f51e7f-2608-4dba-b5a6-50db9e692b01",
    "created_at": "2023-08-05T02:37:52.758560Z",
    "modified_at": "2023-08-05T02:37:52.758576Z"
}

レスポンスに、作成されたプロジェクトのID（今回は 1 ）が入っているのは便利です。後で利用します。

画面を確認すると無事に作成されています。

アクティベーションの作成

続いて、先ほど作成したプロジェクト内の Rulebook を利用して、アクティベーションを作成します。

準備1: `rulebook_id` と `decision_environment_id` の確認

いきなりアクティベーションの作成といきたいところですが、準備が必要です。

アクティベーション作成（POST でapi/eda/v1/activations/）のためのリクエストボディ含める値として、rulebook_id や decision_environment_id があります。

{
  "name": "string",
  "description": "string",
  "is_enabled": true,
  "decision_environment_id": 0,
  "project_id": 0,
  "rulebook_id": 0,
  "extra_var_id": 0,
  "restart_policy": "always"
}

project_id は先ほどプロジェクト作成した時のレスポンスに含まれているので問題ありません。

一方で、rulebook_id や decision_environment_id はまだ分からない状態なので、予め調べておく必要があります。画面で開くと URL に ID が含まれるのでそれでもいいのですが、せっかくなので ID 確認も API を使います。

まずは、rulebook_id の確認です。プロジェクト内の Rulebook 一覧を取得し、ファイル名をキーにしてい rulebook_id を確認します。今回の対象の Rulebook ファイル名は hello_debug.yml とします。

リクエスト:

% curl -X GET -l 'https://(EDA Controllerのアドレス)/api/eda/v1/rulebooks/' -k -s \
  -H 'Authorization: Basic (ユーザー:パスワードのBase64エンコード文字列)' \
  | python3 -m json.tool

レスポンス:

{
    "count": 8,
    "next": null,
    "previous": null,
    "page_size": 20,
    "page": 1,
    "results": [
        {
            "id": 1,
            "name": "hello_debug.yml",
            "description": "",
            "rulesets": "---\n- name: Hello Events\n  hosts: all\n\n  sources:\n    - ansible.eda.range:\n        limit: 5\n\n  rules:\n    - name: Say Hello\n      condition: event.i == 1\n      action:\n        debug:\n          msg: sakana!\n",
            "project_id": 1,
            "created_at": "2023-08-05T02:37:53.607798Z",
            "modified_at": "2023-08-05T02:37:53.607821Z"
        },
        {
            "id": 2,
            "name": "hello_jt.yml",
            "description": "",
            "rulesets": "---\n- name: Hello Events\n  hosts: all\n\n  sources:\n    - ansible.eda.webhook:\n        host: 0.0.0.0\n        port: 5000\n\n  rules:\n    - name: Say Hello\n      condition: event.payload.message == \"sakana\"\n      action:\n        run_job_template:\n          name: Demo Job Template\n          organization: Default\n",
            "project_id": 1,
            "created_at": "2023-08-05T02:37:53.620383Z",
            "modified_at": "2023-08-05T02:37:53.620395Z"
        },
        // 略
    ]
}

対象の Rulebook の rulebook_id が 1 であることが分かりました。

なお、デフォルトでは GET のレスポンスは一度に 20件の表示です。もし、それを超えた件数の Rulebook があり、対象の Rulebook が見つからない場合は、GET のパラーメーターで page_size=50 のようにして一度に取得する件数を増やすか、レスポンス内で next で示されたリクエストを実行して探します。

続いて、decision_environment_id の確認です。Execution Environment の一覧を取得し、DE 名をキーにして decision_environment_id を確認します。今回の対象の DE 名は Default Decision Environment とします。

リクエスト:

curl -X GET -l 'https://(EDA Controllerのアドレス)/api/eda/v1/decision-environments/' -k -s \
  -H 'Authorization: Basic (ユーザー:パスワードのBase64エンコード文字列)' \
  | python3 -m json.tool

レスポンス:

{
    "count": 1,
    "next": null,
    "previous": null,
    "page_size": 20,
    "page": 1,
    "results": [
        {
            "name": "Default Decision Environment",
            "description": "",
            "image_url": "registry.redhat.io/ansible-automation-platform-24/de-supported-rhel8:latest",
            "credential_id": 1,
            "id": 1,
            "created_at": "2023-08-04T15:07:41.211399Z",
            "modified_at": "2023-08-04T15:07:41.211416Z"
        }
    ]
}

対象の DE の decision_environment_id が 1 であることが分かりました。

これで、アクティベーションを作成するときのパラメーターの材料が揃いました。

準備2: Automation Controller へのトークンの設定

現状、アクティベーションの作成には予め Automation Controller へのトークンの設定が必要です。（設定されていない場合は No controller token specified というエラーになる）

すでに画面（ユーザー > (ユーザー名) > コントローラートークン）から設定済みであれば準備OKです。

もし API で設定するのであれば、以下のようにします。

リクエスト:

curl -X POST -l 'https://(EDA Controllerのアドレス)/api/eda/v1/users/me/awx-tokens/' -k -s \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic (ユーザー:パスワードのBase64エンコード文字列)' \
  -d '{
    "name": "my-token",
    "description": "string",
    "token": "Automation Controller のトークン"
  }' \
  | python3 -m json.tool

レスポンス:

{
    "id": 4,
    "name": "my-token",
    "description": "string",
    "user_id": 1,
    "created_at": "2023-08-05T04:03:31.718048Z",
    "modified_at": "2023-08-05T04:03:31.718066Z"
}

アクティベーションの作成

準備ができたので、以下の curl コマンドでアクティべーションを作成します。

リクエスト:

curl -X POST -l 'https://(EDA Controllerのアドレス)/api/eda/v1/activations/' -k -s \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic (ユーザー:パスワードのBase64エンコード文字列)' \
  -d '{
    "name": "hello_debug",
    "is_enabled": true,
    "decision_environment_id": 1,
    "project_id": 1,
    "rulebook_id": 1,
    "restart_policy": "always"
  }' \
  | python3 -m json.tool

レスポンス:

{
    "id": 1,
    "name": "hello_debug",
    "description": "",
    "is_enabled": true,
    "decision_environment": {
        "id": 1,
        "name": "Default Decision Environment",
        "description": "",
        "image_url": "registry.redhat.io/ansible-automation-platform-24/de-supported-rhel8:latest"
    },
    "status": "starting",
    "project": {
        "id": 1,
        "git_hash": "a0b41faee0a07c3620f0062478a27bc382ee9612",
        "url": "https://github.com/akira6592/rulebook-sample",
        "name": "rulebook-sample",
        "description": ""
    },
    "rulebook": {
        "id": 1,
        "name": "hello_debug.yml",
        "description": ""
    },
    "extra_var": null,
    "instances": [],
    "restart_policy": "always",
    "restart_count": 0,
    "rulebook_name": "hello_debug.yml",
    "rules_count": 0,
    "rules_fired_count": 0,
    "created_at": "2023-08-05T04:13:54.032593Z",
    "modified_at": "2023-08-05T04:13:54.032607Z"
}

アクティベーションが作成されました。

おわりに

EDA Controller の REST API のお作法を調べて、お試しとしてプロジェクトやアクティベーションの作成をやってみました。

いろいろと、名前ではなく ID で指定する必要がある点が少し手間でした。

Automation Controller でいう awx.awx や ansible.controller コレクションのように、EDA Controller 自体の操作を自動化するコレクションが出てくるのではないかなと思います。

今のところ、認証の方法を調べているときに見つけた、以下のコレクションが気になっています。

github.com

[2023/10/02 追記]

ansible.eda コレクションに、eda-server/ EDA Controller 自体の設定するためのモジュールを追加する PR が出てました。

github.com

てくなべ (tekunabe)

ansible / network automation / 学習メモ

[Ansible/EDA] EDA Controller の REST API のお作法とプロジェクト、アクティベーション作成

はじめに

お作法

メソッド・エンドポイント・ペイロード

認証方式

使ってみる

プロジェクトの作成

アクティベーションの作成

準備1: `rulebook_id` と `decision_environment_id` の確認

準備2: Automation Controller へのトークンの設定

アクティベーションの作成

おわりに

はじめに

お作法

メソッド・エンドポイント・ペイロード

認証方式

使ってみる

プロジェクトの作成

アクティベーションの作成

準備1: rulebook_id と decision_environment_id の確認

準備2: Automation Controller へのトークンの設定

アクティベーションの作成

おわりに

準備1: `rulebook_id` と `decision_environment_id` の確認