openstack/openstack-ansible
Code Issues Proposed changes

[Docs] Simplify overview page

Browse Source 
This modifies the overview section to be one page instead of
4 long sections. We just refer to the architecture reference
for details about the architecture.

Change-Id: I1f5da9acaa677b2cd752cda30c33eba846a96eb4
This commit is contained in:
Jean-Philippe Evrard 2018-03-12 18:13:30 +00:00
parent 0e2120bba7
commit 8bfc32399e
10 changed files with 161 additions and 210 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
deploy-guide/source/overview-osa.rst → deploy-guide/source/app-aboutosa.rst
View File

@ -1,3 +1,5 @@
.. _app-aboutosa:
=======================
About OpenStack-Ansible
=======================
@ -52,47 +54,3 @@ 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 <http://docs.ansible.com/playbooks_intro.html>`_.
This guide refers to the following types of hosts:
* `Deployment host`, which runs the Ansible playbooks
* `Target hosts`, where Ansible installs OpenStack services and infrastructure
components
Linux containers (LXC)
~~~~~~~~~~~~~~~~~~~~~~
Containers provide operating-system level virtualization by enhancing
the concept of ``chroot`` environments. Containers isolate resources and file
systems for a particular group of processes without the overhead and
complexity of virtual machines. They access the same kernel, devices,
and file systems on the underlying host and provide a thin operational
layer built around a set of rules.
The LXC project implements operating-system-level
virtualization on Linux by using kernel namespaces, and it includes the
following features:
* Resource isolation including CPU, memory, block I/O, and network, by
using ``cgroups``
* Selective connectivity to physical and virtual network devices on the
underlying physical host
* Support for a variety of backing stores, including Logical Volume Manager
(LVM)
* Built on a foundation of stable Linux technologies with an active
development and support community
Installation workflow
~~~~~~~~~~~~~~~~~~~~~
The following diagram shows the general workflow of an OpenStack-Ansible
installation.
.. figure:: figures/installation-workflow-overview.png
:width: 100%
#. :ref:`deployment-host`
#. :ref:`target-hosts`
#. :ref:`configure`
#. :ref:`run-playbooks`
#. :ref:`verify-operation`

1
deploy-guide/source/app.rst
View File

@ -6,3 +6,4 @@ Appendices
:maxdepth: 2
app-resources.rst
app-aboutosa.rst

87
deploy-guide/source/overview-network-arch.rst
View File

@ -1,87 +0,0 @@
.. _network-architecture:
====================
Network architecture
====================
Although Ansible automates most deployment operations, networking on target
hosts requires manual configuration because it varies from one use case to
another. This section describes the network configuration that must be
implemented on all target hosts.
For more information about how networking works, see the
:dev_docs:`OpenStack-Ansible Reference Architecture, section Container
Networking <reference/architecture/index.html>`.
Host network bridges
~~~~~~~~~~~~~~~~~~~~
OpenStack-Ansible uses bridges to connect physical and logical network
interfaces on the host to virtual network interfaces within containers.
Target hosts are configured with the following network bridges.
* LXC internal: ``lxcbr0``
The ``lxcbr0`` bridge is **required**, but OpenStack-Ansible configures it
automatically. It provides external (typically Internet) connectivity to
containers.
This bridge does not directly attach to any physical or logical
interfaces on the host because iptables handles connectivity. It
attaches to ``eth0`` in each container.
The container network that the bridge attaches to is configurable in the
``openstack_user_config.yml`` file in the ``provider_networks``
dictionary.
* Container management: ``br-mgmt``
The ``br-mgmt`` bridge is **required**. It provides management of and
communication between the infrastructure and OpenStack services.
The bridge attaches to a physical or logical interface, typically a
``bond0`` VLAN subinterface. It also attaches to ``eth1`` in each container.
The container network interface that the bridge attaches to is configurable
in the ``openstack_user_config.yml`` file.
* Storage:``br-storage``
The ``br-storage`` bridge is **optional**, but recommended for production
environments. It provides segregated access to Block Storage devices
between OpenStack services and Block Storage devices.
The bridge attaches to a physical or logical interface, typically a
``bond0`` VLAN subinterface. It also attaches to ``eth2`` in each
associated container.
The container network interface that the bridge attaches to is configurable
in the ``openstack_user_config.yml`` file.
* OpenStack Networking tunnel: ``br-vxlan``
The ``br-vxlan`` bridge is **required** if the environment is configured to
allow projects to create virtual networks. It provides the interface for
virtual (VXLAN) tunnel networks.
The bridge attaches to a physical or logical interface, typically a
``bond1`` VLAN subinterface. It also attaches to ``eth10`` in each
associated container.
The container network interface it attaches to is configurable in
the ``openstack_user_config.yml`` file.
* OpenStack Networking provider: ``br-vlan``
The ``br-vlan`` bridge is **required**. It provides infrastructure for VLAN
tagged or flat (no VLAN tag) networks.
The bridge attaches to a physical or logical interface, typically ``bond1``.
It attaches to ``eth11`` for VLAN type networks in each associated
container. It is not assigned an IP address because it handles only
layer 2 connectivity.
The container network interface that the bridge attaches to is configurable
in the ``openstack_user_config.yml`` file.

