86 lines
3.1 KiB
ReStructuredText
86 lines
3.1 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 four 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: ``KAYOBE_VAULT_PASSWORD``
|
|
Export the environment variable ``KAYOBE_VAULT_PASSWORD`` to read the
|
|
password from the environment.
|
|
Environment variable: ``ANSIBLE_VAULT_PASSWORD_FILE``
|
|
Export the environment variable ``ANSIBLE_VAULT_PASSWORD_FILE`` to read the
|
|
password from a (plain text) file, with the path to that file being read
|
|
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.
|
|
|
|
.. _usage-tags:
|
|
|
|
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.
|
|
|
|
Check and diff mode
|
|
-------------------
|
|
|
|
Ansible supports `check and diff modes
|
|
<https://docs.ansible.com/ansible/latest/user_guide/playbooks_checkmode.html>`_,
|
|
which can be used to improve visibility into changes that would be made on
|
|
target systems. The Kayobe CLI supports the ``--check`` argument, and since
|
|
11.0.0, the ``--diff`` argument. Note that these modes are not always
|
|
guaranteed to work, when some tasks are dependent on earlier ones.
|