30. コントローラーのヒントと裏技¶

30.1. コントローラー CLI ツールの使用¶

automation controller には、フル機能のコマンドラインインターフェースがあります。設定および使用手順については、AWX Command Line Interface を参照してください。

30.2. コントローラー管理者パスワードの変更¶

インストールのプロセス中に、管理者パスワードの入力を求められます。これは、コントローラーで作成される admin スーパーユーザー/最初のユーザーに使用されます。SSH でインスタンスにログインする場合には、プロンプトでデフォルトの管理者パスワードが通知されます。どのタイミングであっても、このパスワードを変更する必要がある場合には、コントローラーサーバーで root として以下のコマンドを実行します。

awx-manage changepassword admin

次に新規パスワードを入力します。その後は入力したパスワードが Web UI の管理者パスワードとして機能します。

30.3. コマンドラインからのコントローラー管理者の作成¶

コマンドラインから管理者 (スーパーユーザー) アカウントを作成すると便利な場合があります。管理者を作成するには、コントローラーサーバーで root として以下のコマンドを実行し、プロンプトに従い管理者の情報を入力します。

awx-manage createsuperuser

30.4. ジャンプホストがコントローラーを使用するように設定する手順¶

コントローラーが提供する認証情報は、ProxyCommand ではジャンプホストに渡らず、トンネル接続が設定されてからしか、エンドノードには使用されません。

これを機能させるには、ジャンプホスト経由での接続を設定する ProxyCommand 定義に含まれる AWX ユーザーの SSH config で、固定のユーザー/キーファイルを設定します。

Host tampa
Hostname 10.100.100.11
IdentityFile [privatekeyfile]

Host 10.100..
Proxycommand ssh -W [jumphostuser]@%h:%p tampa

インベントリー変数を介して、ジャンプホストをコントローラーインスタンスに追加することもできます。この変数はインベントリー、グループ、またはホストレベルに設定できます。これをインベントリーに追加するには、選択したレベルの variables フィールドに、以下の変数を追加します。

ansible_user: <user_name>
ansible_connection: ssh
ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q <user_name>@<jump_server_name>"'

30.5. コントローラーの使用時に JSON コマンドの Ansible の出力を表示する方法¶

automation controller の使用時には、API を使用して JSON 形式のコマンドを Ansible の出力として取得できます。

Ansible の出力を表示するには、以下に移動します。

https://<controller server name>/api/v2/jobs/<job_id>/job_events/

30.6. Ansbile 設定ファイルの場所特定および設定¶

Ansible は設定ファイルを必要としませんが、OS パッケージにはカスタマイズできるように /etc/ansible/ansible.cfg がデフォルトで含まれています。カスタムの ansible.cfg ファイルを使用するには、プロジェクトの root にそのファイルを配置します。Automation controller は、プロジェクトの root ディレクトリーからカスタムの ansible.cfg ファイルを検索して ansible-playbook を実行します。それ以外の場所に配置されている ansible.cfg は無視されます。

このファイルで使用可能な値については、configuration file on github を参照してください。

最初はデフォルトを使用することもできますが、デフォルトのモジュールパスや接続タイプなどをここで設定できる点を念頭に置いておいてください。

The controller overrides some ansible.cfg options. For example, the controller stores the SSH ControlMaster sockets, the SSH agent socket, and any other per-job run items in a per-job temporary directory that is passed to the container used for job execution.

30.7. 全 ansible_ 変数リストの確認¶

Ansible はデフォルトで、Ansible が管理するマシンに関する「ファクト」を収集し、Playbook やテンプレートでアクセスできるようになっています。マシンに関する利用可能なファクトすべてを表示するには、setup モジュールをアドホックアクションとして実行します。

ansible -m setup hostname

これは、特定のホストで利用可能な全ファクトのディクショナリーを出力します。詳しい情報は、https://docs.ansible.com/ansible/playbooks_variables.html#information-discovered-from-systems-facts を参照してください。

30.8. execution environments の使用¶

