Unverified Commit 4afe1c96 authored by Matthew Jones's avatar Matthew Jones Committed by GitHub

Merge pull request #496 from AlanCoding/actual_docs

Put docs into the actual docs site
parents 344b80b5 8d456fca
......@@ -73,8 +73,6 @@ resource fields, unless specified.
Any usage errors or connection exceptions are thrown as subclasses of ``tower_cli.exceptions.TowerCLIError``, see
'Exceptions' section below for details.
Table of Contents
.. toctree::
:maxdepth: 1
:caption: Environment Setup
......@@ -82,6 +80,9 @@ Table of Contents
API Reference Table of Contents
.. toctree::
:maxdepth: 1
:caption: Resource List
Example Commands
Examples here are intended to give concrete examples of how the CLI can
be used in an automated way. It can also help with testing or the
defining of feature requests.
Expect the setup script to take up to 2 minutes to run. Most of this
time is waiting for the project source control to sync the examples from
github to the tower server.
You should have a version of tower running and configured in the CLI in
order to run any scripts or commands here. With your specific data, that
can done by the following commands:
.. code:: bash
$ tower-cli config host tower.example.com
$ tower-cli config username leeroyjenkins
$ tower-cli config password myPassw0rd
Jobs demonstrated in the script do not connect to another machine, and
do not require valid machine credentials, so tower-cli config
information should be all the unique information necessary.
Create Fake Data
You may want to reference the `fake data
creator <https://github.com/ansible/tower-cli/blob/master/docs/examples/fake_data_creator.sh>`__
for examples on how to create different types of resources.
If you want to run the script, which auto-populates your Tower server
with a small set of fake data, run the following:
.. code:: bash
# Populate the server with fake data and run test jobs
$ cd docs/source/cli_ref/examples/
$ source fake_data_creator.sh
Cleaning Up
The teardown script removes all of the objects that the CLI can easily
remove. This is not a perfect cleanup, but it performs well enough to
get the system ready to run the fake data creator script again.
.. code:: bash
# Delete the data that was created (with some exceptions)
$ source fake_data_teardown.sh
It is strongly suggested that you only run these scripts on testing
versions of an Ansible Tower host in order to avoid unintended naming
Python Module Use Example
This bash script example borrows fake data elements from the `tower
populator script <https://github.com/jsmartin/tower_populator>`__. The
tower\_populator script provides an example of how to use the tower-cli
python modules.
......@@ -226,3 +226,21 @@ are action-specific options, they provide fine-grained modification of the behav
example, ``--fail-on-found`` option of a ``create`` action will fail the command if a matching record already
exists in Tower backend; global options are used to set runtime configuration settings, functioning the same way
as context manager ``tower_cli.conf.Settings.runtime_values`` in :ref:`api-ref-conf`.
.. toctree::
:maxdepth: 0
:caption: Usage Guides
.. toctree::
:maxdepth: 1
:caption: Examples
.. _cli_ref:
Config Command Options
key-value options available for ``tower-cli config <key> <value>`` command
| *Key* | *Value | *Description* |
| | Type/Default* | |
| ``col | Boolean/'true' | Whether to use colored output for highlighting |
| or`` | | or not. |
| ``for | String with | Output format. The "human" format is intended |
| mat`` | options ('human', | for humans reading output on the CLI; the "json" |
| | 'json', | and "yaml" formats provide more data. |
| | 'yaml')/'human' | |
| ``hos | String/' | The location of the Ansible Tower host. HTTPS is |
| t`` | ' | assumed as the protocol unless "http://" is |
| | | explicitly provided. |
| ``pas | String/'' | Password to use to authenticate to Ansible |
| sword | | Tower. |
| `` | | |
| ``use | String/'' | Username to use to authenticate to Ansible |
| rname | | Tower. |
| `` | | |
| ``ver | Boolean/'true' | Whether to force verified SSL connections. |
| ify_s | | |
| sl`` | | |
| ``ver | Boolean/'false' | Whether to show information about requests being |
| bose` | | made. |
| ` | | |
| ``des | Boolean/'false' | Whether to show description in human-formatted |
| cript | | output. |
| ion_o | | |
| n`` | | |
| ``cer | String/'' | Path to a custom certificate file that will be |
| tific | | used throughout the command. Ignored if |
| ate`` | | ``--insecure`` flag if set in command or |
| | | ``verify_ssl`` is set to false |
| ``use | Boolean/'false' | Whether to use token-based authentication. |
| _toke | | |
| n`` | | |
Environment Variables
All of the above options can also be set using environment variables.
The default behavior is to allow environment variables to override your
tower-cli.cfg settings, but they will not override config values that
are passed in on the command line at runtime. Below is a table of the
available environment variables.
Variable Mapping
| *Environment Variable* | *Tower Config Key* |
| ``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`` |
| ``TOWER_USE_TOKEN`` | ``use_token`` |
- Under the hood we use the SSL functionality of requests, however the
current requests version has checkings on a deprecated SSL
certificate field ``commonName`` (deprecated by RFC 2818). In order
to prevent any related usage issues, please make sure to add
``subjectAltName`` field to your own certificate in use. We will
update help docs as soon as changes are made on the requests side.
.. _cli_ref:
Notification Template Management
Introduction - What Notification Templates Are
Starting with Ansible Tower 3.0, users can create and associate
notification templates to job templates. Whenever a job template
undergoes a successful/unsuccessful job run, all its related
notification templates will send out notifications to corresponding
notification receiver, indicating the status of job run.
Managing Notification Templates with tower-cli
To see the commands available for notification templates, see
``tower-cli notification_template --help``. Within a specific command,
get the help text with
``tower-cli notification_template <command> --help``.
Notification templates suppport all typical CRUD operations that control
other resources through tower-cli: ``get``, ``list``, ``create``,
``modify`` and ``delete``. On the other hand, uses can use new command
``tower-cli job_template associate_notification`` and
``tower-cli job_tempate disassociate_notification`` to (dis)associate an
existing notification to/from a job template.
Basic Operations
CRUD operations on notification templates are basically the same as that
of typicall existing resources, e.g. ``inventory``. There are, however,
some points due to the nature of notification templates that needs to be
careful with:
- There are two options in ``create``, ``--job-template`` and
``--status``, which controls the create mode: providing these options
will create a new notification template and associate it with the
specified job template. Notification templates will be created
isolatedly if these options are not provided. You can find more
information in Tower's official documentation.
- When looking at the help text of certain notification template
commands, note a large portion of the available options are prefixed
by a label like ``[slack]``. These are special configuration-related
options which are composing elements of a notification template's
destination configuration. You can find more information about those
options in Tower's official documentations. These options plus
``--notification-configuration`` option form configuration-related
- Configuration-related options are *not* functioning options in
``get``, ``list`` and ``delete``, meaning they will be ignored under
these commands even provided.
- The label prefixing configuration-related options indicate the type
of notification destination this option is used for. When creating a
new notification template with certain destination type (controlled
by ``--notification-type`` option), *all non-default* related
configuration-related options must be provided.
- When modifying an existing notification template, not every
configuration-related option has to be provided(but encryped fields
must, even you are not changing it!). But if this modification
modifies destination type, *all non-default* related
configuration-related options must be provided.
- ``--notification-configuration`` option provides a json file
specifying the configuration details. All other configuration-related
options will be ignored if \`--notification-configuration\`\` is
Detailed Example
.. code:: bash
# Create a notification template in isolation.
tower-cli notification_template create --name foo --description bar --notification-type slack --channels a --channels b --token hey --organization Default
# Create a notification template under an existing job template.
tower-cli notification_template create --name foo --description bar --notification-type slack --channels a --channels b --token hey --job-template 5 --organization Default
# Get exactly one notification template.
tower-cli notification_template get --name foo
# Get a list of notification templates under certain criteria.
tower-cli notification_template list --notification-type irc
# Modify an existing notification.
tower-cli notification_template modify --description foo --token hi 17
# Delete an existing notification template.
tower-cli notification_template delete --name foo
# Associate a job template with an existing notification template.
tower-cli job_template associate_notification_template --job-template 5 --notification-template 3
# Disassociate a job template with an existing notification template.
tower-cli job_template disassociate_notification_template --job-template 5 --notification-template 3
.. _cli_ref:
Role Management
Introduction - What Roles Are
Starting with Ansible Tower 3.0, roles are the objects used to manage
permissions to various resources within Tower. Each role represents:
- A type of permission like "use", "update", or "admin"
- A resource that this permission applies to, like an inventory or
This is "Role Based Access Control" or RBAC. Each role may have several
users associated with it, where each of the users gains the specified
type of permission. Teams may also be associated with a role, in which
case all users who are members of the team receive the specified type of
Managing Roles with tower-cli
To see the commands available for roles, see ``tower-cli roles``. Within
a specific command, get the help text with
``tower-cli roles list --help``.
The arguments for all role commands follow the same pattern, although
not all arguments are mandatory for all commands. The structure follows
the following pattern:
tower-cli role <action> --type <choice> --user/team <name/pk> --resource <name/pk>
Roles do not have the typical CRUD operations that control other
resources through tower-cli. Roles can not be deleted or created on
their own, because they are tied to the resource that they reference.
The next section covers what the possible actions are.
Basic Operations
The primary use case for roles is adding or removing users and teams
from roles. In the following example, a user is added to the project
"use" role.
tower-cli role grant --type use --user test_user --project test_project
In the above command "test\_user" is the username of a user to receive
the new permission, "test\_project" is the name of the project they are
receiving permission for, and "use" is the type of permission they are
receiving. Specifically, this allows test\_user to use test\_project in
a job template.
In a similar fashion, to remove the user from that role:
tower-cli role revoke --type use --user test_user --project test_project
To list the roles on that project:
tower-cli role list --project test_project
Detailed Example
The following commands will create an inventory and user and demonstrate
the different role commands on them.
.. code:: bash
# Create the inventory and list its roles
tower-cli inventory create --name 'test_inventory' --organization 'Default'
tower-cli role list --inventory 'test_inventory'
tower-cli role get --type 'use' --inventory 'test_inventory'
# Create a user, give access to the inventory and take it away
tower-cli user create --username 'test_user' --password 'pa$$' --email 'user@example.com'
tower-cli role grant --type 'use' --user 'test_user' --inventory 'test_inventory'
tower-cli role list --user 'test_user' --type 'use'
tower-cli role revoke --type 'use' --user 'test_user' --inventory 'test_inventory'
# Create a team, give access to the inventory and take it away
tower-cli team create --name 'test_team' --organization 'Default'
tower-cli role grant --type 'use' --team 'test_team' --inventory 'test_inventory'
tower-cli role list --team 'test_team' --type 'use'
tower-cli role revoke --type 'use' --team 'test_team' --inventory 'test_inventory'
Organization and Team Roles
For assigning users to teams and organizations, include the team or
organization flag, and it will be acted on as the resource. Note that
teams can be either the resource or the role grantee, depending of
whether the ``--team`` or the ``--target-team`` flag is used.
The following example appoints ``test_user`` to the member role of a
team and of an organization.
.. code:: bash
tower-cli role grant --user 'test_user' ---target-team 'test_team' --type 'member'
tower-cli role grant --organization 'Default' --user 'test_user' --type 'member'
These commands are redundant with the tower-cli organization and team
``associate`` and ``disassociate`` commands.
.. _cli_ref:
Survey Management
This feature is added in v3.1.0, and v3.1.3 or higher, at least, is
get help: ``tower-cli job_template survey --help``
View a Survey
The name of the job template is known ("survey jt" in this example), and
the survey definition is desired.
``tower-cli job_template survey --name="survey jt"``
Example output, this is the survey spec:
.. code:: json
"description": "",
"spec": [
"required": true,
"min": null,
"default": "v3.1.3",
"max": null,
"question_description": "enter a version of tower-cli to install",
"choices": "v3.0.0\nv3.0.1\nv3.0.2\nv3.1.0\nv3.1.1\nv3.1.2\nv3.1.3",
"new_question": true,
"variable": "version",
"question_name": "Tower-cli version",
"type": "multiplechoice"
"required": true,
"min": null,
"default": "click\ncolorama\nrequests\nsix\nPyYAML",
"max": null,
"question_description": "which package requirements would you like to install/check",
"choices": "click\ncolorama\nrequests\nsix\nPyYAML",
"new_question": true,
"variable": "packages",
"question_name": "Package requirements",
"type": "multiselect"
"name": ""
Save a survey
Use the job template ``modify`` command to do this. In order to create a
*functional* survey you must do two things:
- Save the survey spec - use the ``--survey-spec`` option
- Enable the survey - use the ``--survey-enabled`` option
Example of enabling the survey on a job template:
``tower-cli job_template modify --name="hello world infinity" --survey-enabled=true``
The ``--survey-spec`` option can get the spec from a file by prepending
the ``@`` character. If this character is not used, it is assumed that
you are giving the JSON data in-line.
Copy a survey to another template
The following example saves a survey spec to a file, and then uploads
that survey spec to another job template.
.. code:: bash
# Save the survey spec to file in local directory
tower-cli job_template survey --name="survey jt" > s.json
# Upload that survey to another job template
tower-cli job_template modify --name="another jt" --survey-spec=@s.json --survey-enabled=true
The next example using one line to do the same thing on the command
tower-cli job_template modify --name="another jt" --survey-spec="$(tower-cli job_template survey --name='survey jt')" --survey-enabled=true
Workflows can also have surveys and follow the same pattern. Example:
``tower-cli workflow survey --name="workflow with survey"``
.. _cli_ref:
Workflow Management
These docs show how to populate an example workflow in Tower and how to
automate the creation or copying of workflows.
Normal CRUD
Workflows and workflow nodes can be managed as normal tower-cli
Workflow Creation
Create an empty workflow:
tower-cli workflow create --name="workflow1" --organization="Default" --description="example description"
Check the existing workflows with the standard list or get commands.
tower-cli workflow list --description-on
Node Creation
Create nodes inside the workflow These all become "root" nodes and will
spawn jobs on workflow launch without any dependencies on other nodes.
These commands create 2 root nodes.
tower-cli node create -W workflow1 --job-template="Hello World"
tower-cli node create -W workflow1 --job-template="Hello World"
List the nodes inside of the workflow
tower-cli node list -W workflow1
Node Association
From the list command, you can find the ids of nodes you want to link
``assocate_success_node`` will cause the 2nd node to run on success of
the first node. The following command causes node 2 to run on the event
of successful completion of node 1.
tower-cli node assocate_success_node 1 2
This operation is only possible when node 2 is a root node. See the
Tower documentation for the limitations on the types of node connections
Auto-creation of the success node, only knowing the parent node id:
tower-cli node assocate_success_node 8 --job-template="Hello world"
Corresponding disassociate commands are also available. Disassociating a
node from another node will make it a root node.
Node Network Bulk Management
To print out a YAML representation of the nodes of a workflow, you can
use the following command. JSON format is also allowed.
tower-cli workflow schema workflow1
Here, "workflow1" is the name of the workflow.
Creating/updating a Schema Definition
To bulk-create or buld-update a workflow node network, use the workflow
schema command. The schema is JSON or YAML content, and can be passed in
the CLI argument, or pointed to a file. The schema is passed as a second
positional argument, where the first argument references the workflow.
tower-cli workflow schema workflow2 @schema.yml
The schema can be provided without using a file:
tower-cli workflow schema workflow2 '[{"job_template": "Hello world"}]'
The Schema definition defines the hierarchy structure that connects the
nodes. Names, as well as other valid parameters for node creation, are
acceptable inside of the node's entry inside the schema definition.
Links must be declared as a list under a key that starts with "success",
"failure", or "always". The following is an example of a valid schema
Example ``schema.yml`` file:
.. code:: yaml
- job_template: Hello world
- inventory_source: AWS servers (AWS servers - 42)
- project: Ansible Examples
- job_template: Echo variable
- job_template: Scan localhost
This style may be useful to apply in a script to create a workflow
network with a tower-cli command after the constituent resources like
the job templates and projects were created by preceding tower-cli
Differences with Machine Formatted Schemas
After writing a workflow schema, you may notice differences in how
tower-cli subsequently echos the schema definition back to you. The
following is what tower-cli might return after writing the above
.. code:: yaml
- failure_nodes:
- inventory_source: 42
job_template: 45
- always_nodes:
- job_template: 55
- job_template: 44
project: 40
Note that the root node data starts with "failure\_nodes", instead of
the name of the job template. This will not impact functionality, and
manually changing the order will not impact functionality either.
Although this format is harder to read, it does the same thing as the
previous schema. The ability to both echo and create schemas can be used
to copy the contents of one workflow to another.
As an example, consider 2 workflows. The first has a name "workflow1",
and has its node network populated. The second is named "workflow2" and
is empty. The following commands will copy the structure from the first
to the second.
.. code:: bash
tower-cli workflow schema workflow1 > schema.yml
tower-cli workflow schema workflow2 @schema.yml
The workflow schema feature populates the workflow node network based on
the hierarchy structure. Before creating each node, it attempts to find
an existing node with the specified properties in that location in the
tree, and will not create a new node if it exists. Also, if an existing
node has no correspondence in the schema, the entire sub-tree based on
that node will be deleted.
Thus, after running the schema command, the resulting workflow topology
will always be exactly the same as what is specified in the given schema
file. To continue with the previous example, subsequent invocations of:
.. code:: bash
tower-cli workflow schema workflow2 @schema.yml
tower-cli workflow schema workflow2 @schema.yml
should not change the network of workflow2, since ``schema.yml`` file
itself remains unchanged. However
.. code:: bash
tower-cli workflow schema workflow2 @new_schema.yml
will modify topology of workflow2 to exactly the same as what is
specified in ``new_schema.yml``.
Launching Workflow Jobs
Use the workflow\_job resource to launch workflow jobs. This supports
the use of extra\_vars, which can contain answers to survey questions.
The ``--monitor`` and ``--wait`` flag are available to poll the server
until workflow job reaches a completed status. The ``--monitor`` option
will print rolling updates of the jobs that ran as part of the workflow.
Here is an example of using those features:
tower-cli workflow_job launch -W "echo Hello World" -e a=1 --monitor
......@@ -37,9 +37,8 @@ Table of Contents
:maxdepth: 2