kayobe/doc/source/usage.rst
Mark Goddard c852c59a51 Fix path to virtualenv in usage guide
Change-Id: Ia200efce040a009bbb35292cf846d36f2edb259b
Story: 2003107
Task: 23224
2018-07-30 09:21:42 +01:00

70 lines
2.4 KiB
ReStructuredText

=====
Usage
=====
Command Line Interface
======================
.. note::
Where a prompt starts with ``(kayobe)`` it is implied that the user has
activated the Kayobe virtualenv. This can be done as follows::
$ source /path/to/venv/bin/activate
To deactivate the virtualenv::
(kayobe) $ deactivate
To see information on how to use the ``kayobe`` CLI and the commands it
provides::
(kayobe) $ kayobe help
As the ``kayobe`` CLI is based on the ``cliff`` package (as used by the
``openstack`` client), it supports tab auto-completion of subcommands. This
can be activated by generating and then sourcing the bash completion script::
(kayobe) $ kayobe complete > kayobe-complete
(kayobe) $ source kayobe-complete
Working with Ansible Vault
--------------------------
If Ansible vault has been used to encrypt Kayobe configuration files, it will
be necessary to provide the ``kayobe`` command with access to vault password.
There are three options for doing this:
Prompt
Use ``kayobe --ask-vault-pass`` to prompt for the password.
File
Use ``kayobe --vault-password-file <file>`` to read the password from a
(plain text) file.
Environment variable
Export the environment variable ``KAYOBE_VAULT_PASSWORD`` to read the
password from the environment.
Limiting Hosts
--------------
Sometimes it may be necessary to limit execution of kayobe or kolla-ansible
plays to a subset of the hosts. The ``--limit <SUBSET>`` argument allows the
kayobe ansible hosts to be limited. The ``--kolla-limit <SUBSET>`` argument
allows the kolla-ansible hosts to be limited. These two options may be
combined in a single command. In both cases, the argument provided should be
an `Ansible host pattern
<http://docs.ansible.com/ansible/latest/intro_patterns.html>`_, and will
ultimately be passed to ``ansible-playbook`` as a ``--limit`` argument.
Tags
----
`Ansible tags <http://docs.ansible.com/ansible/latest/playbooks_tags.html>`_
provide a useful mechanism for executing a subset of the plays or tasks in a
playbook. The ``--tags <TAGS>`` argument allows execution of kayobe ansible
playbooks to be limited to matching plays and tasks. The ``--kolla-tags
<TAGS>`` argument allows execution of kolla-ansible ansible playbooks to be
limited to matching plays and tasks. The ``--skip-tags <TAGS>`` and
``--kolla-skip-tags <TAGS>`` arguments allow for avoiding execution of matching
plays and tasks.