Automation Controller User Guide の「Execution Environments」を参照してください。

30.9. 通知用の `controllerhost` のホスト名設定¶

System Settings で、コントローラーホストのベース URL フィールドの https://controller.example.com を、希望のホスト名に置き換えることで、通知ホスト名を変更できます。

_images/configure-tower-system-misc-baseurl.png

コントローラーライセンスを更新すると、通知のホスト名も更新します。automation controller の新規インストールでは、通知用にホストを設定する必要はありません。

30.10. curl でのジョブの起動¶

コントローラー API でのジョブの起動は簡単です。以下に、活用しやすい curl ツールの使用例を紹介します。

ジョブテンプレート ID が「1」、コントローラーの IP が 192.168.42.100、有効な認証情報が admin および awxsecret とします。これをベースに新規ジョブを作成することができます。

curl -f -k -H 'Content-Type: application/json' -XPOST \
    --user admin:awxsecret \
    http://192.168.42.100/api/v2/job_templates/1/launch/

これにより、JSON オブジェクトが返されるので分析して、新規作成したジョブの ID を「id」フィールドから抽出するのに使用してください。

以下の例に示されているように、ジョブテンプレートの呼び出しに追加の変数を渡します。

curl -f -k -H 'Content-Type: application/json' -XPOST \
    -d '{"extra_vars": "{\"foo\": \"bar\"}"}' \
    --user admin:awxsecret http://192.168.42.100/api/v2/job_templates/1/launch/

ライブの API ドキュメントを表示するには、http://192.168.42.100/api/ にログインして、利用可能な各種オブジェクトを参照してください。

注釈

extra_vars パラメーターは、JSON ディクショナリーだけが必要と思われるかもしれませんが、JSON を含む文字列でなければなりません。引用をエスケープする場合などは注意してください。

30.11. 動的なインベントリーおよびプライベート IP アドレス¶

デフォルトでは、コントローラーは Elastic IP (EIP) アドレスが関連付けられた VPC にだけインスタンスを表示します。VPC インスタンスをすべて表示するには、以下の手順を実行してください。

コントローラーのインターフェースでインベントリーを選択します。
ソースが AWS に設定されたグループをクリックして、ソースタブをクリックします。
「ソース変数」ボックスで vpc_destination_variable: private_ip_address を入力します。

保存して、グループの更新をトリガーします。VPC インスタンスすべてを表示できるはずです。

注釈

有効なインスタンスを設定する場合には、コントローラーは、インスタンスへのアクセス権がある VPC 内で実行している必要があります。

30.12. コントローラーの動的なインベントリーソースによるインスタンスの絞り込み¶

デフォルトでは、コントローラーの動的インベントリーソース (AWS、Rackspace など) は、使用するクラウド認証情報で利用できるインスタンスをすべて返します。また、各インスタンスはさまざまな属性をもとに、自動的にグループに参加します。たとえば、AWS インスタンスは地域、タグ名および値別、セキュリティーグループ別にグループ化されます。お使いの環境で特定のインスタンスを対象にするには、生成されたグループ名が対象となるように Playbook を記述します。以下に例を示します。

---
- hosts: tag_Name_webserver
  tasks:
  ...

ジョブテンプレート設定の Limit フィールドを使用して、特定のグループ、ホスト、グループとホストそれぞれを対象に Playbook を実行するように制限することも可能です。構文は、ansible-playbook コマンドラインの --limit parameter と同じです。

自動生成されたグループをカスタムのグループにコピーして、独自のグループを作成することも可能です。動的インベントリーソースで Overwrite オプションを無効にしておくようにしてください。無効化されていない場合には、これ以降に同期操作を行うとカスタムグループが削除され、置き換えられてしまいます。

30.13. Ansible ソースから提供されるリリース前のモジュールをコントローラーで使用する方法¶

最新の Ansible コアブランチで利用可能な機能をお使いのコントローラーシステムに活用するのは非常に簡単です。

はじめに、利用可能な Ansible Core Module または Ansible Extra Modules GitHub リポジトリーから更新済みのモジュールで使用するものを決定します。

