Documentation

30. Tower のヒントと裏技

30.1. Tower CLI ツールの使用

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

30.2. Tower 管理者パスワードの変更

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

awx-manage changepassword admin

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

30.3. コマンドラインからの Tower 管理者の作成

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

awx-manage createsuperuser

30.4. ジャンプホストが Tower を使用するように設定する手順

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

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

Host tampa
Hostname 10.100.100.11
IdentityFile [privatekeyfile]

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

注釈

ジャンプホストを使用する必要がある場合には、デフォルトで PRoot を無効化する必要があります。PRoot の無効化は、Tower の設定ユーザーインターフェースのジョブのタブから、 ジョブの分離の有効化オフ に切り替えます。

_images/configure-tower-jobs-disable-proot-job-isolation.png

インベントリー変数を介して、ジャンプホストを Tower インスタンスに追加することもできます。この変数はインベントリー、グループ、またはホストレベルに設定できます。これをインベントリーに追加するには、選択したレベルの 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. Tower の使用時に JSON コマンドの Ansible の出力を表示する方法

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

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

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

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

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

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

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

Tower は ansible.cfg オプションを上書きする場合があります。たとえば、Tower は、PRoot 経由で SSH ControlMaster ソケット、SSH エージェントソケット、その他ジョブごとの実行アイテムを、マルチテナントのアクセス制御でセキュリティーが確保されているジョブ毎の一時ディレクトリーに保存します。

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. Ansible Tower での virtualenv の使用

Virtualenv は、分離された Python 環境を構築して依存関係での競合やバージョンの相違による問題を回避します。Virtualenv は、特定のバージョンの Python に必要な実行ファイルや依存関係をすべて含むディレクトリーを作成するだけで機能します。Ansible Tower は、インストール時に 2 つの virtualenv を作成します。1 つは、Tower の実行に、もう 1 つは Ansible の実行に使用します。これにより、Tower は安定した環境で実行でき、Playbook の実行に必要なモジュールを Ansible Python 環境に追加または更新できるようになります。virtualenv の詳細は、Python Guide の「Virtual Environments」および「Python virtualenv」プロジェクト自体を参照してください。

デフォルトでは、virtualenv はファイルシステムの /var/lib/awx/venv/ansible に配置されていますが、カスタムのディレクトリーを作成して、インベントリーインポートで使用できます。これにより、インベントリーソースがカスタムの仮想環境を使用するため、インベントリーインポートの実行方法を選択できるようになります。

さらに Tower は、(EC2、OpenStack、Azure など) 各種クラウドプロバイダーとの統合ポイントとなるように、さまざまなサードパーティーのライブラリー/SDK サポートをこの virtualenv に事前インストールします。以下に詳しく説明されているように、この virtualenv に、定期的に別の SDK サポートを追加することもできます。

注釈

仮想環境にパッケージをインストールする前に umask 0022 を実行することを強く推奨します。パーミッションを適切に設定しておかないと、Tower サービスに失敗します。以下は例となります。

# source /var/lib/awx/venv/ansible/bin/activate
# umask 0022
# pip install --upgrade pywinrm
# deactivate

以下の説明にあるように、Ansible の実行に Tower が使用する virtualenv にモジュールを追加するだけでなく、virtualenvs を新たに作成することができます。

30.8.1. 新しいカスタムの virtualenv の準備

Tower でジョブテンプレートを実行する場合に、異なる virtualenv を指定できます。これには、 virtualenv が配置されているディレクトリーを指定する必要があります。/var/lib/awx/venv/ 内にカスタムの virtualenv を保持することもできますが、カスタムのディレクトリーを作成することを強く推奨します。以下の例では、プレースホルダーのディレクトリー /opt/my-envs/ を使用していますが、任意で指定したディレクトリーパスに置き換えることができます。

  1. 新しいカスタム virtualenv を準備するには、virtualenv パッケージがプリインストールされている必要があります。

$ sudo yum install python-virtualenv
  1. カスタムの virtualenv 向けのディレクトリーを作成します。

$ sudo mkdir /opt/my-envs
  1. ディレクトリーに適切な書き込み権限、実行権限、および所有権を必ず付与してください。

$ sudo chmod 0755 /opt/my-envs
$ sudo chown awx:awx /opt/my-envs
  1. 任意で、作成したディレクトリーを以下のように CUSTOM_VENV_PATHS 設定に追加して、カスタムの virtualenv 用のどのディレクトリーを検索するか、Tower で指定できます。

$ curl -X PATCH 'https://user:[email protected]/api/v2/settings/system/' \
    -d '{"CUSTOM_VENV_PATHS": ["/opt/my-envs/"]}'  -H 'Content-Type:application/json'

複数のディレクトリーに virtualenv がまたがる場合には、全パスを追加してください。Tower が指定した全パスから virtualenv を累積します。