82
deploy-guide/source/overview-requirements.rst
View File

@ -1,10 +1,3 @@
=============================================
Installation requirements and recommendations
=============================================
This section describes software requirements, hardware recommendations, and
network recommendations for running OpenStack in a production environment.
Software requirements
~~~~~~~~~~~~~~~~~~~~~
@ -54,60 +47,79 @@ CPU recommendations
.. _hardware-assisted virtualization extensions: https://en.wikipedia.org/wiki/Hardware-assisted_virtualization
.. _Hyper-threading: https://en.wikipedia.org/wiki/Hyper-threading
Disk recommendations
~~~~~~~~~~~~~~~~~~~~
Storage/disk recommendations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Different hosts have different disk space requirements based on the
services running on each host:
Deployment hosts
A minimum of ``10 GB`` of disk space is sufficient for holding the
OpenStack-Ansible repository content and additional required software.
----------------
A minimum of ``10 GB`` of disk space is sufficient for holding the
OpenStack-Ansible repository content and additional required software.
Compute hosts
Disk space requirements depend on the total number of instances
running on each host and the amount of disk space allocated to each instance.
-------------
* Compute hosts must have a minimum of ``1 TB`` of disk space available.
Disk space requirements depend on the total number of instances
running on each host and the amount of disk space allocated to each instance.
* Consider disks that provide higher I/O throughput with lower latency,
such as SSD drives in a RAID array.
.. tip ::
Consider disks that provide higher I/O throughput with lower latency,
such as SSD drives in a RAID array.
Storage hosts
Hosts running the Block Storage (cinder) service often consume the most disk
space in OpenStack environments.
-------------
* Storage hosts must have a minimum of ``1 TB`` of disk space.
Hosts running the Block Storage (cinder) service often consume the most disk
space in OpenStack environments.
* As with Compute hosts, choose disks that provide the highest
I/O throughput with the lowest latency.
Storage hosts must have a minimum of ``1 TB`` of disk space.
Infrastructure (control plane) hosts
The OpenStack control plane contains storage-intensive services, such as the
Image service (glance), and MariaDB. These hosts must have a minimum of
``100 GB`` of disk space.
.. tip ::
Logging hosts
An OpenStack-Ansible deployment generates a significant amount of log
information. Logs come from a variety of sources, including services running
in containers, the containers themselves, and the physical hosts. Logging
hosts need sufficient disk space to hold live and rotated (historical) log
files. In addition, the storage performance must be able to keep pace with
the log traffic coming from various hosts and containers within the OpenStack
environment. Reserve a minimum of ``50 GB`` of disk space for storing logs on
the logging hosts.
As with Compute hosts, choose disks that provide the highest
I/O throughput with the lowest latency.
Hosts that provide Block Storage volumes must have Logical Volume
Manager (LVM) support. Ensure that hosts have a ``cinder-volume`` volume
group that OpenStack-Ansible can configure for use with Block Storage.
Each infrastructure (control plane) host runs services inside LXC containers.
Infrastructure (control plane) hosts
------------------------------------
The OpenStack control plane contains storage-intensive services, such as the
Image service (glance), and MariaDB. These hosts must have a minimum of
``100 GB`` of disk space.
Each infrastructure (control plane) host runs services inside machine containers.
The container file systems are deployed by default on the root file system of
each control plane host. You have the option to deploy those container file
systems into logical volumes by creating a volume group called lxc.
OpenStack-Ansible creates a 5 GB logical volume for the file system of each
container running on the host.
.. tip ::
Other technologies leveraging copy-on-write can be used to reduce
the disk space requirements on machine containers.
Logging hosts
-------------
An OpenStack-Ansible deployment generates a significant amount of log
information. Logs come from a variety of sources, including services running
in containers, the containers themselves, and the physical hosts. Logging
hosts need sufficient disk space to hold live and rotated (historical) log
files. In addition, the storage performance must be able to keep pace with
the log traffic coming from various hosts and containers within the OpenStack
environment. Reserve a minimum of ``50 GB`` of disk space for storing logs on
the logging hosts.
Network recommendations
~~~~~~~~~~~~~~~~~~~~~~~

