25. Tower のヒントと裏技¶

25.1. Tower CLI ツールの使用¶

Ansible Tower には、機能が豊富に搭載されたコマンドラインインターフェースがあります。この CLI は、Tower の REST API 経由で Tower と通信します。Tower マシンにアクセスできるマシンから、または Tower 自体からインストールすることができます。

pip コマンドを使用してインストールを行います。

pip install ansible-tower-cli

設定および用途に関する説明は、「tower-cli の概要」および https://github.com/ansible/tower-cli/blob/master/README.rst を参照してください。

25.2. API でのジョブテンプレートの起動¶

Ansible Tower では、Tower API からのジョブテンプレートをもとに、あるいは tower-cli コマンドラインツールを使用してジョブを簡単に起動できます。

ジョブテンプレートを起動すると、以下の設定が行われます。

ジョブレコードを作成します。
ジョブテンプレート上の属性すべてをジョブレコードに指定し、その起動エンドポイント (「ランタイム」データ) で指定可能な特定のデータと統合します。
JT およびランタイムデータからの統合データで Ansible を実行します。

ランタイムデータは、ジョブテンプレートの ask_ _on_launch が True に設定されている場合にジョブテンプレートデータより優先されます。たとえば、ランタイムの認証情報は、ジョブテンプレートで ask_credential_on_launch が True に設定されている場合のみ受け入れられます。

API 経由でジョブテンプレートを起動する場合には、以下のワークフローに従ってください。

GET https://your.tower.server/api/v2/job_templates/<your job template id>/launch/: 応答には、ジョブテンプレートに関する情報を提供する job_template_data および defaults などのデータが含まれます。
返されたデータに起動に必要なランタイムデータがないか確認します。また、起動エンドポイントの OPTIONS を検査すると、POST フィールドで許可されている内容を推測しやすくなる場合があります。
警告

特定のランタイム認証情報を指定すると、passwords_needed_to_start で提示されていないパスワードが必要になってくる場合があります。
- passwords_needed_to_start: 必要なパスワードの一覧
- credential_needed_to_start: ブール値
- inventory_needed_to_start: ブール値
- variables_needed_to_start: extra_vars 欄内に渡す必要のあるフィールド一覧
ユーザーが求めたランタイムデータでオプションで許可できるものがあるか、返されたデータを確認します。
- ask_variables_on_launch: extra_vars 内の Ansible に渡す追加の変数を入力するようにユーザーに求めるかどうかを指定するブール値
- ask_tags_on_launch: 起動時に job_tags の入力をユーザーに求めるかどうかを指定するブール値 (便宜上 skip_tags の使用が可能)
- ask_job_type_on_launch: 起動時に job_type の入力をユーザーに求めるかどうかを指定するブール値
- ask_limit_on_launch: 起動時に limit の入力をユーザーに求めるかどうかを指定するブール値
- ask_inventory_on_launch: 起動時に関連の inventory フィールドの入力をユーザーに求めるかどうかを指定するブール値
- ask_credential_on_launch: 起動時に関連の credential フィールドの入力をユーザーに求めるかどうかを指定するブール値
- survey_enabled: 以下のジョブテンプレートの survey_spec Q&A 形式に準拠する追加の extra_vars の入力をユーザーに求めるかどうかを指定するブール値
以前の手順で収集した必須データを使用して POST https://your.tower.server/api/v2/job_templates/<your job template id>/launch/ を実行します。このアクションの要求データで渡すことができる変数には以下が含まれます。
- extra_vars: 調査の質問への回答など、ユーザーが指定する変数を含む JSON または YAML 形式のディクショナリーで表現する文字列 (エスケープした括弧)。
- job_tags: 実行する Playbook にコンマ区切りのタグ一覧を表現する文字列
- limit: 稼働するホストまたはグループ (コンマ区切りリスト) を表現する文字列
- inventory: このジョブランで使用するインベントリーの外部キーの整数値
- credential: このジョブランで使用する認証情報の外部キーの整数値

POST は、ジョブに関するデータと、ランタイムデータが受け入れられるかどうかの情報を返します。ジョブ ID は、3.0 以前に記述されたツールとの互換性を保つために job フィールドで指定します。応答は以下のようになります。

{
  "ignored_fields": {
    "credential": 2,
    "job_tags": "setup,teardown"
  }
  "id": 4,
  ...more data about the job...
  "job": 4,
}

この例では、credential および job_tags の値を指定し、ジョブテンプレートの ask_credential_on_launch と ask_tags_on_launch は False と指定しました。ジョブテンプレートの作成者がランタイムの値を使用する許可を行わなかったので、これらは却下されました。

この応答でジョブに関する詳細を確認できます。更新済みのステータスを取得するには、ジョブページ /jobs/4 への GET 要求を行うか、応答内の url リンクに従う必要があります。キャンセル、再起動などの関連のリンクも含まれます。

注釈

非実行ノードでジョブをクエリーすると、result_stdout フィールドおよび関連の stdout ページでエラーメッセージ「stdout capture is missing」が表示されます。stdout を生成するには、関連の stdout ページに format=txt_download クエリーパラメーターを使用してください。これにより、stdout ファイルが作成され、ジョブへの更新がされるか、関連の std がジョブ出力に表示されます。

