てくなべ (tekunabe)

ansible / network / automation

[Ansible] Tower や AWX をコマンドで操作できる awx コマンドのインストール、設定、動作確認

はじめに

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"

なお、バージョン一覧はリリース一覧から確認できます。

インストールの確認

確認のため、バージョンを表示します。

$ awx --version
11.0.0

無事に表示できました。

[2020/06/24 追記]

AWX 13.0.0 リリースに伴い、PyPi 経由でインストールできるようになりました。パッケージ名は awskit です。

pip install awxkit

awx/INSTALL.md at devel · ansible/awx · GitHub


■ 接続先・認証情報の設定

対象の 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.7.1 documentation

ここでは、前述の 1-2. 環境変数で指定する場合 にしたがって、認証情報が設定済みであることを仮定します。

awx login コマンドでトークンを発行できます。

$ awx login
{
     "token": "xxxxxxxxxxx_dummy_xxxxxxxxxxx"
}

発行されたトークンを環境変数 TOWER_OAUTH_TOKEN に指定します(awx コマンドの --conf.token オプションでも可)。

export TOWER_OAUTH_TOKEN=xxxxxxxxxxx_dummy_xxxxxxxxxxx

この時点で、環境変数で設定していた他の TOWER_USERNAMETOWER_PASSWORD は不要になります。

気になる有効期限ですが、試す限り 設定 > システム > アクセストークンの有効期限 の設定によるようです。デフォルトは 31536000000 秒(1000年)。

f:id:akira6592:20200418151548p:plain
左下の類似項目に注意

試しに、組織の一覧を表示してみます。

$ 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 のインストールと設定と動作確認の方法をご紹介しました。

GUIAPI、Ansible、今回の awx のように、操作方法がいろいろあるのは便利ですね。

参考