次に、Ansible のソース Playbook (/library) と同じディレクトリーレベルに新しいディレクトリーを作成します。

このディレクトリーの作成後に、使用するモジュールをコピーして、/library ディレクトリーにドロップします。すると、最初にこのモジュールは、お使いのシステムモジュールで使用されます。安定版の更新が済んだら、通常のパッケージマネージャーで削除できます。

30.14. コントローラーでのコールバックプラグインの使用¶

Ansible は、コールバックプラグインと呼ばれる方法で、Playbook の実行中にアクションを柔軟に処理できます。コントローラーでこれらのプラグインを使用して、Playbook の実行または失敗時、Playbook の実行後のメール送信時にサービス通知などを行うことができます。コールバックプラグインのアーキテクチャーに関する公式のドキュメントは、http://docs.ansible.com/developing_plugins.html#callbacks を参照してください。

注釈

automation controller は stdout コールバックプラグインをサポートしません。Ansible では 1 つしか許可されず、ストリーミングイベントデータ関連で automation controller が 1 つ使用しているためです。

https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback でサンプルのプラグインも確認してみてください。これらは、各サイトの目的に合わせて変更する必要があります。

これらのプラグインを使用するには、コントローラープロジェクトの Playbook と一緒に、コールバックプラグインの .py ファイルを /callback_plugins と呼ばれるディレクトリーに保存します。次に、ジョブ設定の構成画面の Ansible コールバックプラグイン フィールドにパス (1 行に 1 つのパス) を指定します。

_images/configure-tower-jobs-callback.png

注釈

Ansible に同梱されているコールバックの大半をグローバルには適用するには、ansible.cfg の callback_whitelist セクションに追加します。カスタムコールバックがある場合は、「Enabling callback plugins」を参照してください。

30.15. winrm での Windows への接続¶

デフォルトでは、コントローラーはホストに ssh 接続します。Windows ホストが属するグループ変数に winrm の接続情報を追加する必要があります。最初に、ホストが属する Windows グループを編集して、そのグループの source/edit ページで、変数を配置します。

winrm の接続情報の追加手順:

Windows サーバーが含まれるグループ名の右側にある edit ボタンをクリックして、選択したグループのプロパティーを編集します。"変数" セクションで、接続情報 ansible_connection: winrm を追加します。

完了したら編集を保存します。Ansible が以前に SSH 接続を試行して失敗した場合には、ジョブテンプレートをもう一度実行しなおす必要があります。

30.16. 既存のインベントリーファイルおよびホスト/グループ変数のコントローラーへのインポート¶

既存の静的インベントリーと付属のホストおよびグループ変数をコントローラーにインポートするには、インベントリーを以下と同様の構成に設定する必要があります。

inventory/
|-- group_vars
|   `-- mygroup
|-- host_vars
|   `-- myhost
`-- hosts

これらのホストおよび変数をインポートするには awx-manage コマンドを実行します。

awx-manage inventory_import --source=inventory/ \
  --inventory-name="My Controller Inventory"

たとえば、ansible-hosts という名前のインベントリーのファイルがフラットファイルで 1 つしかない場合には、以下のようにインポートします。

awx-manage inventory_import --source=./ansible-hosts \
  --inventory-name="My Controller Inventory"

競合がある場合や、「My Controller Inventory」という名前のインベントリーを上書きする場合には、以下を実行します。

awx-manage inventory_import --source=inventory/ \
  --inventory-name="My Controller Inventory" \
  --overwrite --overwrite-vars

以下のようなエラーを受信した場合:

ValueError: need more than 1 value to unpack

ホストファイルおよび group_vars を保持するディレクトリーを作成します。

mkdir -p inventory-directory/group_vars

次に、 :vars のリストが含まれるグループごとに、inventory-directory/group_vars/<groupname> という名前のファイルを作成して、変数を YAML 形式にフォーマットします。

準備が完了したら、インポーターは正しく変換を処理します。