34
deploy-guide/source/overview.rst
View File

@ -2,10 +2,32 @@
Overview
========
.. toctree::
.. note::
overview-osa.rst
overview-requirements.rst
overview-service-architecture.rst
overview-network-arch.rst
overview-storage-arch.rst
For essential background reading to help understand the service and storage
architecture, please read
`OpenStack-Ansible Architecture in its reference guide
<https://docs.openstack.org/openstack-ansible/latest/reference/architecture/index.html>`_
If you'd like to understand when OpenStack-Ansible would be a good fit for your
organisation, please read the appendix
":ref:`app-aboutosa`".
This guide refers to the following types of hosts:
* `Deployment host`, which runs the Ansible playbooks
* `Target hosts`, where Ansible installs OpenStack services and infrastructure
components
Installation workflow
=====================
The following diagram shows the general workflow of an OpenStack-Ansible
installation.
.. figure:: figures/installation-workflow-overview.png
:width: 100%
Installation requirements and recommendations
=============================================
.. include:: overview-requirements.rst

74
deploy-guide/source/targethosts-networkconfig.rst
View File

@ -29,3 +29,77 @@ Networking <reference/architecture/index.html>`.
For use case examples, refer to
:dev_docs:`User Guides <user/index.html>`.
Host network bridges
~~~~~~~~~~~~~~~~~~~~
OpenStack-Ansible uses bridges to connect physical and logical network
interfaces on the host to virtual network interfaces within containers.
Target hosts are configured with the following network bridges.
* LXC internal: ``lxcbr0``
The ``lxcbr0`` bridge is **required**, but OpenStack-Ansible configures it
automatically. It provides external (typically Internet) connectivity to
containers.
This bridge does not directly attach to any physical or logical
interfaces on the host because iptables handles connectivity. It
attaches to ``eth0`` in each container.
The container network that the bridge attaches to is configurable in the
``openstack_user_config.yml`` file in the ``provider_networks``
dictionary.
* Container management: ``br-mgmt``
The ``br-mgmt`` bridge is **required**. It provides management of and
communication between the infrastructure and OpenStack services.
The bridge attaches to a physical or logical interface, typically a
``bond0`` VLAN subinterface. It also attaches to ``eth1`` in each container.
The container network interface that the bridge attaches to is configurable
in the ``openstack_user_config.yml`` file.
* Storage:``br-storage``
The ``br-storage`` bridge is **optional**, but recommended for production
environments. It provides segregated access to Block Storage devices
between OpenStack services and Block Storage devices.
The bridge attaches to a physical or logical interface, typically a
``bond0`` VLAN subinterface. It also attaches to ``eth2`` in each
associated container.
The container network interface that the bridge attaches to is configurable
in the ``openstack_user_config.yml`` file.
* OpenStack Networking tunnel: ``br-vxlan``
The ``br-vxlan`` bridge is **required** if the environment is configured to
allow projects to create virtual networks. It provides the interface for
virtual (VXLAN) tunnel networks.
The bridge attaches to a physical or logical interface, typically a
``bond1`` VLAN subinterface. It also attaches to ``eth10`` in each
associated container.
The container network interface it attaches to is configurable in
the ``openstack_user_config.yml`` file.
* OpenStack Networking provider: ``br-vlan``
The ``br-vlan`` bridge is **required**. It provides infrastructure for VLAN
tagged or flat (no VLAN tag) networks.
The bridge attaches to a physical or logical interface, typically ``bond1``.
It attaches to ``eth11`` for VLAN type networks in each associated
container. It is not assigned an IP address because it handles only
layer 2 connectivity.
The container network interface that the bridge attaches to is configurable
in the ``openstack_user_config.yml`` file.

1
doc/source/reference/architecture/container-networking.rst
View File

@ -1,6 +1,5 @@
.. _container-networking:
====================
Container networking
====================

3
doc/source/reference/architecture/index.rst
View File

@ -11,5 +11,8 @@ was architected in this way.
.. toctree::
:maxdepth: 1
service-arch.rst
storage-arch.rst
security.rst
container-networking.rst

41
deploy-guide/source/overview-service-architecture.rst → doc/source/reference/architecture/service-arch.rst
View File

@ -1,14 +1,12 @@
.. _service-architecture:
====================
Service architecture
====================
Introduction
~~~~~~~~~~~~
OpenStack-Ansible has a flexible deployment configuration model that
can deploy all services in separate LXC containers or on designated hosts
without using LXC containers, and all network traffic either on a single
can deploy all services in separate machine containers or on designated hosts
without using containers, and all network traffic either on a single
network interface or on many network interfaces.
This flexibility enables deployers to choose how to deploy OpenStack in the
@ -90,33 +88,6 @@ OpenStack-Ansible deploys the following infrastructure components:
OpenStack services
~~~~~~~~~~~~~~~~~~
OSA is able to deploy the following OpenStack services:
* Bare Metal (`ironic`_)
* Block Storage (`cinder`_)
* Compute (`nova`_)
* Container Infrastructure Management (`magnum`_)
* Dashboard (`horizon`_)
* Data Processing (`sahara`_)
* Identity (`keystone`_)
* Image (`glance`_)
* Networking (`neutron`_)
* Object Storage (`swift`_)
* Orchestration (`heat`_)
* Telemetry (`aodh`_, `ceilometer`_, `gnocchi`_)
.. _ironic: http://docs.openstack.org/developer/ironic
.. _cinder: http://docs.openstack.org/developer/cinder
.. _nova: http://docs.openstack.org/developer/nova
.. _magnum: http://docs.openstack.org/developer/magnum
.. _horizon: http://docs.openstack.org/developer/horizon
.. _sahara: http://docs.openstack.org/developer/sahara
.. _keystone: http://docs.openstack.org/developer/keystone
.. _glance: http://docs.openstack.org/developer/glance
.. _neutron: http://docs.openstack.org/developer/neutron
.. _swift: http://docs.openstack.org/developer/swift
.. _heat: http://docs.openstack.org/developer/heat
.. _aodh: http://docs.openstack.org/developer/aodh
.. _ceilometer: http://docs.openstack.org/developer/ceilometer
.. _gnocchi: http://docs.openstack.org/developer/gnocchi
OSA is able to deploy a multitude of services.
Have a look at the role maturity matrix to know the status of the
service you want to deploy.

2
deploy-guide/source/overview-storage-arch.rst → doc/source/reference/architecture/storage-arch.rst
View File

@ -1,4 +1,3 @@
====================
Storage architecture
====================
@ -164,4 +163,3 @@ the storage device, the Compute host, the hypervisor, and the instance.
+----+---------------------------------------------------------------------+
| 3 | The hypervisor presents the disk as a device to the instance. |
+----+---------------------------------------------------------------------+