diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 2b73ab6ebf..0000000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,102 +0,0 @@ -OpenStack Ansible Deployment -############################ -:tags: openstack, cloud, ansible -:category: \*nix - -contributor guidelines -^^^^^^^^^^^^^^^^^^^^^^ - -Bugs ----- - -Bugs should be filed on Launchpad at "https://bugs.launchpad.net/openstack-ansible". - -When submitting a bug, or working on a bug, please ensure the following criteria are met: - * The description clearly states or describes the original problem or root cause of the problem. - * Include historical information on how the problem was identified. - * Any relevant logs are included. - * If the issue is a bug that needs fixing in a branch other than master, please note the associated branch within the launchpad issue. - * The provided information should be totally self-contained. External access to web services/sites should not be needed. - * Steps to reproduce the problem if possible. - -Tags: - If it's a bug that needs fixing in a branch in addition to master, add a '\-backport-potential' tag (e.g. ``juno-backport-potential``). There are predefined tags that will auto-complete. - -Status: - Please leave the **status** of an issue alone until someone confirms it or a member of the bugs team triages it. While waiting for the issue to be confirmed or triaged the status should remain as **New**. - -Importance: - Should only be touched if it is a Blocker/Gating issue. If it is, please set to **High**, and only use **Critical** if you have found a bug that can take down whole infrastructures. Once the importance has been changed the status should be changed to *Triaged* by someone other than the bug creator. - -Triaging bugs: - Reported bugs need prioritization, confirmation, and shouldn't go stale. If you care about OpenStack stability but aren't wanting to actively develop the roles and playbooks used within the "openstack-ansible" project consider contributing in the area of bug triage, which helps immensely. The whole process is described in the upstream `Bug Triage Documentation`_. - - -Submitting Code ---------------- - -* Write good commit messages. We follow the OpenStack "`Git Commit Good Practice`_" guide. if you have any questions regarding how to write good commit messages please review the upstream OpenStack documentation. -* Changes to the project should be submitted for review via the Gerrit tool, following the `workflow documented here`_. -* Pull requests submitted through GitHub will be ignored and closed without regard. -* All feature additions/deletions should be accompanied by a blueprint/spec. IE: adding additional active agents to neutron, developing a new service role, etc... -* Before creating blueprint/spec an associated issue should be raised on launchpad. This issue will be triaged and a determination will be made on how large the change is and whether or not the change warrants a blueprint/spec. Both features and bug fixes may require the creation of a blueprint/spec. This requirement will be voted on by core reviewers and will be based on the size and impact of the change. -* All blueprints/specs should be voted on and approved by core reviewers before any associated code will be merged. For more information on blueprints/specs please review the `upstream OpenStack Blueprint documentation`_. At the time the blueprint/spec is voted on a determination will be made whether or not the work will be backported to any of the "released" branches. -* Patches should be focused on solving one problem at a time. If the review is overly complex or generally large the initial commit will receive a "**-2**" and the contributor will be asked to split the patch up across multiple reviews. In the case of complex feature additions the design and implementation of the feature should be done in such a way that it can be submitted in multiple patches using dependencies. Using dependent changes should always aim to result in a working build throughout the dependency chain. More information on `advanced gerrit usage and dependent changes can be found here`_. -* All patch sets should adhere to the Ansible Style Guide listed here as well as adhere to the Ansible best practices when possible. `Ansible best practices can be found here`_. -* All changes should be clearly listed in the commit message, with an associated bug id/blueprint along with any extra information where applicable. -* Refactoring work should never include additional "rider" features. Features that may pertain to something that was re-factored should be raised as an issue and submitted in prior or subsequent patches. - -Backporting ------------ -* Backporting is defined as the act of reproducing a change from another branch. Unclean/squashed/modified cherry-picks and complete reimplementations are OK. -* Backporting is often done by using the same code (via cherry picking), but this is not always the case. This method is preferred when the cherry-pick provides a complete solution for the targeted problem. -* When cherry-picking a commit from one branch to another the commit message should be amended with any files that may have been in conflict while performing the cherry-pick operation. Additionally, cherry-pick commit messages should contain the original commit *SHA* near the bottom of the new commit message. This can be done with ``cherry-pick -x``. Here's more information on `Submitting a change to a branch for review`_. -* Every backport commit must still only solve one problem, as per the guidelines in `Submitting Code`_. -* If a backport is a squashed set of cherry-picked commits, the original SHAs should be referenced in the commit message and the reason for squashing the commits should be clearly explained. -* When a cherry-pick is modified in any way, the changes made and the reasons for them must be explicitly expressed in the commit message. -* Refactoring work must not be backported to a "released" branch. - - -Style Guide ------------ - -When creating tasks and other roles for use in Ansible please create then using the YAML dictionary format. - -Example YAML dictionary format: - .. code-block:: yaml - - - name: The name of the tasks - module_name: - thing1: "some-stuff" - thing2: "some-other-stuff" - tags: - - some-tag - - some-other-tag - - -Example what **NOT** to do: - .. code-block:: yaml - - - name: The name of the tasks - module_name: thing1="some-stuff" thing2="some-other-stuff" - tags: some-tag - - .. code-block:: yaml - - - name: The name of the tasks - module_name: > - thing1="some-stuff" - thing2="some-other-stuff" - tags: some-tag - - -Usage of the ">" and "|" operators should be limited to Ansible conditionals and command modules such as the Ansible ``shell`` or ``command``. - - -.. _Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages -.. _workflow documented here: http://docs.openstack.org/infra/manual/developers.html#development-workflow -.. _upstream OpenStack Blueprint documentation: https://wiki.openstack.org/wiki/Blueprints -.. _advanced gerrit usage and dependent changes can be found here: http://www.mediawiki.org/wiki/Gerrit/Advanced_usage -.. _Ansible best practices can be found here: http://docs.ansible.com/playbooks_best_practices.html -.. _Submitting a change to a branch for review: http://www.mediawiki.org/wiki/Gerrit/Advanced_usage#Submitting_a_change_to_a_branch_for_review_.28.22backporting.22.29 -.. _Bug Triage Documentation: https://wiki.openstack.org/wiki/BugTriage diff --git a/README.rst b/README.rst index 964f2c4479..86c22855c6 100644 --- a/README.rst +++ b/README.rst @@ -1,65 +1,32 @@ -OpenStack Ansible Deployment -############################ -:date: 2015-02-02 22:00 -:tags: lxc, openstack, cloud, ansible -:category: \*nix +OpenStack Ansible +################# +OpenStack-Ansible is an `official OpenStack project`_ which aims to deploy +production environments from source in a way that makes it scalable while +also being simple to operate, upgrade, and grow. -Playbooks ---------- +For an overview of the mission, repositories and related Wiki home page, +please see the formal `Home Page`_ for the project. -There are several playbooks within that will setup hosts for use in OpenStack Cloud. The playbooks will enable LXC on hosts and provides the ability to deploy LXC containers for use within openstack. +For those looking to test OpenStack-Ansible using an All-In-One (AIO) build, +please see the `Quick Start`_ guide. -Plays: - * ``setup-hosts.yml`` Performs host setup for use with LXC in the OpenStack hosts. - * ``setup-infrastructure.yml`` Performs all of the setup for all infrastructure components. - * ``setup-openstack.yml`` Performs all of the setup for all of the OpenStack components. +For more detailed Installation and Operator documentation, please see the +`Install Guide`_. -* If you dont want to run plays individually you can simply run ``setup-everything.yml`` which will perform all of the setup and installation for you. +If OpenStack-Ansible is missing something you'd like to see included, then +we encourage you to see the `Developer Documentation` for more details on +how you can get involved. -Basic Setup: - 1. If you have any roles that you'd like to have pulled in that are outside the scope and or replace modules within this repository please add them to the ``ansible-role-requirements.yml`` file. In this file you will want to fill in the details for the role you want to pull in using standard ansible galaxy format. +If you have some questions, or would like some assistance with achieving your +goals, then please feel free to reach out to us on the +`OpenStack Mailing Lists`_ (particularly openstack-operators or openstack-dev) +or on IRC in ``#openstack-ansible`` on the `freenode network`_. - .. code-block:: yaml - - - name: SuperAwesomeModule - src: https://github.com/super-user/SuperAwesomeModule - version: master - - 2. Run the ``./scripts/bootstrap-ansible.sh`` script, which will install, pip, ansible 1.9.x, all of the required python packages, and bring in any third party ansible roles that you may want to add to the deployment. - 3. Copy the ``etc/openstack_deploy`` directory to ``/etc/openstack_deploy``. - 4. Fill in your ``openstack_deploy/openstack_user_config.yml``, ``openstack_deploy/user_secrets.yml`` and ``openstack_deploy/user_variables.yml`` files which you've just copied to your ``/etc/`` directory. - 5. Generate all of your random passwords executing ``scripts/pw-token-gen.py --file /etc/openstack_deploy/user_secrets.yml``. - 6. Accomplish all of the host networking that you want to use within the deployment. See the ``etc/network`` directory in this repository for an example network setup. - 7. When ready change to the ``playbooks/`` directory and execute your desired plays. IE: - - .. code-block:: bash - - openstack-ansible setup-everything.yml - - -Notes ------ - -* If you run the ``./scripts/bootstrap-ansible.sh`` script a wrapper script will be added to your system that wraps the ansible-playbook command to simplify the arguments required to run openstack ansible plays. The name of the wrapper script is **openstack-ansible**. -* The lxc network is created within the *lxcbr0* interface. This supports both NAT networks as well as more traditional networking. If NAT is enabled (default) the IPtables rules will be created along with the interface as a post-up processes. If you ever need to recreate the rules and or restart the dnsmask process you can bounce the interface IE: ``ifdown lxcb0; ifup lxcbr0`` or you can use the ``lxc-system-manage`` command. -* The tool ``lxc-system-manage`` is available on all lxc hosts and can assist in recreating parts of the LXC system whenever its needed. -* Inventory is generated by executing the ``playbooks/inventory/dynamic_inventory.py`` script. This is configured in the ``playbooks/ansible.cfg`` file. -* If you don't use the pw-token-gen.py script you will want to ensure the permissions on /etc/openstack_deploy/user_secrets.yml are more secure. ``chmod 0600 /etc/openstack_deploy/user_secrets.yml`` -* Finding slow Ansible tasks is easier with the ``profile_tasks`` callback plugin. Review the notes in ``playbooks/plugins/callbacks/profile_tasks.py`` to enable it. - - -Bugs and Blueprints -------------------- - -Everything we do is in launchpad and gerrit. If you'd like to raise a bug, feature request, or are looking for ways to contribute please go to "https://launchpad.net/openstack-ansible". - - -Documentation -------------- - -To build the docs make sure that you have installed the python requirements as found within the ``dev-requirements.txt`` file and then run the following command from within the ``doc`` directory. - -.. code-block:: bash - - make html +.. _official OpenStack project: http://governance.openstack.org/reference/projects/index.html +.. _Home Page: http://governance.openstack.org/reference/projects/openstackansible.html +.. _Install Guide: http://docs.openstack.org/developer/openstack-ansible/install-guide/index.html +.. _Quick Start: http://docs.openstack.org/developer/openstack-ansible/developer-docs/quickstart-aio.html +.. _Developer Documentation: http://docs.openstack.org/developer/openstack-ansible/developer-docs/index.html +.. _OpenStack Mailing Lists: http://lists.openstack.org/ +.. _freenode network: https://freenode.net/ diff --git a/development-stack.rst b/development-stack.rst deleted file mode 100644 index 74158b47fa..0000000000 --- a/development-stack.rst +++ /dev/null @@ -1,236 +0,0 @@ -OpenStack Ansible Deployment -############################ -:date: 2015-02-02 22:00 -:tags: lxc, openstack, cloud, ansible -:category: \*nix - - -Building a development stack ----------------------------- - -To deploy an *all-in-one* (AIO) environment for testing or contributing to -this project, use the scripts in the ``scripts`` directory. You must run these -scripts from the repository top-level directory. For example: - -.. code-block:: console - - $ git clone https://github.com/openstack/openstack-ansible \ - /opt/openstack-ansible - $ cd /opt/openstack-ansible - $ scripts/bootstrap-aio.sh - -Requirements -^^^^^^^^^^^^ - -* Quad-core processor capable of running KVM -* 8 GB of RAM -* 60 GB of storage - - .. note:: - - By default, the deployment scripts use the file system on "/" for - containers. Optionally, the deployment scripts can use LVM for - containers. To use LVM, create the ``lvm`` volume group. Each - container uses a logical volume that requires **5 GB** of available - storage in the volume group. - -If deploying on a Rackspace public cloud server, use the *general1-8* or -larger flavor. Optionally, you can use the Orchestration template -``osa-aio-heat-template.yml`` to launch a cloud server and deploy an AIO -environment on it. - -These requirements may seem excessive; however, the default AIO deployment -builds a roughly 35-node environment that closely matches the reference -architecture. For example, components such as RabbitMQ, MariaDB with Galera, -source repository, and Identity service all use multiple containers to -simulate clustering. - -Finally, the AIO deployment uses HAProxy for testing purposes only. Please -do not use this HAProxy configuration for production purposes because it -does not provide any redundancy. - -.. note:: - - Never deploy an AIO environment on a host that you cannot risk breaking - or destroying. - -Procedure -^^^^^^^^^ - -To deploy an AIO environment, complete these steps: - -#. Clone the repository: - - .. code-block:: console - - $ git clone https://github.com/openstack/openstack-ansible \ - /opt/openstack-ansible - -#. Change to the repository top-level directory: - - .. code-block:: console - - $ cd /opt/openstack-ansible - -#. By default, the repository uses the *master* branch. Optionally, you can - check out a different branch. For example, to check out the Kilo branch: - - .. code-block:: console - - $ git checkout kilo - -#. By default, the scripts deploy all OpenStack services. Optionally, you can - disable one or more services using environment variables. See the - ``DEPLOY_*`` variables in the ``run-playbooks.sh`` script for details. For - example, to disable the Telemetry service: - - .. code-block:: console - - $ export DEPLOY_CEILOMETER="no" - - .. note:: - - The scripts still build containers for any service that you disable, but - do not deploy the service. - -#. Prepare the host: - - .. code-block:: console - - $ scripts/bootstrap-aio.sh - - .. note:: - - This script configures the host operating system and supplies values for - mandatory options in configuration files in the - ``/etc/openstack_deploy`` directory. - -#. Install the necessary Ansible components: - - .. code-block:: console - - $ scripts/bootstrap-ansible.sh - - .. note:: - - Only run this script once. - -#. Run the Ansible playbooks to deploy the environment: - - .. code-block:: console - - $ scripts/run-playbooks.sh - - .. note:: - - You can run this script multiple times. - - Optionally, you can run individual playbooks. For example, to deploy the - Identity service: - - .. code-block:: console - - $ cd /opt/openstack-ansible/playbooks - $ openstack-ansible os-keystone-install.yml - -Rebuilding the stack -^^^^^^^^^^^^^^^^^^^^ - -Once you have completed your testing and or dev work if you'd like to tear down the stack and restart from a new build there is a play that will assist you in doing just that. Simply change to your playbooks directory and execute the ``lxc-containers-destroy.yml`` play. - -Example: - -.. code-block:: bash - - # Move to the playbooks directory. - cd /opt/openstack-ansible/playbooks - - # Destroy all of the running containers. - openstack-ansible lxc-containers-destroy.yml - - # On the host stop all of the services that run locally and not within a container. - for i in $(ls /etc/init | grep -e nova -e swift -e neutron | awk -F'.' '{print $1}'); do service $i stop; done - - # Uninstall the core services that were installed. - for i in $(pip freeze | grep -e nova -e neutron -e keystone -e swift); do pip uninstall -y $i; done - - # Remove crusty directories. - rm -rf /openstack /etc/neutron /etc/nova /etc/swift /var/log/neutron /var/log/nova /var/log/swift - - -Using the teardown script: - The ``teardown.sh`` script that will destroy everything known within an environment. You should be aware that this script will destroy whole environments and should be used **WITH CAUTION**. - -This script will destroy all of your running containers and remove items within the ``/openstack`` directory for the container. After the completion of this play you can rerun the ``run-playbooks.sh`` or you can run the plays manually to rebuild the stack. - -Notice -^^^^^^ - -The system uses a number of variables. You should look a the scripts for a full explanation and description of all of the available variables that you can set. At a minimum you should be aware of the default public interface variable as you may be kicking on a box that does not have an ``eth0`` interface. To set the default public interface run the following. - -.. code-block:: bash - - export PUBLIC_INTERFACE="<>" # This is only required if you dont have eth0 - - -Diagram of stack -^^^^^^^^^^^^^^^^ - -Here is a basic diagram that attempts to illustrate what the AIO installation job is doing. **NOTICE** This diagram is not to scale and is not even 100% accurate, this diagram was built for informational purposes only and should **ONLY** be used as such. - - -Diagram:: - - ====== ASCII Diagram for AIO infrastructure ====== - - ------->[ ETH0 == Public Network ] - | - V [ * ] Socket Connections - [ HOST MACHINE ] [ <>v^ ] Network Connections - * ^ * - | | |------------------------------------------------------- - | | | - | |---------------->[ HAProxy ] | - | ^ | - | | | - | V | - | (BR-Interfaces)<------- | - | ^ * | | - *-[ LXC ]*--*----------------------|-----|------|----| | - | | | | | | | | - | | | | | | | | - | | | | | | | | - | | | | V * | | - | * | | [ Galera x3 ] | - | [ Memcached ]<------------| | | | - *-------*[ Rsyslog ]<--------------|--| | * | - | [ Repos Server x3 ]<------| ---|-->[ RabbitMQ x3 ] | - | [ Horizon x2 ]<-----------| | | | - | [ Nova api ec2 ]<---------|--| | | - | [ Nova api os ]<----------|->| | | - | [ Nova console ]<---------| | | | - | [ Nova Cert ]<------------|->| | | - | [ Ceilometer api ]<-------|->| | | - | [ Ceilometer collector ]<-|->| | | - | [ Cinder api ]<-----------|->| | | - | [ Glance api ]<-----------|->| | | - | [ Heat apis ]<------------|->| | [ Loop back devices ]*-* - | [ Heat engine ]<----------|->| | \ \ | - | ------>[ Nova api metadata ] | | | { LVM } { XFS x3 } | - | | [ Nova conductor ]<-------| | | * * | - | |----->[ Nova scheduler ]--------|->| | | | | - | | [ Keystone x3 ]<----------|->| | | | | - | | |--->[ Neutron agents ]*-------|--|---------------------------* - | | | [ Neutron server ]<-------|->| | | | - | | | |->[ Swift proxy ]<----------- | | | | - *-|-|-|-*[ Cinder volume ]*----------------------* | | - | | | | | | | - | | | ----------------------------------------- | | - | | ----------------------------------------- | | | - | | -------------------------| | | | | - | | | | | | | - | | V | | * | - ---->[ Compute ]*[ Neutron linuxbridge ]<---| |->[ Swift storage ]- - - - ====== ASCII Diagram for AIO infrastructure ====== diff --git a/doc/source/developer-docs/contribute.rst b/doc/source/developer-docs/contribute.rst new file mode 100644 index 0000000000..a1dfc96bde --- /dev/null +++ b/doc/source/developer-docs/contribute.rst @@ -0,0 +1,171 @@ +`Home `_ OpenStack-Ansible Developer Documentation + +Contributor Guidelines +====================== + +Bugs +---- + +Bugs should be filed on `Bug Launchpad`_ for OpenStack-Ansible. + +When submitting a bug, or working on a bug, please ensure the following +criteria are met: + +* The description clearly states or describes the original problem or root + cause of the problem. +* Include historical information on how the problem was identified. +* Any relevant logs are included. +* If the issue is a bug that needs fixing in a branch other than master, + please note the associated branch within the launchpad issue. +* The provided information should be totally self-contained. External access + to web services/sites should not be needed. +* Steps to reproduce the problem if possible. + +Tags +```` +If it's a bug that needs fixing in a branch in addition to master, add a +'\-backport-potential' tag (e.g. ``kilo-backport-potential``). +There are predefined tags that will auto-complete. + +Status +`````` +Please leave the **status** of an issue alone until someone confirms it or +a member of the bugs team triages it. While waiting for the issue to be +confirmed or triaged the status should remain as **New**. + +Importance +`````````` +Should only be touched if it is a Blocker/Gating issue. If it is, please +set to **High**, and only use **Critical** if you have found a bug that +can take down whole infrastructures. Once the importance has been changed +the status should be changed to *Triaged* by someone other than the bug +creator. + +Triaging bugs +````````````` +Reported bugs need prioritization, confirmation, and shouldn't go stale. +If you care about OpenStack stability but aren't wanting to actively +develop the roles and playbooks used within the "openstack-ansible" +project consider contributing in the area of bug triage, which helps +immensely. The whole process is described in the upstream +`Bug Triage Documentation`_. + +.. _Bug Launchpad: https://bugs.launchpad.net/openstack-ansible +.. _Bug Triage Documentation: https://wiki.openstack.org/wiki/BugTriage + +Submitting Code +--------------- + +* Write good commit messages. We follow the OpenStack + "`Git Commit Good Practice`_" guide. if you have any questions regarding how + to write good commit messages please review the upstream OpenStack + documentation. +* Changes to the project should be submitted for review via the Gerrit tool, + following the `workflow documented here`_. +* Pull requests submitted through GitHub will be ignored and closed without + regard. +* All feature additions/deletions should be accompanied by a blueprint/spec. + ie: adding additional active agents to neutron, developing a new service + role, etc... +* Before creating blueprint/spec an associated issue should be raised on + launchpad. This issue will be triaged and a determination will be made on + how large the change is and whether or not the change warrants a + blueprint/spec. Both features and bug fixes may require the creation of a + blueprint/spec. This requirement will be voted on by core reviewers and will + be based on the size and impact of the change. +* All blueprints/specs should be voted on and approved by core reviewers + before any associated code will be merged. For more information on + blueprints/specs please review the + `upstream OpenStack Blueprint documentation`_. At the time the + blueprint/spec is voted on a determination will be made whether or not the + work will be backported to any of the "released" branches. +* Patches should be focused on solving one problem at a time. If the review is + overly complex or generally large the initial commit will receive a "**-2**" + and the contributor will be asked to split the patch up across multiple + reviews. In the case of complex feature additions the design and + implementation of the feature should be done in such a way that it can be + submitted in multiple patches using dependencies. Using dependent changes + should always aim to result in a working build throughout the dependency + chain. Documentation is available for `advanced gerrit usage`_ too. +* All patch sets should adhere to the Ansible Style Guide listed here as well + as adhere to the `Ansible best practices`_ when possible. +* All changes should be clearly listed in the commit message, with an + associated bug id/blueprint along with any extra information where + applicable. +* Refactoring work should never include additional "rider" features. Features + that may pertain to something that was re-factored should be raised as an + issue and submitted in prior or subsequent patches. + +.. _Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages +.. _workflow documented here: http://docs.openstack.org/infra/manual/developers.html#development-workflow +.. _upstream OpenStack Blueprint documentation: https://wiki.openstack.org/wiki/Blueprints +.. _advanced gerrit usage: http://www.mediawiki.org/wiki/Gerrit/Advanced_usage +.. _Ansible best practices: http://docs.ansible.com/playbooks_best_practices.html + +Backporting +----------- +* Backporting is defined as the act of reproducing a change from another + branch. Unclean/squashed/modified cherry-picks and complete + reimplementations are OK. +* Backporting is often done by using the same code (via cherry picking), but + this is not always the case. This method is preferred when the cherry-pick + provides a complete solution for the targeted problem. +* When cherry-picking a commit from one branch to another the commit message + should be amended with any files that may have been in conflict while + performing the cherry-pick operation. Additionally, cherry-pick commit + messages should contain the original commit *SHA* near the bottom of the new + commit message. This can be done with ``cherry-pick -x``. Here's more + information on `Submitting a change to a branch for review`_. +* Every backport commit must still only solve one problem, as per the + guidelines in `Submitting Code`_. +* If a backport is a squashed set of cherry-picked commits, the original SHAs + should be referenced in the commit message and the reason for squashing the + commits should be clearly explained. +* When a cherry-pick is modified in any way, the changes made and the reasons + for them must be explicitly expressed in the commit message. +* Refactoring work must not be backported to a "released" branch. + +.. _Submitting a change to a branch for review: http://www.mediawiki.org/wiki/Gerrit/Advanced_usage#Submitting_a_change_to_a_branch_for_review_.28.22backporting.22.29 + +Style Guide +----------- + +When creating tasks and other roles for use in Ansible please create then +using the YAML dictionary format. + +Example YAML dictionary format: + + .. code-block:: yaml + + - name: The name of the tasks + module_name: + thing1: "some-stuff" + thing2: "some-other-stuff" + tags: + - some-tag + - some-other-tag + + +Example what **NOT** to do: + + .. code-block:: yaml + + - name: The name of the tasks + module_name: thing1="some-stuff" thing2="some-other-stuff" + tags: some-tag + + .. code-block:: yaml + + - name: The name of the tasks + module_name: > + thing1="some-stuff" + thing2="some-other-stuff" + tags: some-tag + + +Usage of the ">" and "|" operators should be limited to Ansible conditionals +and command modules such as the Ansible ``shell`` or ``command``. + +-------------- + +.. include:: navigation.txt diff --git a/doc/source/developer-docs/extending.rst b/doc/source/developer-docs/extending.rst index 5bf2cfc7c2..78b0b058ab 100644 --- a/doc/source/developer-docs/extending.rst +++ b/doc/source/developer-docs/extending.rst @@ -1,7 +1,9 @@ -Extending openstack-ansible +`Home `_ OpenStack-Ansible Developer Documentation + +Extending OpenStack-Ansible =========================== -The openstack-ansible project provides a basic OpenStack environment, but +The OpenStack-Ansible project provides a basic OpenStack environment, but many deployers will wish to extend the environment based on their needs. This could include installing extra services, changing package versions, or overriding existing variables. @@ -254,3 +256,6 @@ The list of overrides available may be found by executing: | grep -v "^#" \ | sort -u +-------------- + +.. include:: navigation.txt diff --git a/doc/source/developer-docs/index.rst b/doc/source/developer-docs/index.rst index 1741e64ed9..c369f9b805 100644 --- a/doc/source/developer-docs/index.rst +++ b/doc/source/developer-docs/index.rst @@ -9,10 +9,11 @@ Contents: .. toctree:: :maxdepth: 2 + quickstart-aio + scripts playbooks extending - scripts - quickstart-aio + contribute Indices and tables diff --git a/doc/source/developer-docs/navigation.txt b/doc/source/developer-docs/navigation.txt new file mode 100644 index 0000000000..6e0cf79698 --- /dev/null +++ b/doc/source/developer-docs/navigation.txt @@ -0,0 +1,3 @@ +* `Documentation Home <../index.html>`_ +* `Installation Guide <../install-guide/index.html>`_ +* `Developer Documentation `_ diff --git a/doc/source/developer-docs/playbooks.rst b/doc/source/developer-docs/playbooks.rst index eb6a09d8cf..85ba1528aa 100644 --- a/doc/source/developer-docs/playbooks.rst +++ b/doc/source/developer-docs/playbooks.rst @@ -1,7 +1,9 @@ +`Home `_ OpenStack-Ansible Developer Documentation + Playbooks ========= -The OpenStack Ansible playbooks are stored in the playbooks directory. +The OpenStack-Ansible playbooks are stored in the playbooks directory. There are several top-level playbooks that are run to prepare the host machines before actually deploying OpenStack and associated containers. @@ -46,3 +48,7 @@ OpenStack services: * Neutron * Heat * Horizon + +-------------- + +.. include:: navigation.txt diff --git a/doc/source/developer-docs/quickstart-aio.rst b/doc/source/developer-docs/quickstart-aio.rst index cdb1eb04d3..5f6fe3c5e4 100644 --- a/doc/source/developer-docs/quickstart-aio.rst +++ b/doc/source/developer-docs/quickstart-aio.rst @@ -1,7 +1,9 @@ +`Home `_ OpenStack-Ansible Developer Documentation + Quick Start =========== -All-in-one (AIO) builds are a great way to perform an OpenStack Ansible build +All-in-one (AIO) builds are a great way to perform an OpenStack-Ansible build for: * a development environment @@ -45,11 +47,12 @@ Running a customized AIO build There are four main steps for running a customized AIO build: * Configuration *(this step is optional)* -* Initial bootstrap +* Initial host bootstrap * Install and bootstrap Ansible * Run playbooks -Start by cloning the openstack-ansible repository: +Start by cloning the openstack-ansible repository and changing into the +repository root directory: .. code-block:: bash @@ -57,21 +60,54 @@ Start by cloning the openstack-ansible repository: /opt/openstack-ansible $ cd /opt/openstack-ansible -At this point, you can adjust which services are deployed within your AIO -build. Look at the top of ``scripts/bootstrap-aio.sh`` for several examples. -If you'd like to skip the deployment of ceilometer, you could run the -following: +Next switch the the applicable branch/tag you wish to deploy from. Note that +deploying from the head of a branch may result in an unstable build due to +changes in flight and upstream OpenStack changes. For a test (ie not a +development) build it is usually best to checkout the latest tagged version. + + .. code-block:: bash + + $ git checkout kilo + +By default the scripts deploy all OpenStack services. At this point you may +optionally adjust which services are deployed within your AIO build. Look at +the ``DEPLOY_`` environment variables at the top of +``scripts/run-playbooks.sh`` for more details. For example, if you'd like to +skip the deployment of ceilometer, you would execute the following: .. code-block:: bash $ export DEPLOY_CEILOMETER="no" -Now you're ready to complete the bootstraps and run the playbooks: +Note that the scripts still build containers for any service that you disable, +but do not deploy the service. + +In order for all the services to run, the host must be prepared with the +appropriate disks, packages, network configuration and a base configuration +for the OpenStack Deployment. This preparation is completed by executing: .. code-block:: bash $ scripts/bootstrap-aio.sh + +If you wish to add any additional configuration entries for the OpenStack +configuration then this can be done now by editing +``/etc/openstack_deploy/user_variables.yml``. Please see the `Install Guide`_ +for more details. + +Note that the host bootstrap is not idempotent and should only be executed +once. + +Once you're ready to deploy, bootstrap Ansible by executing: + + .. code-block:: bash + $ scripts/bootstrap-ansible.sh + +Finally, run the playbooks by executing: + + .. code-block:: bash + $ scripts/run-playbooks.sh The installation process will take a while to complete, but here are some @@ -81,6 +117,80 @@ general estimates: * Virtual machines with SSD storage: ~ 45-60 minutes * Systems with traditional hard disks: ~ 90-120 minutes +Once the playbooks have fully executed, you may experiment with various +settings changes in ``/etc/openstack_deploy/user_variable.yml`` and only +run individual playbooks. For example, to run the playbook for the +Keystone service, execute: + + .. code-block:: bash + + $ cd /opt/openstack-ansible/playbooks + $ openstack-ansible os-keystone-install.yml + +.. _Install Guide: ../install-guide/ + +Rebuilding the AIO +------------------ +Sometimes it may be useful to destroy all the containers and rebuild the AIO. +While it is preferred that the AIO is entirely destroyed and rebuilt, this +isn't always practical. As such the following may be executed instead: + + .. code-block:: bash + + $ # Move to the playbooks directory. + $ cd /opt/openstack-ansible/playbooks + + $ # Destroy all of the running containers. + $ openstack-ansible lxc-containers-destroy.yml + + $ # On the host stop all of the services that run locally and not + $ # within a container. + $ for i in \ + $(ls /etc/init \ + | grep -e "nova\|swift\|neutron" \ + | awk -F'.' '{print $1}'); do \ + service $i stop; \ + done + + $ # Uninstall the core services that were installed. + $ for i in $(pip freeze | grep -e "nova\|neutron\|keystone\|swift); do \ + pip uninstall -y $i; done + + $ # Remove crusty directories. + $ rm -rf /openstack /etc/{neutron,nova,swift} \ + /var/log/{neutron,nova,swift} + +There is a convenience script (``scripts/teardown.sh``) which will destroy +everything known within an environment. You should be aware that this script +will destroy whole environments and should be used WITH CAUTION. + +After the teardown is complete, ``run-playbooks.sh`` may be executed again to +rebuild the AIO. + +AIO Host Bootstrap Customisation +-------------------------------- +The AIO makes a number of assumptions about the system it is being deployed +on. Many of these assumptions may be changed through the use of environment +variables which can be changed prior to the AIO host bootstrap. + +As these options change on a regular basis it is best to examine each of the +scripts used to find the environment variables which can be overridden: + + * ``scripts/bootstrap-aio.sh`` (this sets the AIO host up) + * ``scripts/bootstrap-ansible.sh`` (this sets Ansible up) + * ``scripts/scripts-library.sh`` (this is used by all the other scripts) + +As an example, if you wish the Keystone Admin password to be a value which +you set (rather than the default of a random string), then execute: + +.. code-block:: bash + + export ADMIN_PASSWORD="secrete" + +More details about the scripts used can be found in the `scripts page`_. + +.. _scripts page: scripts.html + Quick AIO build on Rackspace Cloud ---------------------------------- @@ -101,11 +211,12 @@ soon as the instance starts. Save this file as ``user_data.yml``: - export ANSIBLE_FORCE_COLOR=true - export PYTHONUNBUFFERED=1 - export REPO=https://github.com/openstack/openstack-ansible - - git clone ${REPO} /opt/os-ansible + - export BRANCH=kilo + - git clone -b ${BRANCH} ${REPO} /opt/openstack-ansible - export DEPLOY_CEILOMETER="no" - - cd /opt/os-ansible && scripts/bootstrap-aio.sh - - cd /opt/os-ansible && scripts/bootstrap-ansible.sh - - cd /opt/os-ansible && scripts/run-playbooks.sh + - cd /opt/openstack-ansible && scripts/bootstrap-aio.sh + - cd /opt/openstack-ansible && scripts/bootstrap-ansible.sh + - cd /opt/openstack-ansible && scripts/run-playbooks.sh output: { all: '| tee -a /var/log/cloud-init-output.log' } Feel free to customize the YAML file to meet your requirements. As an example @@ -127,10 +238,74 @@ We can pass this YAML file to nova and build a Cloud Server at Rackspace: Be sure to replace ``public_key_name`` with the name of the public key that you prefer to use with your instance. Within a minute or so, your instance -should be running and the OpenStack Ansible installation will be in progress. +should be running and the OpenStack-Ansible installation will be in progress. -To follow along with the progress, ssh to your running instance and run: +To follow along with the progress, ssh to your running instance and execute: .. code-block:: bash tail -F /var/log/cloud-init-output.log + +Reference Diagram for the AIO Build +----------------------------------- + +Here is a basic diagram that attempts to illustrate what the resulting AIO +deployment looks like. + +This diagram is not to scale and is not even 100% accurate, this diagram was +built for informational purposes only and should **ONLY** be used as such. + +.. code-block:: text + + ------->[ ETH0 == Public Network ] + | + V [ * ] Socket Connections + [ HOST MACHINE ] [ <>v^ ] Network Connections + * ^ * + | | |------------------------------------------------------- + | | | + | |---------------->[ HAProxy ] | + | ^ | + | | | + | V | + | (BR-Interfaces)<------- | + | ^ * | | + *-[ LXC ]*--*----------------------|-----|------|----| | + | | | | | | | | + | | | | | | | | + | | | | | | | | + | | | | V * | | + | * | | [ Galera x3 ] | + | [ Memcached ]<------------| | | | + *-------*[ Rsyslog ]<--------------|--| | * | + | [ Repos Server x3 ]<------| ---|-->[ RabbitMQ x3 ] | + | [ Horizon x2 ]<-----------| | | | + | [ Nova api ec2 ]<---------|--| | | + | [ Nova api os ]<----------|->| | | + | [ Nova console ]<---------| | | | + | [ Nova Cert ]<------------|->| | | + | [ Ceilometer api ]<-------|->| | | + | [ Ceilometer collector ]<-|->| | | + | [ Cinder api ]<-----------|->| | | + | [ Glance api ]<-----------|->| | | + | [ Heat apis ]<------------|->| | [ Loop back devices ]*-* + | [ Heat engine ]<----------|->| | \ \ | + | ------>[ Nova api metadata ] | | | { LVM } { XFS x3 } | + | | [ Nova conductor ]<-------| | | * * | + | |----->[ Nova scheduler ]--------|->| | | | | + | | [ Keystone x3 ]<----------|->| | | | | + | | |--->[ Neutron agents ]*-------|--|---------------------------* + | | | [ Neutron server ]<-------|->| | | | + | | | |->[ Swift proxy ]<----------- | | | | + *-|-|-|-*[ Cinder volume ]*----------------------* | | + | | | | | | | + | | | ----------------------------------------- | | + | | ----------------------------------------- | | | + | | -------------------------| | | | | + | | | | | | | + | | V | | * | + ---->[ Compute ]*[ Neutron linuxbridge ]<---| |->[ Swift storage ]- + +-------------- + +.. include:: navigation.txt diff --git a/doc/source/developer-docs/scripts.rst b/doc/source/developer-docs/scripts.rst index adf8e77fed..2d4f7424cd 100644 --- a/doc/source/developer-docs/scripts.rst +++ b/doc/source/developer-docs/scripts.rst @@ -1,10 +1,11 @@ +`Home `_ OpenStack-Ansible Developer Documentation + Included Scripts ================ The repository contains several helper scripts to manage gate jobs, -install base requirements, and update repository information. Invoke -these scripts from the top-level directory of the repository. For -example: +install base requirements, and update repository information. Execute +these scripts from the root of the respository clone. For example: .. code:: bash @@ -37,6 +38,39 @@ The script also creates the ``openstack-ansible`` wrapper tool that provides the variable files to match ``/etc/openstack_deploy/user_*.yml`` as arguments to ``ansible-playbook`` as a convenience. +Development and Testing +^^^^^^^^^^^^^^^^^^^^^^^ + +run-playbooks.sh +---------------- + +The ``run-playbooks`` script is designed to be executed in development and +test environments and is also used for automated testing. It executes actions +which are definitely **not** suitable for production environments and must +therefore **not** be used for that purpose. + +In order to scope the playbook execution there are several ``DEPLOY_`` +environment variables available near the top of the script. These are used +by simply exporting an override before executing the script. For example, +to skip the execution of the Ceilometer playbook, execute: + +.. code-block:: bash + + export DEPLOY_CEILOMETER='no' + +run-tempest.sh +-------------- + +The ``run-tempest.sh`` script runs Tempest tests from the first utility +container. This is primarily used for automated gate testing, but may also be +used through manual execution. + +Configurable environment variables: + +* ``TEMPEST_SCRIPT_PARAMETERS`` - Defines tests to run. Values are passed to + ``openstack_tempest_gate.sh`` script, defined in the ``os_tempest`` role. + Defaults to ``scenario heat_api cinder_backup``. + Gating ^^^^^^ @@ -52,7 +86,7 @@ Configurable environment variables: * ``BOOTSTRAP_AIO`` - Boolean (yes/no) to run AIO bootstrap script. Defaults to ``yes``. -* ``BOOTSTRAP_AIO`` - Boolean (yes/no) to run Ansible bootstrip script. +* ``BOOTSTRAP_ANSIBLE`` - Boolean (yes/no) to run Ansible bootstrip script. Defaults to ``yes``. * ``RUN_TEMPEST`` - Boolean (yes/no) to run Tempest tests. Defaults to ``yes``. @@ -78,15 +112,6 @@ the following rules due to Ansible conventions: Ansible playbooks pass through ``ansible-playbook --syntax-check`` and ``ansible-lint``. -run-tempest.sh -------------- -The ``run-tempest.sh`` script runs Tempest tests from the first utility -container. The ``check-gate-commit.sh`` script usually invokes this -script after it completes the OSA deployment. - -Configurable environment variables: - -* ``TEMPEST_SCRIPT_PARAMETERS`` - Defines tests to run. Values are passed to - ``openstack_tempest_gate.sh`` script, defined in the ``os_tempest`` role. - Defaults to ``scenario heat_api cinder_backup``. +.. include:: navigation.txt diff --git a/doc/source/index.rst b/doc/source/index.rst index 875e62e742..4d37abad87 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,7 +3,7 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to openstack-ansible's documentation! +Welcome to OpenStack-Ansible's documentation! ================================================= diff --git a/doc/source/install-guide/app-configfiles.rst b/doc/source/install-guide/app-configfiles.rst index a4b8225c22..bf69963abf 100644 --- a/doc/source/install-guide/app-configfiles.rst +++ b/doc/source/install-guide/app-configfiles.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Appendix A. Configuration files ------------------------------- diff --git a/doc/source/install-guide/app-resources.rst b/doc/source/install-guide/app-resources.rst index 126d9c57eb..4309ba7171 100644 --- a/doc/source/install-guide/app-resources.rst +++ b/doc/source/install-guide/app-resources.rst @@ -1,38 +1,31 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide -Appendix B. Additional resources +Appendix B. Additional Resources -------------------------------- -These additional resources. +The following Ansible resources are useful to reference: -- `OpenStack Documentation `__ +- `Ansible Documentation + `_ -- `OpenStack Developer - Documentation `__ +- `Ansible Best Practices + `_ -- `OpenStack API Quick - Start `__ +- `Ansible Configuration + `_ -- `OpenStack Block Storage (cinder) Developer - Documentation `__ +The following OpenStack resources are useful to reference: -- `OpenStack Compute (nova) Developer - Documentation `__ +- `OpenStack Documentation `_ -- `OpenStack Compute API v2 Developer - Guide `__ +- `OpenStack SDK, CLI and API Documentation + `_ -- `OpenStack Dashboard (horizon) Developer - Documentation `__ +- `OpenStack API Quick Start + `_ -- `OpenStack Identity (keystone) Developer - Documentation `__ - -- `OpenStack Image service (glance) Developer - Documentation `__ - -- `OpenStack Object Storage (swift) Developer - Documentation `__ +- `OpenStack Project Developer Documentation + `_ -------------- diff --git a/doc/source/install-guide/configure-ceilometer.rst b/doc/source/install-guide/configure-ceilometer.rst index e55666bd7a..f832d92158 100644 --- a/doc/source/install-guide/configure-ceilometer.rst +++ b/doc/source/install-guide/configure-ceilometer.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring the Ceilometer service (optional) --------------------------------------------- diff --git a/doc/source/install-guide/configure-cinder-az.rst b/doc/source/install-guide/configure-cinder-az.rst index 3f1a3684aa..c8769622f7 100644 --- a/doc/source/install-guide/configure-cinder-az.rst +++ b/doc/source/install-guide/configure-cinder-az.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Availability zones ------------------ diff --git a/doc/source/install-guide/configure-cinder-backup.rst b/doc/source/install-guide/configure-cinder-backup.rst index fe629bd109..98be9c8aa7 100644 --- a/doc/source/install-guide/configure-cinder-backup.rst +++ b/doc/source/install-guide/configure-cinder-backup.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Backup ------ diff --git a/doc/source/install-guide/configure-cinder-nfs.rst b/doc/source/install-guide/configure-cinder-nfs.rst index 78c5e5905e..b2999ecfda 100644 --- a/doc/source/install-guide/configure-cinder-nfs.rst +++ b/doc/source/install-guide/configure-cinder-nfs.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide NFS back-end ------------ diff --git a/doc/source/install-guide/configure-cinder.rst b/doc/source/install-guide/configure-cinder.rst index def6a44ddd..77224735b8 100644 --- a/doc/source/install-guide/configure-cinder.rst +++ b/doc/source/install-guide/configure-cinder.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring the Block Storage service (optional) ------------------------------------------------ diff --git a/doc/source/install-guide/configure-creds.rst b/doc/source/install-guide/configure-creds.rst index a511888ac6..90a38592fc 100644 --- a/doc/source/install-guide/configure-creds.rst +++ b/doc/source/install-guide/configure-creds.rst @@ -1,11 +1,11 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring service credentials ------------------------------- Configure credentials for each service in the ``/etc/openstack_deploy/*_secrets.yml`` files. Consider using `Ansible -Vault `__ to increase +Vault `_ to increase security by encrypting any files containing credentials. Adjust permissions on these files to restrict access by non-privileged diff --git a/doc/source/install-guide/configure-glance.rst b/doc/source/install-guide/configure-glance.rst index 6aeb15627f..f1e2de196c 100644 --- a/doc/source/install-guide/configure-glance.rst +++ b/doc/source/install-guide/configure-glance.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring the Image service ----------------------------- diff --git a/doc/source/install-guide/configure-haproxy.rst b/doc/source/install-guide/configure-haproxy.rst index c12bd52fe3..190fe2eba4 100644 --- a/doc/source/install-guide/configure-haproxy.rst +++ b/doc/source/install-guide/configure-haproxy.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring HAProxy (optional) ------------------------------ diff --git a/doc/source/install-guide/configure-horizon.rst b/doc/source/install-guide/configure-horizon.rst index 886f439b9d..3146756da0 100644 --- a/doc/source/install-guide/configure-horizon.rst +++ b/doc/source/install-guide/configure-horizon.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring Horizon (optional) ------------------------------ diff --git a/doc/source/install-guide/configure-hostlist.rst b/doc/source/install-guide/configure-hostlist.rst index 7bc95fd48c..461018866a 100644 --- a/doc/source/install-guide/configure-hostlist.rst +++ b/doc/source/install-guide/configure-hostlist.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring target hosts ------------------------ diff --git a/doc/source/install-guide/configure-hypervisor.rst b/doc/source/install-guide/configure-hypervisor.rst index cc602218ea..d5b88101eb 100644 --- a/doc/source/install-guide/configure-hypervisor.rst +++ b/doc/source/install-guide/configure-hypervisor.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring the hypervisor (optional) ------------------------------------- diff --git a/doc/source/install-guide/configure-keystone.rst b/doc/source/install-guide/configure-keystone.rst index ae26d096b4..dd3cc1aa69 100644 --- a/doc/source/install-guide/configure-keystone.rst +++ b/doc/source/install-guide/configure-keystone.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring Keystone (optional) ------------------------------- diff --git a/doc/source/install-guide/configure-networking.rst b/doc/source/install-guide/configure-networking.rst index a5931595e1..422940b38d 100644 --- a/doc/source/install-guide/configure-networking.rst +++ b/doc/source/install-guide/configure-networking.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring target host networking ---------------------------------- @@ -25,7 +25,7 @@ configure target host networking. Use the same IP address ranges as the underlying physical network interfaces or bridges configured in `the section called "Configuring - the network" `__. For example, if the + the network" `_. For example, if the container network uses 203.0.113.0/24, the *``CONTAINER_MGMT_CIDR``* should also use 203.0.113.0/24. @@ -44,7 +44,7 @@ configure target host networking. addresses in the ranges defined in the previous step. This list should include all IP addresses manually configured on target hosts in the `the section called "Configuring the - network" `__, internal load balancers, + network" `_, internal load balancers, service network bridge, deployment hosts and any other devices to avoid conflicts during the automatic IP address generation process. diff --git a/doc/source/install-guide/configure-openstack.rst b/doc/source/install-guide/configure-openstack.rst index 437e636bed..ec2b9d379d 100644 --- a/doc/source/install-guide/configure-openstack.rst +++ b/doc/source/install-guide/configure-openstack.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Overriding OpenStack Configuration Defaults ------------------------------------------- @@ -13,10 +13,11 @@ the `OpenStack Configuration Reference`_ through the use of a simple set of configuration entries in ``/etc/openstack_deploy/user_variables.yml``. This section provides guidance for how to make use of this facility. Further -guidance is available in the `Developer Documentation`_. +guidance is available in the Developer Documentation in the section titled +`Setting overrides in configuration files`_. .. _OpenStack Configuration Reference: http://docs.openstack.org/draft/config-reference/ -.. _Developer Documentation: ../developer-docs/extending.html#setting-overrides-in-configuration-files +.. _Setting overrides in configuration files: ../developer-docs/extending.html#setting-overrides-in-configuration-files Overriding .conf files ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/install-guide/configure-prereq.rst b/doc/source/install-guide/configure-prereq.rst index fcbfe3124d..718266cbed 100644 --- a/doc/source/install-guide/configure-prereq.rst +++ b/doc/source/install-guide/configure-prereq.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Prerequisites ------------- diff --git a/doc/source/install-guide/configure-rabbitmq.rst b/doc/source/install-guide/configure-rabbitmq.rst index 82f2830a6b..087dd5ce25 100644 --- a/doc/source/install-guide/configure-rabbitmq.rst +++ b/doc/source/install-guide/configure-rabbitmq.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring RabbitMQ (optional) ------------------------------- diff --git a/doc/source/install-guide/configure-sslcertificates.rst b/doc/source/install-guide/configure-sslcertificates.rst index 78fce82b3f..90ace67d51 100644 --- a/doc/source/install-guide/configure-sslcertificates.rst +++ b/doc/source/install-guide/configure-sslcertificates.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Securing services with SSL certificates --------------------------------------- diff --git a/doc/source/install-guide/configure-swift-add.rst b/doc/source/install-guide/configure-swift-add.rst index 8bb2055d26..fc85425a5b 100644 --- a/doc/source/install-guide/configure-swift-add.rst +++ b/doc/source/install-guide/configure-swift-add.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Add to existing deployment -------------------------- @@ -7,10 +7,10 @@ Complete the following procedure to deploy Object Storage on an existing deployment. #. `the section called "Configure and mount storage - devices" `__ + devices" `_ #. `the section called "Configure an Object Storage - deployment" `__ + deployment" `_ #. Optionally, allow all Identity users to use Object Storage by setting ``swift_allow_all_users`` in the ``user_variables.yml`` file to diff --git a/doc/source/install-guide/configure-swift-config.rst b/doc/source/install-guide/configure-swift-config.rst index cbbef3f3df..d943829585 100644 --- a/doc/source/install-guide/configure-swift-config.rst +++ b/doc/source/install-guide/configure-swift-config.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring the service ----------------------- diff --git a/doc/source/install-guide/configure-swift-devices.rst b/doc/source/install-guide/configure-swift-devices.rst index 9f0aa44781..b1ca245722 100644 --- a/doc/source/install-guide/configure-swift-devices.rst +++ b/doc/source/install-guide/configure-swift-devices.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Storage devices --------------- @@ -75,7 +75,7 @@ through ``sdg``. $ mount /srv/node/sdg To view an annotated example of the ``swift.yml`` file, see `Appendix A, -*OSA configuration files* `__. +*OSA configuration files* `_. For the following mounted devices: diff --git a/doc/source/install-guide/configure-swift-glance.rst b/doc/source/install-guide/configure-swift-glance.rst index 9dd3660488..782827a31c 100644 --- a/doc/source/install-guide/configure-swift-glance.rst +++ b/doc/source/install-guide/configure-swift-glance.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Integrate with the Image Service -------------------------------- diff --git a/doc/source/install-guide/configure-swift-overview.rst b/doc/source/install-guide/configure-swift-overview.rst index 70975391d3..e7a23061ea 100644 --- a/doc/source/install-guide/configure-swift-overview.rst +++ b/doc/source/install-guide/configure-swift-overview.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Overview -------- @@ -16,7 +16,7 @@ the ``swift`` section. To view the configuration files, including information about which variables are required and which are optional, see `Appendix A, *OSA -configuration files* `__. +configuration files* `_. -------------- diff --git a/doc/source/install-guide/configure-swift-policies.rst b/doc/source/install-guide/configure-swift-policies.rst index b37b785515..130fae9e58 100644 --- a/doc/source/install-guide/configure-swift-policies.rst +++ b/doc/source/install-guide/configure-swift-policies.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Storage Policies ---------------- @@ -45,7 +45,7 @@ cluster: specified when created. For more information about storage policies, see: `Storage -Policies `__ +Policies `_ -------------- diff --git a/doc/source/install-guide/configure-swift.rst b/doc/source/install-guide/configure-swift.rst index 629be06659..d1eafc6bf2 100644 --- a/doc/source/install-guide/configure-swift.rst +++ b/doc/source/install-guide/configure-swift.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring the Object Storage service (optional) ------------------------------------------------- @@ -21,10 +21,10 @@ modify the Object Storage configuration files to enable Object Storage usage. #. `the section called "Configure and mount storage - devices" `__ + devices" `_ #. `the section called "Configure an Object Storage - deployment" `__ + deployment" `_ #. Optionally, allow all Identity users to use Object Storage by setting ``swift_allow_all_users`` in the ``user_variables.yml`` file to diff --git a/doc/source/install-guide/configure.rst b/doc/source/install-guide/configure.rst index abf0f335d8..1698bc4bfe 100644 --- a/doc/source/install-guide/configure.rst +++ b/doc/source/install-guide/configure.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Chapter 5. Deployment configuration ----------------------------------- diff --git a/doc/source/install-guide/deploymenthost-add.rst b/doc/source/install-guide/deploymenthost-add.rst index d69d2d5463..a1ee5dc9fd 100644 --- a/doc/source/install-guide/deploymenthost-add.rst +++ b/doc/source/install-guide/deploymenthost-add.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring the operating system -------------------------------- diff --git a/doc/source/install-guide/deploymenthost-os.rst b/doc/source/install-guide/deploymenthost-os.rst index 47d078c961..91fa58cdac 100644 --- a/doc/source/install-guide/deploymenthost-os.rst +++ b/doc/source/install-guide/deploymenthost-os.rst @@ -1,10 +1,10 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Installing the operating system ------------------------------- Install the `Ubuntu Server 14.04 (Trusty Tahr) LTS -64-bit `__ operating system on the +64-bit `_ operating system on the deployment host with at least one network interface configured to access the Internet or suitable local repositories. diff --git a/doc/source/install-guide/deploymenthost-osa.rst b/doc/source/install-guide/deploymenthost-osa.rst index 5c554b6a0b..6839f00233 100644 --- a/doc/source/install-guide/deploymenthost-osa.rst +++ b/doc/source/install-guide/deploymenthost-osa.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Installing source and dependencies ---------------------------------- diff --git a/doc/source/install-guide/deploymenthost-sshkeys.rst b/doc/source/install-guide/deploymenthost-sshkeys.rst index 4c11490014..4e30ff9910 100644 --- a/doc/source/install-guide/deploymenthost-sshkeys.rst +++ b/doc/source/install-guide/deploymenthost-sshkeys.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring Secure Shell (SSH) keys ----------------------------------- diff --git a/doc/source/install-guide/deploymenthost.rst b/doc/source/install-guide/deploymenthost.rst index 9b93613843..880f653e32 100644 --- a/doc/source/install-guide/deploymenthost.rst +++ b/doc/source/install-guide/deploymenthost.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Chapter 3. Deployment host -------------------------- @@ -20,7 +20,7 @@ deployment host contains Ansible and orchestrates the OSA installation on the target hosts. One of the target hosts, preferably one of the infrastructure variants, can be used as the deployment host. To use a deployment host as a target host, follow the steps in `Chapter 4, -*Target hosts* `__ on the deployment host. This +*Target hosts* `_ on the deployment host. This guide assumes separate deployment and target hosts. -------------- diff --git a/doc/source/install-guide/index.rst b/doc/source/install-guide/index.rst index b7fde9f6b3..843c44f730 100644 --- a/doc/source/install-guide/index.rst +++ b/doc/source/install-guide/index.rst @@ -1,13 +1,13 @@ -OpenStack Ansible Installation Guide +OpenStack-Ansible Installation Guide ==================================== -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Overview ^^^^^^^^ -.. toctree:: +.. toctree:: overview.rst @@ -22,7 +22,7 @@ Deployment host Target hosts ^^^^^^^^^^^^ -.. toctree:: +.. toctree:: targethosts.rst @@ -30,7 +30,7 @@ Target hosts Configuration ^^^^^^^^^^^^^ -.. toctree:: +.. toctree:: configure.rst @@ -38,7 +38,7 @@ Configuration Installation ^^^^^^^^^^^^ -.. toctree:: +.. toctree:: install-foundation.rst install-infrastructure.rst @@ -48,15 +48,15 @@ Installation Operations ^^^^^^^^^^ -.. toctree:: +.. toctree:: ops.rst -Appendix -^^^^^^^^ +Appendices +^^^^^^^^^^ -.. toctree:: +.. toctree:: app-configfiles.rst app-resources.rst diff --git a/doc/source/install-guide/install-foundation-run.rst b/doc/source/install-guide/install-foundation-run.rst index 8e0d8ebbbe..124310c310 100644 --- a/doc/source/install-guide/install-foundation-run.rst +++ b/doc/source/install-guide/install-foundation-run.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Running the foundation playbook ------------------------------- diff --git a/doc/source/install-guide/install-foundation.rst b/doc/source/install-guide/install-foundation.rst index 9388fdbf98..c857aa6c77 100644 --- a/doc/source/install-guide/install-foundation.rst +++ b/doc/source/install-guide/install-foundation.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Chapter 6. Foundation playbooks ------------------------------- diff --git a/doc/source/install-guide/install-infrastructure-run.rst b/doc/source/install-guide/install-infrastructure-run.rst index 2a06c6df74..f42eac4902 100644 --- a/doc/source/install-guide/install-infrastructure-run.rst +++ b/doc/source/install-guide/install-infrastructure-run.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Running the infrastructure playbook ----------------------------------- diff --git a/doc/source/install-guide/install-infrastructure-verify.rst b/doc/source/install-guide/install-infrastructure-verify.rst index ab5f890c03..556718bc10 100644 --- a/doc/source/install-guide/install-infrastructure-verify.rst +++ b/doc/source/install-guide/install-infrastructure-verify.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Verifying infrastructure operation ---------------------------------- diff --git a/doc/source/install-guide/install-infrastructure.rst b/doc/source/install-guide/install-infrastructure.rst index 4c9d32a33e..1200ab2272 100644 --- a/doc/source/install-guide/install-infrastructure.rst +++ b/doc/source/install-guide/install-infrastructure.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Chapter 7. Infrastructure playbooks ----------------------------------- diff --git a/doc/source/install-guide/install-openstack-run.rst b/doc/source/install-guide/install-openstack-run.rst index 7c06a5f695..1bb6d67fb3 100644 --- a/doc/source/install-guide/install-openstack-run.rst +++ b/doc/source/install-guide/install-openstack-run.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Running the OpenStack playbook ------------------------------ diff --git a/doc/source/install-guide/install-openstack-utilitycontainer.rst b/doc/source/install-guide/install-openstack-utilitycontainer.rst index 1be08ebbbd..262aad6dc0 100644 --- a/doc/source/install-guide/install-openstack-utilitycontainer.rst +++ b/doc/source/install-guide/install-openstack-utilitycontainer.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Utility container ----------------- @@ -14,7 +14,7 @@ For example, the tempest playbooks are installed on the utility container since tempest testing does not need a container of its own. For another example of using the utility container, see `the section called "Verifying OpenStack -operation" `__. +operation" `_. -------------- diff --git a/doc/source/install-guide/install-openstack-verify.rst b/doc/source/install-guide/install-openstack-verify.rst index 3de1458b0a..89e271c552 100644 --- a/doc/source/install-guide/install-openstack-verify.rst +++ b/doc/source/install-guide/install-openstack-verify.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Verifying OpenStack operation ----------------------------- diff --git a/doc/source/install-guide/install-openstack.rst b/doc/source/install-guide/install-openstack.rst index e36558e591..ee513d7cf1 100644 --- a/doc/source/install-guide/install-openstack.rst +++ b/doc/source/install-guide/install-openstack.rst @@ -1,9 +1,9 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Chapter 8. OpenStack playbooks ------------------------------ -.. toctree:: +.. toctree:: install-openstack-run.rst install-openstack-utilitycontainer.rst diff --git a/doc/source/install-guide/navigation.txt b/doc/source/install-guide/navigation.txt index ffafd61352..f6c86bd471 100644 --- a/doc/source/install-guide/navigation.txt +++ b/doc/source/install-guide/navigation.txt @@ -1,115 +1,3 @@ -`Main Index `__ - ----------- - -- `2. Overview `__ - - - `About OpenStack Ansible Deployment `__ - - `Ansible `__ - - `Linux Containers (LXC) `__ - - `Host layout `__ - - `Host networking `__ - - `OpenStack Networking `__ - - `Installation requirements `__ - - `Installation workflow `__ - -- `3. Deployment host `__ - - - `Installing the operating system `__ - - `Configuring the operating - system `__ - - `Installing source and - dependencies `__ - - `Configuring Secure Shell (SSH) - keys `__ - -- `4. Target hosts `__ - - - `Installing the operating system `__ - - `Configuring Secure Shell (SSH) - keys `__ - - `Configuring the operating system `__ - - `Configuring LVM `__ - - `Configuring the network `__ - - - `Reference - architecture `__ - - `Configuring the network on a target - host `__ - -- `5. Deployment configuration `__ - - - `Prerequisites `__ - - `Configuring target host - networking `__ - - `Configuring target hosts `__ - - `Configuring service credentials `__ - - `Configuring the hypervisor - (optional) `__ - - `Configuring the Image service - (optional) `__ - - `Configuring the Block Storage service - (optional) `__ - - - `NFS back-end `__ - - `Backup `__ - - `Availability zones `__ - - - `Configuring the Object Storage service - (optional) `__ - - - `Overview `__ - - `Storage devices `__ - - `Object Storage service `__ - - `Integrate with the Image Service - `__ - - `Add to existing deployment `__ - - `Policies `__ - - - `Configuring HAProxy (optional) `__ - - `Configuring Horizon (optional) `__ - - `Configuring Keystone (optional) `__ - - `Configuring RabbitMQ (optional) `__ - - `Securing services with SSL certificates - `__ - -- `6. Installation `__ - - - `Foundation components `__ - - - `Running the foundation - playbook `__ - - - `Infrastructure components `__ - - - `Running the infrastructure - playbook `__ - - `Verifying infrastructure - operation `__ - - - `OpenStack components `__ - - - `Running the OpenStack - playbook `__ - - `Utility Container - Overview `__ - - `Verifying OpenStack - operation `__ - -- `7. Operations `__ - - - `Adding a compute host `__ - - `Galera cluster maintenance `__ - - - `Removing nodes `__ - - `Starting a cluster `__ - - `Cluster recovery `__ - - `Single-node failure `__ - - `Multi-node failure `__ - - `Complete failure `__ - - `Rebuilding a - container `__ - -- `A. OSA configuration files `__ - -- `B. Additional resources `__ +* `Documentation Home <../index.html>`_ +* `Installation Guide `_ +* `Developer Documentation <../developer-docs/index.html>`_ diff --git a/doc/source/install-guide/ops-addcomputehost.rst b/doc/source/install-guide/ops-addcomputehost.rst index bd21d57a6f..ce4436d828 100644 --- a/doc/source/install-guide/ops-addcomputehost.rst +++ b/doc/source/install-guide/ops-addcomputehost.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Adding a compute host --------------------- @@ -7,7 +7,7 @@ Use the following procedure to add a compute host to an operational cluster. #. Configure the host as a target host. See `Chapter 4, *Target - hosts* `__ for more information. + hosts* `_ for more information. #. Edit the ``/etc/openstack_deploy/openstack_user_config.yml`` file and add the host to the ``compute_hosts`` stanza. diff --git a/doc/source/install-guide/ops-galera-recovery.rst b/doc/source/install-guide/ops-galera-recovery.rst index f76fcf914c..c251b9d33b 100644 --- a/doc/source/install-guide/ops-galera-recovery.rst +++ b/doc/source/install-guide/ops-galera-recovery.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Galera cluster recovery ----------------------- diff --git a/doc/source/install-guide/ops-galera-recoverycomplete.rst b/doc/source/install-guide/ops-galera-recoverycomplete.rst index 1aab615178..fdfda9cff5 100644 --- a/doc/source/install-guide/ops-galera-recoverycomplete.rst +++ b/doc/source/install-guide/ops-galera-recoverycomplete.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Complete failure ---------------- diff --git a/doc/source/install-guide/ops-galera-recoverycontainer.rst b/doc/source/install-guide/ops-galera-recoverycontainer.rst index 09cb2f5777..7fbc7bc3ad 100644 --- a/doc/source/install-guide/ops-galera-recoverycontainer.rst +++ b/doc/source/install-guide/ops-galera-recoverycontainer.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Rebuilding a container ---------------------- diff --git a/doc/source/install-guide/ops-galera-recoverymulti.rst b/doc/source/install-guide/ops-galera-recoverymulti.rst index 7a8d49ee01..d8b7da2402 100644 --- a/doc/source/install-guide/ops-galera-recoverymulti.rst +++ b/doc/source/install-guide/ops-galera-recoverymulti.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Multi-node failure ------------------ @@ -33,7 +33,7 @@ recover cannot join the cluster because it no longer exists. server indicates ``non-Primary`` because it cannot achieve quorum. #. Run the following command to - `rebootstrap `__ + `rebootstrap `_ the operational node into the cluster. .. code-block:: bash diff --git a/doc/source/install-guide/ops-galera-recoverysingle.rst b/doc/source/install-guide/ops-galera-recoverysingle.rst index 74b7549ea7..f0819666e7 100644 --- a/doc/source/install-guide/ops-galera-recoverysingle.rst +++ b/doc/source/install-guide/ops-galera-recoverysingle.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Single-node failure ------------------- diff --git a/doc/source/install-guide/ops-galera-remove.rst b/doc/source/install-guide/ops-galera-remove.rst index cf2a1fb394..f69b8fd64a 100644 --- a/doc/source/install-guide/ops-galera-remove.rst +++ b/doc/source/install-guide/ops-galera-remove.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Removing nodes -------------- diff --git a/doc/source/install-guide/ops-galera-start.rst b/doc/source/install-guide/ops-galera-start.rst index 884663d6dd..573172110b 100644 --- a/doc/source/install-guide/ops-galera-start.rst +++ b/doc/source/install-guide/ops-galera-start.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Starting a cluster ------------------ diff --git a/doc/source/install-guide/ops-galera.rst b/doc/source/install-guide/ops-galera.rst index a3b94e2b1e..23123dca6e 100644 --- a/doc/source/install-guide/ops-galera.rst +++ b/doc/source/install-guide/ops-galera.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Galera cluster maintenance -------------------------- diff --git a/doc/source/install-guide/ops-troubleshooting-containernetworking.rst b/doc/source/install-guide/ops-troubleshooting-containernetworking.rst index 834d9ba784..0876d39233 100644 --- a/doc/source/install-guide/ops-troubleshooting-containernetworking.rst +++ b/doc/source/install-guide/ops-troubleshooting-containernetworking.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Container networking issues --------------------------- diff --git a/doc/source/install-guide/ops-troubleshooting.rst b/doc/source/install-guide/ops-troubleshooting.rst index 0bda0c6202..9e9adfda16 100644 --- a/doc/source/install-guide/ops-troubleshooting.rst +++ b/doc/source/install-guide/ops-troubleshooting.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Troubleshooting --------------- diff --git a/doc/source/install-guide/ops.rst b/doc/source/install-guide/ops.rst index 4570421191..4ba4e80b76 100644 --- a/doc/source/install-guide/ops.rst +++ b/doc/source/install-guide/ops.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Chapter 9. Operations --------------------- diff --git a/doc/source/install-guide/overview-ansible.rst b/doc/source/install-guide/overview-ansible.rst index 9aeca7aede..39f8f544e3 100644 --- a/doc/source/install-guide/overview-ansible.rst +++ b/doc/source/install-guide/overview-ansible.rst @@ -1,17 +1,17 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Ansible ------- -OpenStack Ansible Deployment uses a combination of Ansible and -Linux Containers (LXC) to install and manage OpenStack. Ansible -provides an automation platform to simplify system and application -deployment. Ansible manages systems using Secure Shell (SSH) +OpenStack-Ansible Deployment uses a combination of Ansible and +Linux Containers (LXC) to install and manage OpenStack. Ansible +provides an automation platform to simplify system and application +deployment. Ansible manages systems using Secure Shell (SSH) instead of unique protocols that require remote daemons or agents. Ansible uses *playbooks* written in the YAML language for orchestration. For more information, see `Ansible - Intro to -Playbooks `__. +Playbooks `_. In this guide, we refer to the host running Ansible playbooks as the *deployment host* and the hosts on which Ansible installs OSA as the @@ -19,13 +19,13 @@ the *deployment host* and the hosts on which Ansible installs OSA as the A recommended minimal layout for deployments involves five target hosts in total: three infrastructure hosts, one compute host, and one -logging host. All hosts require three network interfaces. More -information on setting up target hosts can be found in `the section -called "Host layout" `__. +logging host. All hosts require three network interfaces. More +information on setting up target hosts can be found in `the section +called "Host layout" `_. For more information on physical, logical, and virtual network interfaces within hosts see `the section called "Host -networking" `__. +networking" `_. -------------- diff --git a/doc/source/install-guide/overview-hostlayout.rst b/doc/source/install-guide/overview-hostlayout.rst index 11c7f01e65..d674e4e5d6 100644 --- a/doc/source/install-guide/overview-hostlayout.rst +++ b/doc/source/install-guide/overview-hostlayout.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Host layout ----------- @@ -14,8 +14,8 @@ The recommended layout contains a minimum of five hosts (or servers). To use the optional Block Storage (cinder) service, a sixth host is recommended. Block Storage hosts require an LVM volume group named *cinder-volumes*. See `the section called "Installation -requirements" `__ and `the section -called "Configuring LVM" `__ for more information. +requirements" `_ and `the section +called "Configuring LVM" `_ for more information. The hosts are called *target hosts* because Ansible deploys the OSA environment within these hosts. The OSA environment also recommends a diff --git a/doc/source/install-guide/overview-hostnetworking.rst b/doc/source/install-guide/overview-hostnetworking.rst index 059bbd003d..201a0bf7bd 100644 --- a/doc/source/install-guide/overview-hostnetworking.rst +++ b/doc/source/install-guide/overview-hostnetworking.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Host networking --------------- @@ -29,7 +29,7 @@ random names for ``veth`` pairs. The relationship between physical interfaces, logical interfaces, bridges, and virtual interfaces within containers is shown in `Figure 2.2, "Network -components" `__. +components" `_.   @@ -93,7 +93,7 @@ Target hosts can contain the following network bridges: layer 2 connectivity. `Figure 2.3, "Container network -architecture" `__ +architecture" `_ provides a visual representation of network components for services in containers. @@ -106,7 +106,7 @@ containers. By default, OSA installs the Compute service in a bare metal environment rather than within a container. `Figure 2.4, "Bare/Metal network -architecture" `__ +architecture" `_ provides a visual representation of the unique layout of network components on a Compute host. diff --git a/doc/source/install-guide/overview-lxc.rst b/doc/source/install-guide/overview-lxc.rst index ea8ea35ed0..04b40ecb2a 100644 --- a/doc/source/install-guide/overview-lxc.rst +++ b/doc/source/install-guide/overview-lxc.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Linux Containers (LXC) ---------------------- diff --git a/doc/source/install-guide/overview-neutron.rst b/doc/source/install-guide/overview-neutron.rst index b77a0caeb2..f9d2091908 100644 --- a/doc/source/install-guide/overview-neutron.rst +++ b/doc/source/install-guide/overview-neutron.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide OpenStack Networking -------------------- @@ -6,7 +6,7 @@ OpenStack Networking OpenStack Networking (neutron) is configured to use a DHCP agent, L3 Agent and Linux Bridge agent within a networking agents container. `Figure 2.5, "Networking agents -containers" `__ +containers" `_ shows the interaction of these agents, network components, and connection to a physical network. @@ -17,7 +17,7 @@ connection to a physical network. .. image:: figures/networking-neutronagents.png The Compute service uses the KVM hypervisor. `Figure 2.6, "Compute -hosts" `__ shows +hosts" `_ shows the interaction of instances, Linux Bridge agent, network components, and connection to a physical network. diff --git a/doc/source/install-guide/overview-osa.rst b/doc/source/install-guide/overview-osa.rst index 8b6f9708f4..f658657e19 100644 --- a/doc/source/install-guide/overview-osa.rst +++ b/doc/source/install-guide/overview-osa.rst @@ -1,6 +1,6 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide -About OpenStack Ansible Deployment +About OpenStack-Ansible Deployment ---------------------------------- OpenStack-Ansible uses the Ansible IT automation framework to @@ -8,9 +8,9 @@ create an OpenStack cluster on Ubuntu Linux. OpenStack components are installed into Linux Containers (LXC) for isolation and ease of maintenance. -| OpenStack Ansible Deployment +| OpenStack-Ansible Deployment -This documentation is intended for deployers of the OpenStack Ansible +This documentation is intended for deployers of the OpenStack-Ansible deployment system who are interested in installing an OpenStack. The document is for informational purposes only and is provided "AS IS." @@ -21,7 +21,7 @@ purposes only. We do not intend our use or display of other companies" tradenames, trademarks, or service marks to imply a relationship with, or endorsement or sponsorship of us by, these other companies. -`OpenStack.org `__ +`OpenStack.org `_ .. include:: navigation.txt diff --git a/doc/source/install-guide/overview-requirements.rst b/doc/source/install-guide/overview-requirements.rst index 95fff20327..f124b533fe 100644 --- a/doc/source/install-guide/overview-requirements.rst +++ b/doc/source/install-guide/overview-requirements.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Installation requirements ------------------------- diff --git a/doc/source/install-guide/overview-workflow.rst b/doc/source/install-guide/overview-workflow.rst index 6ded2075d6..c8193a70f0 100644 --- a/doc/source/install-guide/overview-workflow.rst +++ b/doc/source/install-guide/overview-workflow.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Installation workflow --------------------- diff --git a/doc/source/install-guide/overview.rst b/doc/source/install-guide/overview.rst index 41041366c3..090ca8e34c 100644 --- a/doc/source/install-guide/overview.rst +++ b/doc/source/install-guide/overview.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Chapter 2. Overview ------------------- diff --git a/doc/source/install-guide/targethosts-add.rst b/doc/source/install-guide/targethosts-add.rst index 846862e474..685ae94fe3 100644 --- a/doc/source/install-guide/targethosts-add.rst +++ b/doc/source/install-guide/targethosts-add.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring the operating system -------------------------------- diff --git a/doc/source/install-guide/targethosts-configlvm.rst b/doc/source/install-guide/targethosts-configlvm.rst index d8c5a1a268..3e324b9db5 100644 --- a/doc/source/install-guide/targethosts-configlvm.rst +++ b/doc/source/install-guide/targethosts-configlvm.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring LVM --------------- @@ -21,4 +21,4 @@ Configuring LVM -------------- -.. include:: navigation.txt \ No newline at end of file +.. include:: navigation.txt diff --git a/doc/source/install-guide/targethosts-network.rst b/doc/source/install-guide/targethosts-network.rst index b5599d77c8..74ad842071 100644 --- a/doc/source/install-guide/targethosts-network.rst +++ b/doc/source/install-guide/targethosts-network.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring the network ----------------------- @@ -41,8 +41,8 @@ following optional components: - Storage network subinterface on the ``bond0`` interface and ``br-storage`` bridge with a static IP address. -For more information, see `OpenStack Ansible -Networking `__. +For more information, see `OpenStack-Ansible +Networking `_. -------------- diff --git a/doc/source/install-guide/targethosts-networkexample.rst b/doc/source/install-guide/targethosts-networkexample.rst index bbe4e54e96..a313e4aa61 100644 --- a/doc/source/install-guide/targethosts-networkexample.rst +++ b/doc/source/install-guide/targethosts-networkexample.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring the network on a target host ---------------------------------------- @@ -6,9 +6,9 @@ Configuring the network on a target host This example uses the following parameters to configure networking on a single target host. See `Figure 4.2, "Target hosts for infrastructure, networking, and storage -services" `__ +services" `_ and `Figure 4.3, "Target hosts for Compute -service" `__ +service" `_ for a visual representation of these parameters in the architecture. - VLANs: diff --git a/doc/source/install-guide/targethosts-networkrefarch.rst b/doc/source/install-guide/targethosts-networkrefarch.rst index 96c9a29497..27545ee9be 100644 --- a/doc/source/install-guide/targethosts-networkrefarch.rst +++ b/doc/source/install-guide/targethosts-networkrefarch.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Reference architecture ---------------------- diff --git a/doc/source/install-guide/targethosts-os.rst b/doc/source/install-guide/targethosts-os.rst index 0f55b432ed..e7c32572d2 100644 --- a/doc/source/install-guide/targethosts-os.rst +++ b/doc/source/install-guide/targethosts-os.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Installing the operating system ------------------------------- diff --git a/doc/source/install-guide/targethosts-sshkeys.rst b/doc/source/install-guide/targethosts-sshkeys.rst index ddaa8f8a96..08a106baab 100644 --- a/doc/source/install-guide/targethosts-sshkeys.rst +++ b/doc/source/install-guide/targethosts-sshkeys.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Configuring Secure Shell (SSH) keys ----------------------------------- diff --git a/doc/source/install-guide/targethosts.rst b/doc/source/install-guide/targethosts.rst index f6e1c6ca9f..be24c77c23 100644 --- a/doc/source/install-guide/targethosts.rst +++ b/doc/source/install-guide/targethosts.rst @@ -1,4 +1,4 @@ -`Home `__ OpenStack Ansible Installation Guide +`Home `_ OpenStack-Ansible Installation Guide Chapter 4. Target hosts -----------------------