From 8bfc32399e0ed5e0af55e65a318819234b709911 Mon Sep 17 00:00:00 2001 From: Jean-Philippe Evrard Date: Mon, 12 Mar 2018 18:13:30 +0000 Subject: [PATCH] [Docs] Simplify overview page 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 --- .../{overview-osa.rst => app-aboutosa.rst} | 46 +--------- deploy-guide/source/app.rst | 1 + deploy-guide/source/overview-network-arch.rst | 87 ------------------- deploy-guide/source/overview-requirements.rst | 82 +++++++++-------- deploy-guide/source/overview.rst | 34 ++++++-- .../source/targethosts-networkconfig.rst | 74 ++++++++++++++++ .../architecture/container-networking.rst | 1 - doc/source/reference/architecture/index.rst | 3 + .../reference/architecture/service-arch.rst | 41 ++------- .../reference/architecture/storage-arch.rst | 2 - 10 files changed, 161 insertions(+), 210 deletions(-) rename deploy-guide/source/{overview-osa.rst => app-aboutosa.rst} (61%) delete mode 100644 deploy-guide/source/overview-network-arch.rst rename deploy-guide/source/overview-service-architecture.rst => doc/source/reference/architecture/service-arch.rst (70%) rename deploy-guide/source/overview-storage-arch.rst => doc/source/reference/architecture/storage-arch.rst (99%) diff --git a/deploy-guide/source/overview-osa.rst b/deploy-guide/source/app-aboutosa.rst similarity index 61% rename from deploy-guide/source/overview-osa.rst rename to deploy-guide/source/app-aboutosa.rst index e803de861f..b64c3f3681 100644 --- a/deploy-guide/source/overview-osa.rst +++ b/deploy-guide/source/app-aboutosa.rst @@ -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 `_. - -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` diff --git a/deploy-guide/source/app.rst b/deploy-guide/source/app.rst index c846febdc7..cea31e3346 100644 --- a/deploy-guide/source/app.rst +++ b/deploy-guide/source/app.rst @@ -6,3 +6,4 @@ Appendices :maxdepth: 2 app-resources.rst + app-aboutosa.rst \ No newline at end of file diff --git a/deploy-guide/source/overview-network-arch.rst b/deploy-guide/source/overview-network-arch.rst deleted file mode 100644 index 14fba89d8c..0000000000 --- a/deploy-guide/source/overview-network-arch.rst +++ /dev/null @@ -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 `. - -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. - diff --git a/deploy-guide/source/overview-requirements.rst b/deploy-guide/source/overview-requirements.rst index a7be773227..7b0f98a98b 100644 --- a/deploy-guide/source/overview-requirements.rst +++ b/deploy-guide/source/overview-requirements.rst @@ -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 ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/deploy-guide/source/overview.rst b/deploy-guide/source/overview.rst index 131e6a5fb1..94538762f2 100644 --- a/deploy-guide/source/overview.rst +++ b/deploy-guide/source/overview.rst @@ -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 + `_ + 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 diff --git a/deploy-guide/source/targethosts-networkconfig.rst b/deploy-guide/source/targethosts-networkconfig.rst index 09493de62d..8aefb452a1 100644 --- a/deploy-guide/source/targethosts-networkconfig.rst +++ b/deploy-guide/source/targethosts-networkconfig.rst @@ -29,3 +29,77 @@ Networking `. For use case examples, refer to :dev_docs:`User Guides `. + + + +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. \ No newline at end of file diff --git a/doc/source/reference/architecture/container-networking.rst b/doc/source/reference/architecture/container-networking.rst index cc45768cd8..43e89446a1 100644 --- a/doc/source/reference/architecture/container-networking.rst +++ b/doc/source/reference/architecture/container-networking.rst @@ -1,6 +1,5 @@ .. _container-networking: -==================== Container networking ==================== diff --git a/doc/source/reference/architecture/index.rst b/doc/source/reference/architecture/index.rst index b285a07e0a..199e18eb97 100644 --- a/doc/source/reference/architecture/index.rst +++ b/doc/source/reference/architecture/index.rst @@ -11,5 +11,8 @@ was architected in this way. .. toctree:: :maxdepth: 1 + service-arch.rst + storage-arch.rst security.rst container-networking.rst + diff --git a/deploy-guide/source/overview-service-architecture.rst b/doc/source/reference/architecture/service-arch.rst similarity index 70% rename from deploy-guide/source/overview-service-architecture.rst rename to doc/source/reference/architecture/service-arch.rst index 099b83b546..8d21ef5382 100644 --- a/deploy-guide/source/overview-service-architecture.rst +++ b/doc/source/reference/architecture/service-arch.rst @@ -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. diff --git a/deploy-guide/source/overview-storage-arch.rst b/doc/source/reference/architecture/storage-arch.rst similarity index 99% rename from deploy-guide/source/overview-storage-arch.rst rename to doc/source/reference/architecture/storage-arch.rst index 51410587ae..6526136487 100644 --- a/deploy-guide/source/overview-storage-arch.rst +++ b/doc/source/reference/architecture/storage-arch.rst @@ -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. | +----+---------------------------------------------------------------------+ -