$ curl -X PATCH 'https://user:[email protected]/api/v2/settings/system/' \
    -d '{"CUSTOM_VENV_PATHS": ["/path/1/to/venv/", "/path/2/to/venv/", "/path/3/to/venv/"]}' \
    -H 'Content-Type:application/json'
  1. virtualenv のディレクトリーが設定されたので、その場所に仮想環境を作成します。

$ sudo virtualenv /opt/my-envs/custom-venv

注釈

複数の Python バージョンがサポートされていますが、Python 3 で virtualenv を作成する構文は若干変更されています: $ sudo python3 -m venv /opt/my-envs/custom-venv

  1. 次に、gcc をインストールして、psutil をコンパイルできるようにします。

$ yum install gcc
  1. 新規作成した virtualenv は、Playbook を正しく実行するには、基本的な依存関係が必要です (例: ファクトの収集):

$ sudo /opt/my-envs/custom-venv/bin/pip install psutil

ここから、Ansible 自体に適した各 virtualenv バージョンなど、追加で Python の依存関係をインストールできます。

$ sudo /opt/my-envs/custom-venv/bin/pip install -U "ansible == X.Y.Z"

または、Tower のベースインストールに含まれていない、サードパーティーの SDK を別途追加することができます。

$ sudo /opt/my-envs/custom-venv/bin/pip install -U python-digitalocean

コピーする場合は、pip freeze を使用してTower のデフォルトの virtualenv に含まれるライブラリーを見つけ出すことができます。

$ sudo /var/lib/awx/venv/ansible/bin/pip freeze

Tower のクラスターインストールでは、同じ virtualenv が全ローカルファイルシステムの /opt/my-envs/ に存在することを確認する必要があります。カスタムの virtualenv は、分離インスタンスでサポートされます。カスタムの仮想環境を使用する場合は、Tower ノードだけでなく、使用する分離ノードでコピーまたは複製する必要があります。コンテナーにカスタムの仮想環境を設定する方法は、『Ansible Tower Administration Guide』の「Build custom virtual environments」を参照してください。

30.8.2. カスタムの virtualenv の割り当て

カスタムの virtualenv を作成したら、組織、プロジェクト、ジョブテンプレートのレベル別に割り当ててジョブ実行に使用できます。インベントリーソースにカスタムの virv でインベントリーの更新を実行できるように、このカスタムの virv を設定できます。そのインベントリーを使用したジョブでは、独自のルールに準拠し、この venv は使用しません。SCM インベントリーソースで venv が選択されていない場合は、リンクしたプロジェクトの venv を使用できます。組織にカスタムの venv を割り当てることができます。ただし、組織にカスタムの venvを割り当てる場合には、ジョブ実行にだけ使用されるため、この組織のインベントリー更新では使用されません。

以下では、任意のレベルでカスタムの venv を正しく割り当てる方法を説明します。

PATCH https://awx-host.example.org/api/v2/organizations/N/
PATCH https://awx-host.example.org/api/v2/projects/N/
PATCH https://awx-host.example.org/api/v2/job_templates/N/
PATCH https://awx-host.example.org/api/v2/inventory_sources/N/

Content-Type: application/json
{
        'custom_virtualenv': '/opt/my-envs/custom-venv'
}

/api/v2/config/ への HTTP GET 要求では、インストール済みの virtualenvs の検出一覧が返されます。

{
        "custom_virtualenvs": [
                "/opt/my-envs/custom-venv",
                "/opt/my-envs/my-other-custom-venv",
        ],
...
}

Ansible Tower ユーザーインターフェースの対象の編集画面から、組織、プロジェクトおよびジョブテンプレートに割り当てる仮想環境を指定することも可能です。以下の例で示されるように、Ansible 環境 ドロップダウンメニューから virtualenv を選択してください。

_images/organizations-ansible-env-virtualenv-list.png

ジョブテンプレートの起動時に、ジョブの詳細ペーで指定した virtualenv も表示されます。

_images/jobs-show-job-details-venv.png

30.9. 通知用の towerhost のホスト名設定

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

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

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

30.10. curl でのジョブの起動

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

ジョブテンプレート ID が '1' で、Tower の 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 アドレス

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

  • Tower のインターフェースでインベントリーを選択します。

  • ソースが AWS に設定されたグループをクリックして、ソースタブをクリックします。

  • 「ソース変数」ボックスで vpc_destination_variable: private_ip_address を入力します。

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

注釈

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

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

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

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

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

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

30.13. Ansible ソースから提供されるリリース前のモジュールを Tower で使用する方法

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

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

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

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

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

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

注釈

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

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

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

_images/configure-tower-jobs-callback.png

注釈

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

30.15. winrm での Windows への接続

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

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

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

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

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

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

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

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

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

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

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

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

awx-manage inventory_import --source=inventory/ \
  --inventory-name="My Tower 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 形式にフォーマットします。

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