diff --git a/doc/source/install-guide-revised-draft/figures/installation-workflow-overview.png b/doc/source/install-guide-revised-draft/figures/installation-workflow-overview.png new file mode 100644 index 0000000000..c7540c4a1a Binary files /dev/null and b/doc/source/install-guide-revised-draft/figures/installation-workflow-overview.png differ diff --git a/doc/source/install-guide-revised-draft/figures/installation-workflow-run-playbooks.png b/doc/source/install-guide-revised-draft/figures/installation-workflow-run-playbooks.png new file mode 100644 index 0000000000..cedc8c1574 Binary files /dev/null and b/doc/source/install-guide-revised-draft/figures/installation-workflow-run-playbooks.png differ diff --git a/doc/source/install-guide-revised-draft/figures/installation-workflow-verify-openstack.png b/doc/source/install-guide-revised-draft/figures/installation-workflow-verify-openstack.png new file mode 100644 index 0000000000..8fd49e0afb Binary files /dev/null and b/doc/source/install-guide-revised-draft/figures/installation-workflow-verify-openstack.png differ diff --git a/doc/source/install-guide-revised-draft/figures/installation-workflow.graffle b/doc/source/install-guide-revised-draft/figures/installation-workflow.graffle new file mode 100644 index 0000000000..dc44be71c3 Binary files /dev/null and b/doc/source/install-guide-revised-draft/figures/installation-workflow.graffle differ diff --git a/doc/source/install-guide-revised-draft/index.rst b/doc/source/install-guide-revised-draft/index.rst index c6b7266a70..d661885c26 100644 --- a/doc/source/install-guide-revised-draft/index.rst +++ b/doc/source/install-guide-revised-draft/index.rst @@ -17,5 +17,5 @@ Table of Contents deploymenthost.rst targethosts.rst configure.rst - install.rst + installation.rst app.rst diff --git a/doc/source/install-guide-revised-draft/install-foundation.rst b/doc/source/install-guide-revised-draft/install-foundation.rst deleted file mode 100644 index 524e7f68a5..0000000000 --- a/doc/source/install-guide-revised-draft/install-foundation.rst +++ /dev/null @@ -1,77 +0,0 @@ -`Home `_ OpenStack-Ansible Installation Guide - -==================== -Foundation playbooks -==================== - -**Figure 5.1. Installation work flow** - -.. image:: figures/workflow-foundationplaybooks.png - -The main Ansible foundation playbook prepares the target hosts for -infrastructure and OpenStack services and performs the following -operations: - -- Performs deployment host initial setup - -- Builds containers on target hosts - -- Restarts containers on target hosts - -- Installs common components into containers on target hosts - -Running the foundation playbook -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - Before continuing, validate the configuration files using the - guidance in `Checking the integrity of your configuration files`_. - - .. _Checking the integrity of your configuration files: ../install-guide/configure-configurationintegrity.html - -#. Change to the ``/opt/openstack-ansible/playbooks`` directory. - -#. Run the host setup playbook: - - .. code-block:: shell-session - - # openstack-ansible setup-hosts.yml - - Confirm satisfactory completion with zero items unreachable or - failed: - - .. code-block:: shell-session - - PLAY RECAP ******************************************************************** - ... - deployment_host : ok=18 changed=11 unreachable=0 failed=0 - -#. If using HAProxy: - - .. note:: - - To run HAProxy on multiple hosts, use ``keepalived`` to make HAProxy highly - available. The keepalived role downloads during the ``bootstrap-ansible`` stage. - If not, re-run the following command before running the HAProxy playbook: - - .. code-block:: shell-session - - # pushd /opt/openstack-ansible; scripts/bootstrap-ansible.sh; popd - - or - - .. code-block:: shell-session - - # ansible-galaxy install -r ../ansible-role-requirements.yml - - Run the playbook to deploy HAProxy: - - .. code-block:: shell-session - - # openstack-ansible haproxy-install.yml - - --------------- - -.. include:: navigation.txt diff --git a/doc/source/install-guide-revised-draft/install-infrastructure.rst b/doc/source/install-guide-revised-draft/install-infrastructure.rst deleted file mode 100644 index 1cb0c9eece..0000000000 --- a/doc/source/install-guide-revised-draft/install-infrastructure.rst +++ /dev/null @@ -1,96 +0,0 @@ -`Home `_ OpenStack-Ansible Installation Guide - -======================== -Infrastructure playbooks -======================== - -**Figure 6.1. Installation workflow** - -.. image:: figures/workflow-infraplaybooks.png - -The main Ansible infrastructure playbook installs infrastructure -services and performs the following operations: - -- Installs Memcached - -- Installs the repository server - -- Installs Galera - -- Installs RabbitMQ - -- Installs Rsyslog - -- Configures Rsyslog - -Running the infrastructure playbook -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - Before continuing, validate the configuration files using the - guidance in `Checking the integrity of your configuration files`_. - -.. _Checking the integrity of your configuration files: ../install-guide/configure-configurationintegrity.html - -#. Change to the ``/opt/openstack-ansible/playbooks`` directory. - -#. Run the infrastructure setup playbook: - - .. code-block:: shell-session - - # openstack-ansible setup-infrastructure.yml - - Confirm satisfactory completion with zero items unreachable or - failed: - - .. code-block:: shell-session - - PLAY RECAP ******************************************************************** - ... - deployment_host : ok=27 changed=0 unreachable=0 failed=0 - -Verify the database cluster -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -#. Change to the ``/opt/openstack-ansible/playbooks`` directory. - -#. Execute the following command to show the current cluster state: - - .. code-block:: shell-session - - # ansible galera_container -m shell -a "mysql \ - -h localhost -e 'show status like \"%wsrep_cluster_%\";'" - - Example output: - - .. code-block:: shell-session - - node3_galera_container-3ea2cbd3 | success | rc=0 >> - Variable_name Value - wsrep_cluster_conf_id 17 - wsrep_cluster_size 3 - wsrep_cluster_state_uuid 338b06b0-2948-11e4-9d06-bef42f6c52f1 - wsrep_cluster_status Primary - - node2_galera_container-49a47d25 | success | rc=0 >> - Variable_name Value - wsrep_cluster_conf_id 17 - wsrep_cluster_size 3 - wsrep_cluster_state_uuid 338b06b0-2948-11e4-9d06-bef42f6c52f1 - wsrep_cluster_status Primary - - node4_galera_container-76275635 | success | rc=0 >> - Variable_name Value - wsrep_cluster_conf_id 17 - wsrep_cluster_size 3 - wsrep_cluster_state_uuid 338b06b0-2948-11e4-9d06-bef42f6c52f1 - wsrep_cluster_status Primary - - The ``wsrep_cluster_size`` field indicates the number of nodes - in the cluster and the ``wsrep_cluster_status`` field indicates - primary. - --------------- - -.. include:: navigation.txt diff --git a/doc/source/install-guide-revised-draft/install-openstack.rst b/doc/source/install-guide-revised-draft/install-openstack.rst deleted file mode 100644 index 8b5d142ebc..0000000000 --- a/doc/source/install-guide-revised-draft/install-openstack.rst +++ /dev/null @@ -1,132 +0,0 @@ -`Home `_ OpenStack-Ansible Installation Guide - -=================== -OpenStack playbooks -=================== - -**Figure 7.1. Installation work flow** - -.. image:: figures/workflow-openstackplaybooks.png - -The ``setup-openstack.yml`` playbook installs OpenStack services and -performs the following operations: - -- Installs Identity (keystone) - -- Installs the Image service (glance) - -- Installs Block Storage (cinder) - -- Installs Compute (nova) - -- Installs Networking (neutron) - -- Installs Orchestration (heat) - -- Installs Dashboard (horizon) - -- Installs Telemetry (ceilometer and aodh) - -- Installs Object Storage (swift) - -- Installs Ironic - -Running the OpenStack playbook -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -#. Change to the ``/opt/openstack-ansible/playbooks`` directory. - -#. Run the OpenStack setup playbook: - - .. code-block:: shell-session - - # openstack-ansible setup-openstack.yml - - Confirm satisfactory completion with zero items unreachable or - failed. - -Utility container -~~~~~~~~~~~~~~~~~ - -The utility container provides a space where miscellaneous tools and -software are installed. Tools and objects are placed in a -utility container if they do not require a dedicated container or if it -is impractical to create a new container for a single tool or object. -Utility containers are also used when tools cannot be installed -directly onto a host. - -For example, the tempest playbooks are installed on the utility -container since tempest testing does not need a container of its own. - -Verifying OpenStack operation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Verify basic operation of the OpenStack API and dashboard. - -**Procedure 8.1. Verifying the API** - -The utility container provides a CLI environment for additional -configuration and testing. - -#. Determine the utility container name: - - .. code-block:: shell-session - - # lxc-ls | grep utility - infra1_utility_container-161a4084 - -#. Access the utility container: - - .. code-block:: shell-session - - # lxc-attach -n infra1_utility_container-161a4084 - -#. Source the ``admin`` tenant credentials: - - .. code-block:: shell-session - - # source /root/openrc - -#. Run an OpenStack command that uses one or more APIs. For example: - - .. code-block:: shell-session - - # openstack user list - +----------------------------------+--------------------+ - | ID | Name | - +----------------------------------+--------------------+ - | 08fe5eeeae314d578bba0e47e7884f3a | alt_demo | - | 0aa10040555e47c09a30d2240e474467 | dispersion | - | 10d028f9e47b4d1c868410c977abc3df | glance | - | 249f9ad93c024f739a17ca30a96ff8ee | demo | - | 39c07b47ee8a47bc9f9214dca4435461 | swift | - | 3e88edbf46534173bc4fd8895fa4c364 | cinder | - | 41bef7daf95a4e72af0986ec0583c5f4 | neutron | - | 4f89276ee4304a3d825d07b5de0f4306 | admin | - | 943a97a249894e72887aae9976ca8a5e | nova | - | ab4f0be01dd04170965677e53833e3c3 | stack_domain_admin | - | ac74be67a0564722b847f54357c10b29 | heat | - | b6b1d5e76bc543cda645fa8e778dff01 | ceilometer | - | dc001a09283a404191ff48eb41f0ffc4 | aodh | - | e59e4379730b41209f036bbeac51b181 | keystone | - +----------------------------------+--------------------+ - -**Procedure 8.2. Verifying the dashboard** - -#. With a web browser, access the dashboard using the external load - balancer IP address defined by the ``external_lb_vip_address`` option - in the ``/etc/openstack_deploy/openstack_user_config.yml`` file. The - dashboard uses HTTPS on port 443. - -#. Authenticate using the username ``admin`` and password defined by the - ``keystone_auth_admin_password`` option in the - ``/etc/openstack_deploy/user_variables.yml`` file. - -.. note:: - - Only users with administrator privileges can upload public images - using the dashboard or CLI. - --------------- - -.. include:: navigation.txt diff --git a/doc/source/install-guide-revised-draft/install.rst b/doc/source/install-guide-revised-draft/install.rst deleted file mode 100644 index 9d9e7b5112..0000000000 --- a/doc/source/install-guide-revised-draft/install.rst +++ /dev/null @@ -1,11 +0,0 @@ -============ -Installation -============ -`Home `_ OpenStack-Ansible Installation Guide - -.. toctree:: - :maxdepth: 2 - - install-foundation.rst - install-infrastructure.rst - install-openstack.rst diff --git a/doc/source/install-guide-revised-draft/installation.rst b/doc/source/install-guide-revised-draft/installation.rst new file mode 100644 index 0000000000..ac570bfd78 --- /dev/null +++ b/doc/source/install-guide-revised-draft/installation.rst @@ -0,0 +1,205 @@ +`Home `_ OpenStack-Ansible Installation Guide + +============ +Installation +============ + +The installation process requires running three main playbooks: + +- The ``setup-hosts.yml`` Ansible foundation playbook prepares the target + hosts for infrastructure and OpenStack services, builds and restarts + containers on target hosts, and installs common components into containers + on target hosts. + +- The ``setup-infrastructure.yml`` Ansible infrastructure playbook installs + infrastructure services: memcached, the repository server, Galera, RabbitMQ, + Rsyslog, and configures Rsyslog. + +- The ``setup-openstack.yml`` OpenStack playbook installs OpenStack services, + including the Identity service (keystone), Image service (glance), + Block Storage (cinder), Compute service (nova), OpenStack Networking + (neutron), Orchestration (heat), Dashboard (horizon), Telemetry service + (ceilometer and aodh), Object Storage service (swift), and OpenStack + bare metal provisioning (ironic). + +Installation process +~~~~~~~~~~~~~~~~~~~~ + +.. figure:: figures/installation-workflow-run-playbooks.png + :scale: 100 + + +.. note:: + + Before continuing, validate the configuration files using the + guidance in `Checking the integrity of your configuration files`_. + + .. _Checking the integrity of your configuration files: ../install-guide/configure-configurationintegrity.html + +#. Change to the ``/opt/openstack-ansible/playbooks`` directory. + +#. Run the host setup playbook: + + .. code-block:: console + + # openstack-ansible setup-hosts.yml + + Confirm satisfactory completion with zero items unreachable or + failed: + + .. code-block:: console + + PLAY RECAP ******************************************************************** + ... + deployment_host : ok=18 changed=11 unreachable=0 failed=0 + + +#. Run the infrastructure setup playbook: + + .. code-block:: console + + # openstack-ansible setup-infrastructure.yml + + Confirm satisfactory completion with zero items unreachable or + failed: + + .. code-block:: console + + PLAY RECAP ******************************************************************** + ... + deployment_host : ok=27 changed=0 unreachable=0 failed=0 + + +#. Run the following command to verify the database cluster: + + .. code-block:: console + + # ansible galera_container -m shell -a "mysql \ + -h localhost -e 'show status like \"%wsrep_cluster_%\";'" + + Example output: + + .. code-block:: console + + node3_galera_container-3ea2cbd3 | success | rc=0 >> + Variable_name Value + wsrep_cluster_conf_id 17 + wsrep_cluster_size 3 + wsrep_cluster_state_uuid 338b06b0-2948-11e4-9d06-bef42f6c52f1 + wsrep_cluster_status Primary + + node2_galera_container-49a47d25 | success | rc=0 >> + Variable_name Value + wsrep_cluster_conf_id 17 + wsrep_cluster_size 3 + wsrep_cluster_state_uuid 338b06b0-2948-11e4-9d06-bef42f6c52f1 + wsrep_cluster_status Primary + + node4_galera_container-76275635 | success | rc=0 >> + Variable_name Value + wsrep_cluster_conf_id 17 + wsrep_cluster_size 3 + wsrep_cluster_state_uuid 338b06b0-2948-11e4-9d06-bef42f6c52f1 + wsrep_cluster_status Primary + + The ``wsrep_cluster_size`` field indicates the number of nodes + in the cluster and the ``wsrep_cluster_status`` field indicates + primary. + +#. Run the OpenStack setup playbook: + + .. code-block:: console + + # openstack-ansible setup-openstack.yml + + Confirm satisfactory completion with zero items unreachable or + failed. + +Utility container +~~~~~~~~~~~~~~~~~ + +The utility container provides a space where miscellaneous tools and +software are installed. Tools and objects are placed in a +utility container if they do not require a dedicated container or if it +is impractical to create a new container for a single tool or object. +Utility containers are also used when tools cannot be installed +directly onto a host. + +For example, the tempest playbooks are installed on the utility +container since tempest testing does not need a container of its own. + +Verifying OpenStack operation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: figures/installation-workflow-verify-openstack.png + :scale: 100 + + +.. TODO Add procedures to test different layers of the OpenStack environment + +Verify basic operation of the OpenStack API and dashboard. + +**Verifying the API** + +The utility container provides a CLI environment for additional +configuration and testing. + +#. Determine the utility container name: + + .. code-block:: console + + # lxc-ls | grep utility + infra1_utility_container-161a4084 + +#. Access the utility container: + + .. code-block:: console + + # lxc-attach -n infra1_utility_container-161a4084 + +#. Source the ``admin`` tenant credentials: + + .. code-block:: console + + # source /root/openrc + +#. Run an OpenStack command that uses one or more APIs. For example: + + .. code-block:: console + + # openstack user list + +----------------------------------+--------------------+ + | ID | Name | + +----------------------------------+--------------------+ + | 08fe5eeeae314d578bba0e47e7884f3a | alt_demo | + | 0aa10040555e47c09a30d2240e474467 | dispersion | + | 10d028f9e47b4d1c868410c977abc3df | glance | + | 249f9ad93c024f739a17ca30a96ff8ee | demo | + | 39c07b47ee8a47bc9f9214dca4435461 | swift | + | 3e88edbf46534173bc4fd8895fa4c364 | cinder | + | 41bef7daf95a4e72af0986ec0583c5f4 | neutron | + | 4f89276ee4304a3d825d07b5de0f4306 | admin | + | 943a97a249894e72887aae9976ca8a5e | nova | + | ab4f0be01dd04170965677e53833e3c3 | stack_domain_admin | + | ac74be67a0564722b847f54357c10b29 | heat | + | b6b1d5e76bc543cda645fa8e778dff01 | ceilometer | + | dc001a09283a404191ff48eb41f0ffc4 | aodh | + | e59e4379730b41209f036bbeac51b181 | keystone | + +----------------------------------+--------------------+ + +**Verifying the dashboard** + +#. With a web browser, access the dashboard using the external load + balancer IP address defined by the ``external_lb_vip_address`` option + in the ``/etc/openstack_deploy/openstack_user_config.yml`` file. The + dashboard uses HTTPS on port 443. + +#. Authenticate using the username ``admin`` and password defined by the + ``keystone_auth_admin_password`` option in the + ``/etc/openstack_deploy/user_variables.yml`` file. + +.. TODO Add troubleshooting information to resolve common installation issues + +-------------- + +.. include:: navigation.txt diff --git a/doc/source/install-guide-revised-draft/overview-workflow.rst b/doc/source/install-guide-revised-draft/overview-workflow.rst index 58a25badb3..dca01972bc 100644 --- a/doc/source/install-guide-revised-draft/overview-workflow.rst +++ b/doc/source/install-guide-revised-draft/overview-workflow.rst @@ -8,16 +8,16 @@ This diagram shows the general workflow associated with an OpenStack-Ansible (OSA) installation. -**Figure 1.7. Installation workflow** +.. figure:: figures/installation-workflow-overview.png + :scale: 100 -.. image:: figures/workflow-overview.png + Installation workflow -#. :doc:`Prepare deployment hosts ` +#. :doc:`Prepare deployment host ` #. :doc:`Prepare target hosts ` #. :doc:`Configure deployment ` -#. :doc:`Run foundation playbooks ` -#. :doc:`Run infrastructure playbooks ` -#. :doc:`Run OpenStack playbooks ` +#. :doc:`Run playbooks ` +#. :doc:`Verify OpenStack operation ` =======