Ansible 入門シリーズへようこそ。アプリケーション・プログラミング・インタフェース (API) は、魔法のようにさまざまな方法で使用することができます。Ansible 入門シリーズのこの記事では、Red Hat Ansible Tower の API を使用して Playbook やその他のツールで活用できる情報を抽出する方法をご紹介します。

このブログ記事の構想は、David Federlein が新しい Ansible Tower のデモとプレゼンテーションを開発していたときに生まれたものです。本記事の中でそのコードベースを参照しているので、確認しながらお読みください。このデモでは Vagrant と VirtualBox を使用しているため、デモを再現するには、これらのアプリケーションをインストールしていただく必要があります。

Ansible Tower の API

Ansible Tower の API は完全にブラウザー対応しています。インスタンスの REST API に移動するには、ブラウザーに http://<Tower server name>/api/v2 と入力します。移動後、リストされるいずれかのリンクをクリックすると、その特定の属性用にロードされた現在のオブジェクトが Ansible Tower に表示されます。Ansible Tower の UI でできることはすべて、API からも実行できます。API を使用して、認証情報からユーザーに至るまで、あらゆる情報を表示することもできます。次のセクションで説明しますが、手動で API に Post (投稿) したり、Playbook で呼び出しを行ったりできます。

API への Post (投稿)

API はさまざまな方法で呼び出すことができますが、ここでは、最も基本的な 2 つの方法をご紹介します。

1. Ansible Tower の REST API インタフェースから手動で呼び出す
2. Playbook から呼び出す

ここで言う「基本的」とは、これらの方法が「Ansible Tower を介してのみ行われる」ということです。すでにご存知かもしれませんが、Ansible Tower からの情報を他のアプリケーションで使用することで、さまざまな優れた機能を実現できます。

これらの方法では、Ansible Tower を設定、変更できるだけでなく、以下で説明するように、API 呼び出しを介してジョブを実行することもできます。これにより、エンタープライズ・インフラストラクチャの他の側面との密接な連携が可能になり、リソースとジョブテンプレートに対して設定された権限管理をベースにアクセス制御を行いながら、Red Hat Ansible Engine のワークロードを実行することができます。

手動での Post (投稿)

初心者にとって最も簡単な (ただし、速度と自動化は最高レベルではない) API への Post (投稿) 方法は、API インタフェースからの Post (投稿) です。インタフェースで、Post (投稿) するオブジェクトを選択できます。各オブジェクトには、ページの下部にテンプレートがあり、Post (投稿) に含めることのできるフィールドが表示されます。

