move old docs into actual docs

parent 34b11e5f
......@@ -205,3 +205,22 @@ 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: 1
:caption: Usage Guides
usage/CONFIG_CMD_OPTIONS.rst
usage/NOTIFICATION_TEMPLATE_MANAGEMENT.rst
usage/ROLE_MANAGEMENT.rst
usage/SURVEYS.rst
usage/WORKFLOWS.rst
.. toctree::
:maxdepth: 1
:caption: Examples
examples/README.rst
examples/fake_data_creator.rst
examples/workflow_demo.rst
.. _cli_ref:
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/'127.0.0.1 | 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`` \|
Notes
-----
- 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:
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``.
The arguments for all notification template commands follow the same
pattern, although not all arguments are mandatory for all commands. The
structure follows the following pattern:
::
tower-cli role <action> <options>
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
options.
- 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
provided.
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:
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
credential
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
permission.
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:
How to manage surveys of job templates and workflows through tower-cli
======================================================================
This feature is added in v3.1.0, and v3.1.3 or higher, at least, is
recommended.
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
line.
::
tower-cli job_template modify --name="another jt" --survey-spec="$(tower-cli job_template survey --name='survey jt')" --survey-enabled=true
Workflows
---------
Workflows can also have surveys and follow the same pattern. Example:
``tower-cli workflow survey --name="workflow with survey"``
.. _cli_ref:
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
resources.
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
allowed.
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
definition.
Example ``schema.yml`` file:
.. code:: yaml
- 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
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
commands.
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
example.
.. code:: yaml
- failure_nodes:
- inventory_source: 42
job_template: 45
success_nodes:
- always_nodes:
- job_template: 55
success_nodes:
- 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
Idempotence
~~~~~~~~~~~
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
......@@ -34,12 +34,12 @@ Table of Contents
-----------------
.. toctree::
:maxdepth: 2
:maxdepth: 3
install.rst
VERSIONING.rst
quickstart.rst
api_ref/index.rst
VERSIONING.rst
cli_ref/index.rst
api_ref/index.rst
CONTRIBUTING.rst
HISTORY.rst
## key-value options available for `tower-cli config <key> <value>` command
| *Key* | *Value Type/Default* | *Description* |
|------------------|-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `color` | Boolean/'true' | Whether to use colored output for highlighting or not. |
| `format` | String with options ('human', 'json', 'yaml')/'human' | Output format. The "human" format is intended for humans reading output on the CLI; the "json" and "yaml" formats provide more data. |
| `host` | String/'127.0.0.1' | The location of the Ansible Tower host. HTTPS is assumed as the protocol unless "http://" is explicitly provided. |
| `password` | String/'' | Password to use to authenticate to Ansible Tower. |
| `username` | String/'' | Username to use to authenticate to Ansible Tower. |
| `verify_ssl` | Boolean/'true' | Whether to force verified SSL connections. |
| `verbose` | Boolean/'false' | Whether to show information about requests being made. |
| `description_on` | Boolean/'false' | Whether to show description in human-formatted output. |
| `certificate` | String/'' | Path to a custom certificate file that will be used throughout the command. Ignored if `--insecure` flag if set in command or `verify_ssl` is set to false |
| `use_token` | Boolean/'false' | Whether to use token-based authentication. |
## 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` |
## Notes
* 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.
## 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`.
The arguments for all notification template commands follow the same pattern, although
not all arguments are mandatory for all commands. The structure follows
the following pattern:
```
tower-cli role <action> <options>
```
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 options.
* 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 provided.