From bdb856c8fe6a8c62f4efb56c77ccb9458fb178d4 Mon Sep 17 00:00:00 2001 From: daz Date: Fri, 10 Jun 2016 14:57:54 +1000 Subject: [PATCH] [docs] Migrate ops and appendix content 1. Migrate Ops chapter and tips and tricks appendix to developer docs 2. Migrate Appendix G to a chapter in the developer docs 3. Minor edits Change-Id: I4070f02b75a8f9614545be0744e63ba76a3b49e2 Implements: blueprint osa-install-guide-overhaul --- .../configure-network-services.rst | 2 +- doc/source/developer-docs/index.rst | 3 +- ...stallation-hosts-limited-connectivity.rst} | 11 +- .../ops-addcomputehost.rst | 0 .../ops-galera-recovery.rst | 0 .../ops-galera-remove.rst | 0 .../ops-galera-start.rst | 0 .../ops-galera.rst | 0 .../ops-logging.rst | 0 .../ops-tips.rst} | 12 +- .../ops-troubleshooting.rst | 0 doc/source/developer-docs/ops.rst | 19 +++ .../app-custom-layouts.rst | 2 +- .../install-guide-revised-draft/app-nuage.rst | 13 +- .../app-plumgrid.rst | 2 +- .../install-guide-revised-draft/index.rst | 12 +- .../install-guide-revised-draft/ops.rst | 20 --- doc/source/upgrade-guide/minor-upgrade.rst | 132 ------------------ 18 files changed, 40 insertions(+), 188 deletions(-) rename doc/source/{install-guide-revised-draft/app-no-internet-connectivity.rst => developer-docs/installation-hosts-limited-connectivity.rst} (95%) rename doc/source/{install-guide-revised-draft => developer-docs}/ops-addcomputehost.rst (100%) rename doc/source/{install-guide-revised-draft => developer-docs}/ops-galera-recovery.rst (100%) rename doc/source/{install-guide-revised-draft => developer-docs}/ops-galera-remove.rst (100%) rename doc/source/{install-guide-revised-draft => developer-docs}/ops-galera-start.rst (100%) rename doc/source/{install-guide-revised-draft => developer-docs}/ops-galera.rst (100%) rename doc/source/{install-guide-revised-draft => developer-docs}/ops-logging.rst (100%) rename doc/source/{install-guide-revised-draft/app-tips.rst => developer-docs/ops-tips.rst} (83%) rename doc/source/{install-guide-revised-draft => developer-docs}/ops-troubleshooting.rst (100%) create mode 100644 doc/source/developer-docs/ops.rst delete mode 100644 doc/source/install-guide-revised-draft/ops.rst delete mode 100644 doc/source/upgrade-guide/minor-upgrade.rst diff --git a/doc/source/developer-docs/configure-network-services.rst b/doc/source/developer-docs/configure-network-services.rst index 87d1d19229..5a6af21cde 100644 --- a/doc/source/developer-docs/configure-network-services.rst +++ b/doc/source/developer-docs/configure-network-services.rst @@ -103,7 +103,7 @@ Deploying LBaaS v2 # openstack-ansible os-neutron-install.yml # openstack-ansible os-horizon-install.yml -.. _lbaas-special-notes +.. _lbaas-special-notes: Special notes about LBaaS ------------------------- diff --git a/doc/source/developer-docs/index.rst b/doc/source/developer-docs/index.rst index 8d26075299..1948f89603 100644 --- a/doc/source/developer-docs/index.rst +++ b/doc/source/developer-docs/index.rst @@ -10,12 +10,13 @@ Contents: :maxdepth: 2 quickstart-aio + installation-hosts-limited-connectivity scripts playbooks extending + ops contribute core-reviewers additional-roles inventory deploy-config - diff --git a/doc/source/install-guide-revised-draft/app-no-internet-connectivity.rst b/doc/source/developer-docs/installation-hosts-limited-connectivity.rst similarity index 95% rename from doc/source/install-guide-revised-draft/app-no-internet-connectivity.rst rename to doc/source/developer-docs/installation-hosts-limited-connectivity.rst index 58cc4b4e4c..1cbb0f38a3 100644 --- a/doc/source/install-guide-revised-draft/app-no-internet-connectivity.rst +++ b/doc/source/developer-docs/installation-hosts-limited-connectivity.rst @@ -1,11 +1,6 @@ -`Home `__ OpenStack-Ansible Installation Guide - -=========================================================== -Appendix G. Installation on hosts with limited connectivity -=========================================================== - -Introduction -~~~~~~~~~~~~ +=============================================== +Installation on hosts with limited connectivity +=============================================== Many playbooks and roles in OpenStack-Ansible retrieve dependencies from the public Internet by default. Many deployers block direct outbound connectivity diff --git a/doc/source/install-guide-revised-draft/ops-addcomputehost.rst b/doc/source/developer-docs/ops-addcomputehost.rst similarity index 100% rename from doc/source/install-guide-revised-draft/ops-addcomputehost.rst rename to doc/source/developer-docs/ops-addcomputehost.rst diff --git a/doc/source/install-guide-revised-draft/ops-galera-recovery.rst b/doc/source/developer-docs/ops-galera-recovery.rst similarity index 100% rename from doc/source/install-guide-revised-draft/ops-galera-recovery.rst rename to doc/source/developer-docs/ops-galera-recovery.rst diff --git a/doc/source/install-guide-revised-draft/ops-galera-remove.rst b/doc/source/developer-docs/ops-galera-remove.rst similarity index 100% rename from doc/source/install-guide-revised-draft/ops-galera-remove.rst rename to doc/source/developer-docs/ops-galera-remove.rst diff --git a/doc/source/install-guide-revised-draft/ops-galera-start.rst b/doc/source/developer-docs/ops-galera-start.rst similarity index 100% rename from doc/source/install-guide-revised-draft/ops-galera-start.rst rename to doc/source/developer-docs/ops-galera-start.rst diff --git a/doc/source/install-guide-revised-draft/ops-galera.rst b/doc/source/developer-docs/ops-galera.rst similarity index 100% rename from doc/source/install-guide-revised-draft/ops-galera.rst rename to doc/source/developer-docs/ops-galera.rst diff --git a/doc/source/install-guide-revised-draft/ops-logging.rst b/doc/source/developer-docs/ops-logging.rst similarity index 100% rename from doc/source/install-guide-revised-draft/ops-logging.rst rename to doc/source/developer-docs/ops-logging.rst diff --git a/doc/source/install-guide-revised-draft/app-tips.rst b/doc/source/developer-docs/ops-tips.rst similarity index 83% rename from doc/source/install-guide-revised-draft/app-tips.rst rename to doc/source/developer-docs/ops-tips.rst index 3ece753053..e6f8604eeb 100644 --- a/doc/source/install-guide-revised-draft/app-tips.rst +++ b/doc/source/developer-docs/ops-tips.rst @@ -1,8 +1,6 @@ -`Home `__ OpenStack-Ansible Installation Guide - -=========================== -Appendix D: Tips and tricks -=========================== +=============== +Tips and tricks +=============== Ansible forks ~~~~~~~~~~~~~ @@ -12,8 +10,8 @@ fork makes use of a Session. By default, Ansible sets the number of forks to 5. However, you can increase the number of forks used in order to improve deployment performance in large environments. -Note that a number of forks larger than 10 will cause issues for any playbooks -which make use of ``delegate_to`` or ``local_action`` in the tasks. It is +Note that more than 10 forks will cause issues for any playbooks +which use ``delegate_to`` or ``local_action`` in the tasks. It is recommended that the number of forks are not raised when executing against the Control Plane, as this is where delegation is most often used. diff --git a/doc/source/install-guide-revised-draft/ops-troubleshooting.rst b/doc/source/developer-docs/ops-troubleshooting.rst similarity index 100% rename from doc/source/install-guide-revised-draft/ops-troubleshooting.rst rename to doc/source/developer-docs/ops-troubleshooting.rst diff --git a/doc/source/developer-docs/ops.rst b/doc/source/developer-docs/ops.rst new file mode 100644 index 0000000000..8ffd031d4d --- /dev/null +++ b/doc/source/developer-docs/ops.rst @@ -0,0 +1,19 @@ +========== +Operations +========== + +The following operations and troubleshooting information apply to +installed environments. + +.. toctree:: + + ops-addcomputehost.rst + ops-galera.rst + ops-logging.rst + ops-tips.rst + ops-troubleshooting.rst + + +-------------- + +.. include:: navigation.txt diff --git a/doc/source/install-guide-revised-draft/app-custom-layouts.rst b/doc/source/install-guide-revised-draft/app-custom-layouts.rst index 8cc7dee42a..eaeca72dff 100644 --- a/doc/source/install-guide-revised-draft/app-custom-layouts.rst +++ b/doc/source/install-guide-revised-draft/app-custom-layouts.rst @@ -1,7 +1,7 @@ `Home `_ OpenStack-Ansible Installation Guide ================================================ -Appendix H: Customizing host and service layouts +Appendix E: Customizing host and service layouts ================================================ Understanding the default layout diff --git a/doc/source/install-guide-revised-draft/app-nuage.rst b/doc/source/install-guide-revised-draft/app-nuage.rst index a0cd26d9f4..7246490e46 100644 --- a/doc/source/install-guide-revised-draft/app-nuage.rst +++ b/doc/source/install-guide-revised-draft/app-nuage.rst @@ -1,10 +1,11 @@ `Home `__ OpenStack-Ansible Installation Guide -Appendix F. Using Nuage Neutron Plugin --------------------------------------- +====================================== +Appendix C. Using Nuage Neutron Plugin +====================================== Introduction -============ +~~~~~~~~~~~~ This document describes the steps required to deploy Nuage Networks VCS with OpenStack-Ansible (OSA). These steps include: @@ -20,7 +21,7 @@ with OpenStack-Ansible (OSA). These steps include: - Execute the playbooks. Prerequisites -============= +~~~~~~~~~~~~~ #. The deployment environment has been configured according to OSA best-practices. This includes cloning OSA software and bootstrapping @@ -33,7 +34,7 @@ Prerequisites /opt/nuage-openstack-ansible Configure Nuage Neutron Plugin -============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Configuring the Neutron plugin requires creating/editing of parameters in following two files: @@ -122,7 +123,7 @@ Also modify the following parameters in this file as per your Nuage VCS environm - { name: "nuage_repo", link: "" } Installation -============ +~~~~~~~~~~~~ #. After multi-node OpenStack cluster is setup as detailed above; start the OpenStack deployment as listed in the OpenStack-Ansible Install guide by diff --git a/doc/source/install-guide-revised-draft/app-plumgrid.rst b/doc/source/install-guide-revised-draft/app-plumgrid.rst index 7127c050f9..472568618f 100644 --- a/doc/source/install-guide-revised-draft/app-plumgrid.rst +++ b/doc/source/install-guide-revised-draft/app-plumgrid.rst @@ -1,7 +1,7 @@ `Home `__ OpenStack-Ansible Installation Guide ========================================= -Appendix E: Using PLUMgrid Neutron plugin +Appendix D: Using PLUMgrid Neutron plugin ========================================= Installing source and host networking diff --git a/doc/source/install-guide-revised-draft/index.rst b/doc/source/install-guide-revised-draft/index.rst index 71c848d0aa..8de3fcdd8b 100644 --- a/doc/source/install-guide-revised-draft/index.rst +++ b/doc/source/install-guide-revised-draft/index.rst @@ -49,14 +49,6 @@ Installation install-openstack.rst -Operations -^^^^^^^^^^ - -.. toctree:: - - ops.rst - - Appendices ^^^^^^^^^^ @@ -64,8 +56,6 @@ Appendices app-configfiles.rst app-resources.rst - app-tips.rst app-plumgrid.rst app-nuage.rst - app-no-internet-connectivity.rst - app-custom-layouts.rst \ No newline at end of file + app-custom-layouts.rst diff --git a/doc/source/install-guide-revised-draft/ops.rst b/doc/source/install-guide-revised-draft/ops.rst deleted file mode 100644 index 308d2d19c4..0000000000 --- a/doc/source/install-guide-revised-draft/ops.rst +++ /dev/null @@ -1,20 +0,0 @@ -`Home `_ OpenStack-Ansible Installation Guide - -===================== -Chapter 8. Operations -===================== - -The following operations and troubleshooting procedures apply to -installed environments. - -.. toctree:: - - ops-addcomputehost.rst - ops-galera.rst - ops-logging.rst - ops-troubleshooting.rst - - --------------- - -.. include:: navigation.txt diff --git a/doc/source/upgrade-guide/minor-upgrade.rst b/doc/source/upgrade-guide/minor-upgrade.rst deleted file mode 100644 index 982e212292..0000000000 --- a/doc/source/upgrade-guide/minor-upgrade.rst +++ /dev/null @@ -1,132 +0,0 @@ -.. _minor-upgrades: - -============== -Minor upgrades -============== - -.. note:: To avoid issues and simplify troubleshooting during an upgrade, - first disable the security hardening role by setting your - variable ``apply_security_hardening`` to ``False`` in the - :file:`user_variables.yml` file. - -A minor upgrade typically requires the following steps: - -#. Change directory into the repository clone root directory: - - .. code-block:: console - - # cd /opt/openstack-ansible - -#. Ensure your OpenStack-Ansible code is on the latest Newton release tag (14.x.x): - - .. code-block:: console - - # git checkout stable/newton - # LATEST_TAG=$(git describe --abbrev=0 --tags) - # git checkout ${LATEST_TAG} - -#. Update all the dependent roles to the latest version: - - .. code-block:: console - - # ./scripts/bootstrap-ansible.sh - -#. Change into the playbooks directory: - - .. code-block:: console - - # cd playbooks - -#. Update the hosts: - - .. code-block:: console - - # openstack-ansible setup-hosts.yml - -#. Update the infrastructure: - - .. code-block:: console - - # openstack-ansible -e rabbitmq_upgrade=true \ - setup-infrastructure.yml - -#. Update all OpenStack services: - - .. code-block:: console - - # openstack-ansible setup-openstack.yml - -.. note:: - - Scope upgrades to specific OpenStack components by - executing each of the component playbooks using groups. - -For example: - -#. Update only the Compute hosts: - - .. code-block:: console - - # openstack-ansible os-nova-install.yml --limit nova_compute - -#. Update only a single Compute host: - - .. note:: - - Skipping the ``nova-key`` tag is necessary as the keys on - all Compute hosts will not be gathered. - - .. code-block:: console - - # openstack-ansible os-nova-install.yml --limit \ - --skip-tags 'nova-key' - -To see which hosts belong to which groups, the -``inventory-manage.py`` script shows all groups and their hosts. -For example: - -#. Change directory into the repository clone root directory: - - .. code-block:: console - - # cd /opt/openstack-ansible - -#. Show all groups and which hosts belong to them: - - .. code-block:: console - - # ./scripts/inventory-manage.py -G - -#. Show all hosts and which groups they belong: - - .. code-block:: console - - # ./scripts/inventory-manage.py -g - -To see which hosts a playbook will execute against, and to see which -tasks will execute. - -#. Change directory into the repository clone playbooks directory: - - .. code-block:: console - - # cd /opt/openstack-ansible/playbooks - -#. See the hosts in the ``nova_compute`` group which a playbook executes against: - - .. code-block:: console - - # openstack-ansible os-nova-install.yml --limit nova_compute \ - --list-hosts - -#. See the tasks which will be executed on hosts in the ``nova_compute`` group: - - .. code-block:: console - - # openstack-ansible os-nova-install.yml --limit nova_compute \ - --skip-tags 'nova-key' \ - --list-tasks - --------------- - -.. include:: navigation.txt \ No newline at end of file