たとえば、API を使用して Ansible Tower インスタンスにプロジェクトを追加するとします。操作はとても簡単です。Ansible Tower の API 画面 (https://<towerip>/api/v2) に移動して、プロジェクト URL (/api/v2/projects/) を選択し、一番下までスクロールします。次のようなコンテンツが表示されます。

{
    "name": "",
    "description": "",
    "local_path": "",
    "scm_type": "",
    "scm_url": "",
    "scm_branch": "",
    "scm_clean": false,
    "scm_delete_on_update": false,
    "credential": null,
    "timeout": 0,
    "organization": null,
    "scm_update_on_launch": false,
    "scm_update_cache_timeout": 0
}

このコンテンツが表示されたら、環境の関連情報を引用符内に記述します。フィールドに貼り付けたら、[POST (投稿)] をクリックします。正常に Post (投稿) されると、Ansible Tower の UI で、あるいは API 経由でプロジェクトを表示できます。

失敗した場合は、リクエストが不正であったことを示す通知を受け取ります。エラーを修正する方法は、その下の引用符内に示されます。たとえば、ユーザーを作成しているときに、そのユーザーのパスワードを入力しなかった場合は失敗し、次のエラーが返されます。

{
    "password": [
        "This field may not be blank."
    ]
}

上記のエラーのように API への Post (投稿) に関する問題が発生した場合は、UI の右上の [GET (取得)] の横にある [OPTIONS (オプション)] ボタンをクリックすると、役立つ情報が表示されます。[OPTIONS (オプション)] ボタンをクリックすると、Post (投稿) する特定のオブジェクトまたはエンドポイントの POST、PUT、PATCH の許容値が表示されます。

見つかったエラーをコンテンツフィールドで修正したら、もう一度 [POST (投稿)] をクリックして、オブジェクトが Ansible Tower に正常に追加されたことを確認します。

Playbook を使用した Post (投稿)

Ansible Tower の API に Post (投稿) するもう 1 つの方法は、Playbook を使用する方法です。この記事の前半でリンクを貼っている GitHub リポジトリでは、インストール後の play を通じて Post (投稿) します。インストール後に実行される処理の大半が、API 経由で行われます。

この動作を実際に確認するには、先ほどインスタンスに追加したプロジェクトを同期させます。これには、Ansible Playbook の作成に関する事前知識がいくらか必要となります。不明な点についてや、Playbook に関する知識を深めたい場合は、Red Hat のドキュメントをご覧ください。

ジョブの同期を開始する play では、Ansible 内の URI モジュールが使用されます。このモジュールは、Ansible Tower API などの Web サービスとの対話に使用されます。この play は、上記にリンクを貼ってあるコードベースの /roles/tower/main.yml にあります。

- name: kick off project sync
  uri:
    url:  https://localhost/api/v1/projects/7/update/
    method: POST
    user: admin
    password: "{{ towerpass }}"
    validate_certs: False
    status_code:
      - 200
      - 201
      - 202
  when: response.status == 201

この Playbook のタスクでは、Ansible にプロジェクトの API URL に移動するよう指示しています。この例では、URL は https://localhost/api/v2/projects/7/update/ です。更新前にプロジェクトに番号が割り当てられていることを確認してください。プロジェクトには、Ansible Tower に登録されたタイミングに基づき、Ansible Tower で番号が割り当てられます。この番号を確認するには、プロジェクト https://<your_ip_here>/api/v2/projects/ の API インタフェースに移動します。そこから同期するプロジェクトを見つけ、そのプロジェクト番号の更新エンドポイントに Post (投稿) する必要があります。この例では、プロジェクト番号 7 で更新を行います。

更新する必要のあるプロジェクトが見つかったら、更新するエンドポイントへの Post (投稿) を行います。この例ではプロジェクト 7 を更新するため、エンドポイントは https://localhost/api/v1/projects/7/update/ です。

この Post (投稿) が URI モジュールで正常に動作するためには、Tower にログインするためのユーザー認証情報も API に渡す必要があります。この例では、デフォルトの管理者ユーザーを使用しています。管理者ユーザーでなくても、そのような Post (投稿) を行う十分なアクセス権を持つ任意のユーザーを指定できます。

ジョブの開始

「ジョブの開始」というと、あいまいな見出しだと感じるかもしれません。「Ansible Tower でジョブを開始するのは、説明が必要なほどのことではない」と思われるかもしれません。実際その通りなのですが、この例では、Ansible Tower でPlaybook からジョブを開始します。これも、API コールで実行可能なことの 1 つです。参照しようとしている例は、vagrant-common ロール (/roles/vagrant-common/main.yml) にあります。

コードの中で、注目すべきタスクが次の例に含まれています。

name: kick off the provisioning job template
  shell:  "curl -f -H 'Content-Type: application/json' -XPOST --user 
admin:{{ towerpass }} 
https://172.16.2.42/api/v2/job_templates/8/launch/ --insecure"
  when: inventory_hostname == 'demovm4'

shell モジュールを使用し、特定の https エンドポイントに対して curl コマンドを実行していることがすぐにわかると思います。この場合、この https エンドポイントは、特定のジョブテンプレートを起動するための API エンドポイントです。

その特定のジョブテンプレートには、Ansible Tower で番号が割り当てられています。特定のジョブテンプレートのエンドポイントを、API の詳細を確認することなくすばやく簡単に見つけ出すには、API を経由して実行するジョブテンプレートを確認します。ジョブテンプレートへ移動したら、URL とそれに割り当てられた番号を確認してください。

該当するジョブテンプレートが見つかったら、https エンドポイントは api/v2/job_templates/8/launch/ のようになります。curl コマンドで `-XPOST` を指定してそのエンドポイントをヒットすると、うまくいくはずです。

さらに詳しく 

この記事で扱ったのは、Ansible Tower の API を使ってできることの一部に過ぎません。Ansible Tower の API に興味があり、詳細を知りたい場合は、API に関する Ansible ドキュメントをご覧ください。

Ansible の Twitter アカウント (@ansible) では、入門コンテンツの最新情報をお知らせしています。また、Ansible ブログでは、Ansible 入門シリーズの過去記事をご覧いただけます。

AnsibleFest 2018 の開催日もお見逃しなく。今年の Ansible 入門チームは、テキサス州オースティンで 10 月 2 ～ 3 日の 2 日間にわたって開催されます。テーマは Ansible 自動化です。 

最後に、このブログ記事の作成に協力してくれた Ansible 入門チームのメンバー、Bianca Henderson を紹介します。Bianca：LinkedIn / Twitter (@bizonks)   

関連リンク

• Red Hat Ansible Towerのご紹介

• Red Hat Ansible Towerのインストールガイド