Documentation

10. tower-cli の概要

tower-cli は Ansible Tower のコマンドツールです。このツールでは、Tower コマンドが簡単に UNIX コマンドラインから実行できます。また、他の python アプリのクライアントライブラリーまたは、Tower REST API で API の対話を開発する他のユーザーの参照としても使用できます。

注釈

tower-cli ソフトウェアは現在開発中のオープンソースプロジェクトで、完全な実装が行われるまで Tower の機能のサブセットとしてのみ実装されます。

10.1. ライセンス

Tower は商用ライセンスのあるソフトウェアですが、tower-cli はオープンソースプロジェクトです。具体的には、このプロジェクトは Apache 2.0 ライセンスで提供されています。GitHub へのプル要求、寄稿、チケット起票にご協力お願いします。

10.2. 機能

tower-cli は Tower API にコマンドを送信します。Tower 内にある大半のオブジェクトを取得、作成、変更、削除することができます。

このツールは以下のような使い方が可能です。

  • Playbook 実行の起動 (例: Jenkins、TeamCity、Bamboo など)

  • ジョブステータスの確認

  • 組織、ユーザー、チームなどのオブジェクトの迅速な作成

10.3. インストール

tower-cli は、PyPI ではパッケージとして提供されます。

推奨のインストール方法は pip を使用する方法です。

$ pip install ansible-tower-cli

このプロジェクトは主要なブランチは、直接ソースから使用することもできます。

tower-cli の詳細は、https://github.com/ansible/tower-cli/ のプロジェクトページを参照してください。

10.4. Configuration (構成)

tower-cli は、独自の設定を編集でき、ユーザーは直接設定ファイルを編集できるので、複数の方法で設定を行うことができます。

10.4.1. tower-cli config での設定

推奨の設定方法は tower-cli config コマンドを使用する方法です。

$ tower-cli config key value

引数なしで tower-cli config コマンドを実行すると、設定オプションの完全一覧と、設定箇所が表示されます。デフォルトの動作では、環境変数が tower-cli.cfg 設定を上書きしますが、ランタイム時にコマンドラインで渡す設定値は上書きされません。利用可能な環境変数および対応する Tower 設定キーは以下の通りです。

  • TOWER_COLOR: color

  • TOWER_FORMAT: format

  • TOWER_HOST: host

  • TOWER_PASSWORD: password

  • TOWER_USERNAME: username

  • TOWER_VERIFY_SSL: verify_ssl

  • TOWER_VERBOSE: verbose

  • TOWER_DESCRIPTION_ON: description_on

  • TOWER_CERTIFICATE: certificate

通常、最低でも ホスト、ユーザー名、パスワードの (Ansible Tower インスタンスの場所、Tower への認証に使用する認証情報) 3 つの設定オプションを指定する必要があります。

$ tower-cli config host tower.example.com
$ tower-cli config username leeroyjenkins
$ tower-cli config password myPassw0rd

10.4.2. config ファイルへの直接書き込み

設定ファイルは直接編集することもできます。設定ファイルは : または = で区切ったキーと値を含むシンプルなファイルです。

host: tower.example.com
username: admin
password: p4ssw0rd

10.4.3. ファイルの場所

設定ファイルの場所の優先順位は以下の通りです (優先度が低いものから高いものの順)。

  • 内部のデフォルト

  • /etc/tower/tower_cli.cfg (tower-cli config --global で記述)

  • ~/.tower_cli.cfg (tower-cli config で記述)

  • ランタイムのパラメーター

10.4.4. 使用法

tower-cli の呼び出しは通常、以下の形式を取ります。

$ tower-cli {resource} {action} ...

resource は、userorganizationjob_template など、Tower 内のオブジェクトタイプです。リソース名は常に Tower CLI (tower-cli users ではなく tower-cli user を使用してください) では、単数形を使用するようにしてください。

action とは、実行するアイテムのことです (動詞)。多くの tower-cli リソースには listcreatemodifydelete などのアクションと、Tower のオブジェクトにあるフィールドに適したオプションが含まれます。

アクションおよびリソースの例は以下を含むがそれに限定されるものではありません。

10.4.4.1. ユーザーアクション

# 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

10.4.4.2. ジョブアクション

# Launch a job.
$ tower-cli job launch --job-template=144

# Monitor a job.
$ tower-cli job monitor 95

10.4.4.3. グループアクション

# 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

10.4.4.4. ワークフローアクション

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

詳しい情報は、https://github.com/ansible/tower-cli/blob/master/docs/WORKFLOWS.md で tower-cli ワークフローのドキュメントを参照してください。

10.4.5. 追加の変数の指定

ジョブの起動時に 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 の場合のみ受け入れられます。

  • それらは有効な survey の変数に対応するものである。

  • ask_variables_on_launch が True に設定されている。

10.4.6. SSL の警告

デフォルトでは、Tower サーバーの SSL 証明書が検証できない場合には tower-cli がエラーを発行します。未検証の SSL 接続を許可するには、config 変数``verify_ssl = false`` を true に設定してください。true に設定されている場合に、単一のコマンドが verify_ssl を上書きできるようにするには、--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