diff --git a/doc/source/developer-docs/index.rst b/doc/source/developer-docs/index.rst index de2053eec4..9502caef83 100644 --- a/doc/source/developer-docs/index.rst +++ b/doc/source/developer-docs/index.rst @@ -19,4 +19,3 @@ Contents: bug-triage core-reviewers role-services - inventory diff --git a/doc/source/index.rst b/doc/source/index.rst index 1ac3598ea2..cef8f98b88 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -23,6 +23,7 @@ review. upgrade-guide/index developer-docs/index + inventory/index .. _Ocata series timeline: https://launchpad.net/openstack-ansible/trunk .. _Ocata series release notes: http://docs.openstack.org/releasenotes/openstack-ansible/unreleased.html diff --git a/doc/source/inventory/configure-inventory.rst b/doc/source/inventory/configure-inventory.rst new file mode 100644 index 0000000000..6ae9fdc870 --- /dev/null +++ b/doc/source/inventory/configure-inventory.rst @@ -0,0 +1,57 @@ +========================= +Configuring the inventory +========================= + +Changing the base environment directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``--environment/-e`` argument will take the path to a directory containing +an ``env.d`` directory. This defaults to ``playbooks/inventory/`` in the +OpenStack-Ansible codebase. + +Contents of this directory are populated into the environment *before* the +``env.d`` found in the directory specified by ``--config``. + + +Checking inventory configuration for errors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Using the ``--check`` flag when running ``dynamic_inventory.py`` will run the +inventory build process and look for known errors, but not write any files to +disk. + +If any groups defined in the ``openstack_user_config.yml`` or ``conf.d`` files +are not found in the environment, a warning will be raised. + +This check does not do YAML syntax validation, though it will fail if there +are unparseable errors. + +Writing debug logs +~~~~~~~~~~~~~~~~~~~ + +The ``--debug/-d`` parameter allows writing of a detailed log file for +debugging the inventory script's behavior. The output is written to +``inventory.log`` in the current working directory. + +The ``inventory.log`` file is appended to, not overwritten. + +Like ``--check``, this flag is not invoked when running from ansible. + +Configuration constraints +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The lxc_hosts Group +------------------- + +When the dynamic inventory script creates a container name, the host on +which the container resides is added to the ``lxc_hosts`` inventory group. + +Using this name for a group in the configuration will result in a runtime +error. + +Dynamic Inventory API documentation +----------------------------------- + +.. automodule:: dynamic_inventory + :members: + diff --git a/doc/source/inventory/index.rst b/doc/source/inventory/index.rst new file mode 100644 index 0000000000..dea89d0c89 --- /dev/null +++ b/doc/source/inventory/index.rst @@ -0,0 +1,17 @@ +========= +Inventory +========= + +OpenStack-Ansible uses an included script to generate the inventory of hosts +and containers within the environment. This script is called by Ansible +through its `dynamic inventory functionality `_. + +In this section, you will find documentation relevant to the inventory +for OpenStack-Ansible. + +.. toctree:: + :maxdepth: 2 + + generate-inventory + configure-inventory + manage-inventory diff --git a/doc/source/inventory/inventory.rst b/doc/source/inventory/inventory.rst new file mode 100644 index 0000000000..21c2ec42e3 --- /dev/null +++ b/doc/source/inventory/inventory.rst @@ -0,0 +1,97 @@ +======================== +Generating the Inventory +======================== + +The script that creates the inventory is located at +``playbooks/inventory/dynamic_inventory.py``. + +Executing the dynamic_inventory.py script +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When running an Ansible command (such as ``ansible``, ``ansible-playbook`` or +``openstack-ansible``) Ansible executes the ``dynamic_inventory.py`` script +and use its output as inventory. + +Run the following command: + +.. code-block:: bash + + # from the playbooks directory + inventory/dynamic_inventory.py --config /etc/openstack_deploy/ + +This invocation is useful when testing changes to the dynamic inventory script. + +Inputs +~~~~~~ + +The ``dynamic_inventory.py`` takes the ``--config`` argument for the directory +holding configuration from which to create the inventory. If not specified, +the default is ``/etc/openstack_deploy/``. + +In addition to this argument, the base environment skeleton is provided in the +``playbooks/inventory/env.d`` directory of the OpenStack-Ansible codebase. + +Should an ``env.d`` directory be found in the directory specified by +``--config``, its contents will be added to the base environment, overriding +any previous contents in the event of conflicts. + +.. note:: + + In all versions prior to |previous_release_formal_name|, this argument was ``--file``. + +The following file must be present in the configuration directory: + + * ``openstack_user_config.yml`` + +Additionally, the configuration or environment could be spread between two +additional sub-directories: + + * ``conf.d`` + * ``env.d`` (for environment customization) + +The dynamic inventory script does the following: + +* Generates the names of each container that runs a service +* Creates container and IP address mappings +* Assigns containers to physical hosts + +As an example, consider the following excerpt from +``openstack_user_config.yml``: + +.. code-block :: yaml + + identity_hosts: + infra01: + ip: 10.0.0.10 + infra02: + ip: 10.0.0.11 + infra03: + ip: 10.0.0.12 + +The ``identity_hosts`` dictionary defines an Ansible inventory group named +``identity_hosts`` containing the three infra hosts. The configuration file +``playbooks/inventory/env.d/keystone.yml`` defines additional Ansible +inventory groups for the containers that are deployed onto the three hosts +named with the prefix *infra*. + +Note that any services marked with ``is_metal: true`` will run on the allocated +physical host and not in a container. For an example of ``is_metal: true`` +being used refer to ``playbooks/inventory/env.d/cinder.yml`` in the +``container_skel`` section. + +Outputs +^^^^^^^ + +Once executed, the script will output an ``openstack_inventory.json`` file into +the directory specified with the ``--config`` argument. This is used as the +source of truth for repeated runs. + +.. note:: + The ``openstack_inventory.json`` file is the source of truth for the + environment. Deleting this in a production environment means that the UUID + portion of container names will be regenerated, which then results in new + containers being created. Containers generated under the previous version + will no longer be recognized by Ansible, even if reachable via SSH. + +The same JSON structure is printed to stdout, which is consumed by Ansible as +the inventory for the playbooks. diff --git a/doc/source/inventory/manage-inventory.rst b/doc/source/inventory/manage-inventory.rst new file mode 100644 index 0000000000..463db518d9 --- /dev/null +++ b/doc/source/inventory/manage-inventory.rst @@ -0,0 +1,62 @@ +===================================== +Inspecting and managing the inventory +===================================== + +The file ``scripts/inventory-manage.py`` is used to produce human readable +output based on the ``/etc/openstack_deploy/openstack_inventory.json`` file. + +The same script can be used to safely remove hosts from the inventory, export +the inventory based on hosts, and clear IP addresses from containers within +the inventory files. + +Operations taken by this script only affect the +``/etc/opentstack_deploy/openstack_inventory.json`` file; any new or removed +information must be set by running playbooks. + +Viewing the inventory +~~~~~~~~~~~~~~~~~~~~~ + +The ``/etc/openstack_deploy/openstack_inventory.json`` file is read by default. +An alternative file can be specified with ``--file``. + +A list of all hosts can be seen with the ``--list-host/-l`` argument + +To see a listing of hosts and containers by their group, use +``--list-groups/-g``. + +To see all of the containers, use ``--list-containers/-G``. + +Removing a host +~~~~~~~~~~~~~~~ + +A host can be removed with the ``--remove-item/-r`` parameter. + +Use the host's name as an argument. + +.. _`dynamic inventory functionality`: http://docs.ansible.com/ansible/intro_dynamic_inventory.html + +Exporting host information +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Information on a per-host basis can be obtained with the ``--export/-e`` +parameter. + +This JSON output has two top-level keys: ``hosts`` and ``all``. + +``hosts`` contains a map of a host's name to its variable and group data. + +``all`` contains global network information such as the load balancer IPs and +provider network metadata. + +Clearing existing container IP addresses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``--clear-ips`` parameter can be used to remove all container IP address +information from the ``openstack_inventory.json`` file. Baremetal hosts will +not be changed. + +This will *not* change the LXC configuration until the associated playbooks +are run and the containers restarted, which will result in API downtime. + +Any changes to the containers must also be reflected in the deployment's load +balancer.