はじめに
Ansible Tower / AWX は GUI の他にも、REST API 機能があります。API を利用すると、プログラムから操作しやすくなったり、CLI 化しやすくなったリします。
AWX には、API をラッピングしたような awx という CLI ツールがあります。
（ここでは AWX 本体は大文字の AWX、awx コマンドは小文字の awx と表記します）
以前は類似のツールでは tower-cli がありましたが、現在は legacy 扱いです。（とはいえ、本記事を書いている時点では tower-cli にしかできないこともまだあります。インポート/エクスポートなど）
この記事では、インストールなどの準備や、動作確認としてかんたんな利用例をご紹介します。
- 動作確認環境
- AWX 11.0.0
■ インストール
準備として、awx コマンドのインストールと、接続先の設定をします。pip コマンドで簡単にインストールできます。
インストールの実行
AWX の公式ドキュメントに基づき、以下の pip コマンドでインストールします。
pip install "https://github.com/ansible/awx/archive/<バージョン>.tar.gz#egg=awxkit&subdirectory=awxkit"
<バージョン> の箇所には、11.0.0 などのバージョン番号を指定します。
- コマンド実行例
pip install "https://github.com/ansible/awx/archive/11.0.0.tar.gz#egg=awxkit&subdirectory=awxkit"
なお、バージョン一覧はリリース一覧から確認できます。
[2020/06/24 追記]
AWX 13.0.0 リリースに伴い、PyPi 経由でインストールできるようになりました。パッケージ名は awskit です。
pip install awxkit
awx/INSTALL.md at devel · ansible/awx · GitHub
インストールの確認
確認のため、バージョンを表示します。
$ awx --version 11.0.0
無事に表示できました。
■ 接続先・認証情報の設定
対象の Ansible Tower / AWX を操作するには、接続先アドレスや認証情報の設定が必要です。
いくつか方法がるので、それぞれご紹介します。 簡単な検証レベルをのため、パスワードなどを平文で指定していますが。実運用の場合はもうひと工夫必要かと思います。
なお、各オプションや、設定項目についてはこちらにも掲載されています。
方法1: ユーザー・パスワードを指定する
接続先アドレスや、ユーザー・パスワードを直接指定する方法です。
さらに細かくいうと、都度指定する方法と、環境変数で指定する方法があります。
1-1. 都度指定する場合
あまり実用的ではないですが、awx コマンドの実行のたびにオプションとして指定する方法です。
- 主なオプション
| オプション | 概要 | 例 |
|---|---|---|
--conf.host |
対象の Ansible Tower / AWX のアドレス | --conf.host https://localhost |
--conf.username |
ログインユーザー名 | --conf.username myadmin |
--conf.password |
ログインパスワード | --conf.password mypasswrd |
--conf.incecure |
SSL 証明書検証の無効化 | --conf.incecure |
- コマンド例（組織の一覧を表示）
awx --conf.host https://localhost --conf.username myadmin --conf.password mypassword organization list
なお、デフォルトでの設定値は awx config コマンドで確認できます。
$ awx config { "base_url": "https://127.0.0.1:443", "token": "", "use_sessions": false, "credentials": { "default": { "username": "admin", "password": "password" } } }
1-2. 環境変数で指定する場合
接続先や認証情報は、環境変数でも指定できます。
- 主な環境変数
| オプション | 概要 | 例 |
|---|---|---|
TOWER_HOST |
対象の Ansible Tower / AWX のアドレス | TOWER_HOST=https://localhost |
TOWER_USERNAME |
ログインユーザー名 | TOWER_USERNAME=myadmin |
TOWER_PASSWORD |
ログインパスワード | TOWER_PASSWORD=mypassword |
TOWER_VERIFY_SSL |
SSL 証明書検証の有無 | TOWER_VERIFY_SSL=False |
- 設定例
export TOWER_HOST=https://localhost export TOWER_USERNAME=myadmin export TOWER_PASSWORD=mypassword export TOWER_VERIFY_SSL=False
上記の設定をした場合、awx config の結果は以下のようになります。（TOWER_VERIFY_SSL の値はここには反映されないようです）
$ awx config { "base_url": "https://localhost", "token": "", "use_sessions": false, "credentials": { "default": { "username": "myadmin", "password": "mypassword" } } }
他、tower-cli で利用していた ~/.tower-cli.cfg 内に定義する方法が、awx コマンドでも利用できるかは未確認です。
方法2: OAuth2.0 トークンを指定する
いったん、正しいユーザー名とパスワードを指定するとトークンを発行できます。 次回以降そのトークンを利用して操作する方法です。
参考
Authentication — AWX CLI Ansible Tower 3.8.6 documentation
ここでは、前述の 1-2. 環境変数で指定する場合 にしたがって、認証情報が設定済みであることを仮定します。
awx login コマンドでトークンを発行できます。
$ awx login { "token": "xxxxxxxxxxx_dummy_xxxxxxxxxxx" }
AWX の画面上は各ユーザーの トークン 画面で、生成されたことが確認できます。ただし、トークンの値自体は参照できないので、さきほど表示された値を控えておく必要があります。
発行されたトークンを環境変数 TOWER_OAUTH_TOKEN に指定します（awx コマンドの --conf.token オプションでも可）。
export TOWER_OAUTH_TOKEN=xxxxxxxxxxx_dummy_xxxxxxxxxxx
この時点で、環境変数で設定していた他の TOWER_USERNAME と TOWER_PASSWORD は不要になります。
気になる有効期限ですが、試す限り 設定 > システム > アクセストークンの有効期限 の設定によるようです。デフォルトは 31536000000 秒（1000年）。
試しに、組織の一覧を表示してみます。
$ awx organization list { "count": 1, "next": null, "previous": null, "results": [ { "id": 2, "type": "organization", "url": "/api/v2/organizations/2/", "related": { "created_by": "/api/v2/users/1/", "modified_by": "/api/v2/users/1/", "projects": "/api/v2/organizations/2/projects/", "inventories": "/api/v2/organizations/2/inventories/", "job_templates": "/api/v2/organizations/2/job_templates/", "workflow_job_templates": "/api/v2/organizations/2/workflow_job_templates/", "users": "/api/v2/organizations/2/users/", // ...(略)... }
トークンによって正しく認証され、組織の一覧が表示できました。
なお、認証情報が誤っていると Valid credentials were not provided. というエラーメッセージが表示されます。
■ 利用例（動作確認）
ここまでで準備ができたので、動作確認を兼ねて実際に使ってみます。
基本的な構文は、以下のようなイメージです。
awx 何を どうする オプション
たとえば、ユーザーの一覧を表示するなら awx user list です。-h をつけてコマンドヘルプを見るといろいろわかります。
ユーザー一覧の取得
- コマンド書式
awx user list
- 実行例
$ awx user list { "count": 3, "next": null, "previous": null, "results": [ { "id": 1, "type": "user", "url": "/api/v2/users/1/", "related": { "teams": "/api/v2/users/1/teams/", "organizations": "/api/v2/users/1/organizations/", "admin_of_organizations": "/api/v2/users/1/admin_of_organizations/", "projects": "/api/v2/users/1/projects/", "credentials": "/api/v2/users/1/credentials/", "roles": "/api/v2/users/1/roles/", "activity_stream": "/api/v2/users/1/activity_stream/", "access_list": "/api/v2/users/1/access_list/", "tokens": "/api/v2/users/1/tokens/", "authorized_tokens": "/api/v2/users/1/authorized_tokens/", "personal_tokens": "/api/v2/users/1/personal_tokens/" }, "summary_fields": { "user_capabilities": { "edit": false, "delete": false } }, "created": "2019-10-05T07:50:31.898459Z", "username": "admin", "first_name": "", "last_name": "", "email": "root@localhost", "is_superuser": true, "is_system_auditor": false, "ldap_dn": "", "last_login": "2020-04-18T05:42:08.939503Z", "external_account": null, "auth": [] }, // ...(略)... ] }
json が見にくい場合は、-f オプションで出力形式を変更できます。
-f human で人にやさしい感じになります。概要の確認であればこのほうがいいかもしれません。
$ awx user list -f human id username == ======== 1 admin 15 myadmin 14 operator
おわりに
awx のインストールと設定と動作確認の方法をご紹介しました。
GUI、API、Ansible、今回の awx のように、操作方法がいろいろあるのは便利ですね。
