tower-cli は Ansible Tower のコマンドツールです。このツールでは、Tower コマンドが簡単に UNIX コマンドラインから実行できます。また、他の python アプリのクライアントライブラリーまたは、Tower REST API で API の対話を開発する他のユーザーの参照としても使用できます。
注釈
tower-cli ソフトウェアは現在開発中のオープンソースプロジェクトで、完全な実装が行われるまで Tower の機能のサブセットとしてのみ実装されます。
Tower は商用ライセンスのあるソフトウェアですが、tower-cli はオープンソースプロジェクトです。具体的には、このプロジェクトは Apache 2.0 ライセンスで提供されています。GitHub へのプル要求、寄稿、チケット起票にご協力お願いします。
tower-cli は Tower API にコマンドを送信します。Tower 内にある大半のオブジェクトを取得、作成、変更、削除することができます。
このツールは以下のような使い方が可能です。
tower-cli は PyPI <https://pypi.python.org/pypi/ansible-tower-cli>からパッケージとして入手できます。
推奨のインストール方法は pip を使用する方法です。
$ pip install ansible-tower-cli
このプロジェクトは主要なブランチは、直接ソースから使用することもできます。
tower-cli の詳細は、以下のプロジェクトページを参照してください。
tower-cli は、独自の設定を編集でき、ユーザーは直接設定ファイルを編集できるので、複数の方法で設定を行うことができます。
推奨される設定方法は tower-cli config コマンドを使用するものです。
$ tower-cli config key value
引数なしで tower-cli config コマンドを実行すると、設定オプションの完全一覧と、設定箇所が表示されます。デフォルトの動作では、環境変数が tower-cli.cfg 設定を上書きしますが、ランタイムにコマンドラインで渡す設定値は上書きされません。利用可能な環境変数および対応する Tower 設定キーは以下の通りです。
通常、最低でも ホスト、ユーザー名、パスワードの (Ansible Tower インスタンスの場所、Tower への認証に使用する認証情報) 3 つの設定オプションを指定する必要があります。
$ tower-cli config host tower.example.com
$ tower-cli config username leeroyjenkins
$ tower-cli config password myPassw0rd
設定ファイルは直接編集することもできます。設定ファイルは : または = で区切ったキーと値を含むシンプルなファイルです。
host: tower.example.com
username: admin
password: p4ssw0rd
設定ファイルの場所の優先順位は以下の通りです (優先度が低いものから高いものの順)。
/etc/awx/tower_cli.cfg (tower-cli config --global を使用して記述)~/.tower_cli.cfg (tower-cli config を使用して記述)tower-cli の呼び出しは一般的に以下の形式を取ります。
$ tower-cli {resource} {action} ...
resource は、user、organization、job_template など、Tower 内のオブジェクトタイプです。リソース名は常に Tower CLI (tower-cli users` ではなく tower-cli user を使用してください) では、単数形を使用するようにしてください。
action とは、実行するアイテムのことです (動詞)。多くの tower-cli リソースには get、list、create、modify、delete などのアクションと、Tower のオブジェクトにあるフィールドに適したオプションが含まれます。
アクションおよびリソースの例は以下を含むがそれに限定されるものではありません。
# List all users.
$ tower-cli user list
# List all non-superusers
$ tower-cli user list --is-superuser=false
# Get the user with the ID of 42.
$ tower-cli user get 42
# Get the user with the given username.
$ tower-cli user get --username=guido
# Create a new user.
$ tower-cli user create --username=guido --first-name=Guido \
--last-name="Van Rossum" [email protected]
# Modify an existing user.
# This would modify the first name of the user with the ID of "42" to "Guido".
$ tower-cli user modify 42 --first-name=Guido
# Modify an existing user, lookup by username.
# This would use "username" as the lookup, and modify the first name.
# Which fields are used as lookups vary by resource, but are generally
# the resource's name.
$ tower-cli user modify --username=guido --first-name=Guido
# Delete a user.
$ tower-cli user delete 42
# Launch a job.
$ tower-cli job launch --job-template=144
# Monitor a job.
$ tower-cli job monitor 95
# Get a list of groups.
$ tower-cli group --list.
# Sync a group by the groupID.
$ tower-cli group sync $groupID
疑問な点がある場合には、他のオプションがないかヘルプを参照してください。
$ tower-cli # help
$ tower-cli user --help # resource specific help
$ tower-cli user create --help # command specific help
Tower 3.1.0 および Tower-CLI 3.1.0 以降は、通常の CRUD アクションか、ワークフローネットワークを定義する YAML ファイルを使用して Tower-CLI からワークフローネットワークを管理することができます。
# Print out the schema for a workflow
$ tower-cli workflow schema workflow_name
# Create the network defined in file "schema.yml"
$ tower-cli workflow schema workflow_name @schema.yml
以下は、スキーマの一例です。
- job_template: Hello world
failure:
- inventory_source: AWS servers (AWS servers - 42)
success:
- project: Ansible Examples
always:
- job_template: Echo variable
success:
- job_template: Scan localhost
詳しい情報は、以下で tower-cli ワークフローのドキュメントを参照してください。
ジョブの起動時に Tower サーバーに追加の変数を渡す方法が複数あります。
--extra-vars="@filename.yml" のフラグを使用したファイルでデータを渡す方法--extra-vars="var: value" のフラグでランタイム時に yaml データを追加する方法これらの方法は組み合わせて使用することができます。たとえば、手動で追加の変数を指定した上に、ファイルを指定するなど、コマンドラインで複数回フラグを指定した場合には、これらの 2 つのソースが統合されて、Tower サーバーに送信されます。
# Launch a job with extra variables from filename.yml, and also a=5
$ tower-cli job launch --job-template=1 --extra-vars="a=5 b=3" \
--extra-vars="@filename.yml"
# Create a job template with that same set of extra variables
$ tower-cli job_template create --name=test_job_template --project=1 \
--inventory=1 --playbook=helloworld.yml \
--machine-credential=1 --extra-vars="a=5 b=3" \
--extra-vars="@filename.yml"
ジョブテンプレートを変更する場合には複数のソースを組み合せることはできません。空白は --extra-vars="a='white space'" などの文字列で使用することができ、list-valued パラメーターは key=value ではなく JSON または YAML で送信できます。たとえば --extra-vars="a: [1, 2, 3, 4, 5]" は、その一覧を使用して値としてパラメーター "a" を送信します。
注釈
追加の厳密な extra_vars 検証が Ansible Tower 3.0.0 で追加されました。ジョブ起動 API に渡される``extra_vars`` は、以下が True の場合のみ受け入れられます。
ask_variables_on_launch は True に設定します。デフォルトでは、Tower サーバーの SSL 証明書が検証できない場合には tower-cli によりエラーを発行します。未検証の SSL 接続を許可するには、config 変数``verify_ssl`` を true に設定してください。単一のコマンドを許可するには、--insecure フラグを追加します。
# Disable insecure connection warnings permanently
$ tower-cli config verify_ssl false
# Disable insecure connection warnings for just this command
$ tower-cli job_template list --insecure