注釈

スキャンジョブに対して起動する際には、新規インベントリーを割り当てることはできません。スキャンジョブは固定のインベントリーに紐付けする必要があります。

注釈

このタイプの "scan" に/から起動する際は、ジョブタイプを変更できません。ask_job_type_on_launch オプションのみが起動時に "run" と "check" の切り替えが可能です。

25.3. `tower-cli` ジョブテンプレートの起動¶

Tower コマンドラインから、ジョブテンプレートの起動方法として tower-cli を使用できます。

tower-cli の起動に関するヘルプは以下を使用します。

tower-cli job launch --help.

ジョブテンプレートから起動するには、以下と同様に tower-cli を呼び出します。

API の使用例として、-v フラグを追加することもできます。

tower-cli job launch --job-template=4 -v

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

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

awx-manage changepassword admin

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

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

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

awx-manage createsuperuser

25.6. ジャンプホストが 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>"'

25.7. Tower の使用時に JSON コマンドの Ansible の出力を表示する方法¶

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

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

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

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

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

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

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

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

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

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

ansible -m setup hostname

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

25.10. Ansible Tower での virtualenv の使用¶

Ansible Tower 3.0 以降では 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 を新たに作成することができます。

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

Tower では、別の virtualenv を指定して、ジョブテンプレートの実行で使用することができます。カスタムの virtualenv を選択するには、先に /var/lib/awx/venv/ に virtualenv を作成してください。

$ sudo virtualenv /var/lib/awx/venv/my-custom-venv

新たに作成した virtualenv では、正しく Playbook を実行するにはベースの依存関係がいくつか必要です (Tower は、Playbook のアーティファクトのプレースホルダーとして memcached を使用します)。

$ sudo /var/lib/awx/venv/my-custom-venv/bin/pip install python-memcached psutil

ここから、Ansible 自体の per-virtualenv バージョンなど、必要とされる Python の依存関係を追加でインストールできます。

$ sudo /var/lib/awx/venv/my-custom-venv/bin/pip install -U "ansible == X.Y.Z"

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

$ sudo /var/lib/awx/venv/my-custom-venv/bin/pip install -U python-digitalocean

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

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

Tower のクラスターインストールでは、同じ virtualenv が全ローカルファイルシステムの /var/lib/awx/venv/ に存在することを確認する必要があります。カスタムの virtualenv は、分離インスタンスでサポートされます。カスタムの仮想環境を使用する場合は、Tower ノードだけでなく、使用する分離ノードでコピーまたは複製する必要があります。

25.10.2. カスタムの virtualenv の割り当て¶

カスタムの virtualenv を作成したら、組織、プロジェクトおよびジョブテンプレートレベルでこの virtualenv を割り当てることができます。

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/

Content-Type: application/json
{
        'custom_virtualenv': '/var/lib/awx/venv/my-custom-venv'
}

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

{
        "custom_virtualenvs": [
                "/var/lib/awx/venv/my-custom-venv",
                "/var/lib/awx/venv/my-other-custom-venv",
        ],
...
}

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

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

25.11. 通知用の `towerhost` のホスト名設定¶

/etc/tower/settings.py で、TOWER_URL_BASE='https://tower.example.com' を編集して、通知のホスト名を変更します。https://tower.example.com は任意のホスト名に置き換えてください。変更を保存してから ansible-tower-service restart で Tower サービスを再起動する必要があります。

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

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

注釈

Tower では、「tower-cli」と呼ばれる機能満載のコマンドラインインターフェースが提供されるようになりました。curl の利用を検討されている場合には、便利なツールです。

curl でのジョブの起動は、Tower 2.1.x 以降のバージョンで機能します。

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 を含む文字列でなければなりません。引用をエスケープする場合などは注意してください。

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

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

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

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

注釈

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

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

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

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

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

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

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

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

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

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

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

25.16. 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 でサンプルのプラグインも確認してみてください。これらは、各サイトの目的に合わせて変更する必要があります。

これらのプラグインを使用するには、コールバックプラグインの .py ファイルを Tower プロジェクトの Playbook と合わせて、/callback_plugins というディレクトリーに配置します。

どのプロジェクトにも依存せず、コールバックをすべての Playbook に適用するには、以下のディレクトリーの 1 つに .py ファイルを配置してください (Linux ディストリビューションおよび Ansible のインストール方法により異なる)。

* /usr/lib/pymodules/python2.7/ansible/callback_plugins

* /usr/local/lib/python2.7/dist-packages/ansible/callback_plugins

* /usr/lib/python2.6/site-packages/ansible/callback_plugins

注釈

Ansible に同梱されているコールバックの大半をグローバルには適用するには、ansible.cfg の callback_whitelist セクションに追加します。

25.17. winrm での Windows への接続¶

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

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

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

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

25.18. 既存のインベントリーファイルおよびホスト/グループ変数の 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 形式にフォーマットします。

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