diff --git a/doc/source/install-guide/overview-hostlayout.rst b/doc/source/install-guide/overview-hostlayout.rst index b07b925111..91cc4b7d84 100644 --- a/doc/source/install-guide/overview-hostlayout.rst +++ b/doc/source/install-guide/overview-hostlayout.rst @@ -1,9 +1,10 @@ `Home `_ OpenStack-Ansible Installation Guide +=========== Host layout ------------ +=========== -The recommended layout contains a minimum of five hosts (or servers). +We recommend a layout that contains a minimum of five hosts (or servers): - Three control plane infrastructure hosts @@ -11,22 +12,21 @@ The recommended layout contains a minimum of five hosts (or servers). - One compute host -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 +If using the optional Block Storage (cinder) service, we recommend +the use of a sixth host. 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. -The hosts are called *target hosts* because Ansible deploys the OSA -environment within these hosts. The OSA environment also recommends a -*deployment host* from which Ansible orchestrates the deployment +The hosts are called target hosts because Ansible deploys the OSA +environment within these hosts. We recommend a +deployment host from which Ansible orchestrates the deployment process. One of the target hosts can function as the deployment host. -At least one load balancer **must** be used to manage the traffic among -the target hosts. This can be any type of load balancer (hardware, haproxy, -etc). While OpenStack-Ansible has playbooks and roles for deploying haproxy, -we recommend for deployers to use physical load balancers when moving to -production. +Use at least one load balancer to manage the traffic among +the target hosts. You can use any type of load balancer such as a hardware +appliance or HAProxy. We recommend using physical load balancers for +production environments. Infrastructure Control Plane target hosts contain the following services: diff --git a/doc/source/install-guide/overview-osa.rst b/doc/source/install-guide/overview-osa.rst index fb302bfd2b..f6c1b13e6f 100644 --- a/doc/source/install-guide/overview-osa.rst +++ b/doc/source/install-guide/overview-osa.rst @@ -1,21 +1,21 @@ `Home `_ OpenStack-Ansible Installation Guide +======================= About OpenStack-Ansible ------------------------ +======================= -OpenStack-Ansible uses the Ansible IT automation framework to +OpenStack-Ansible (OSA) uses the Ansible IT automation framework to deploy an OpenStack environment on Ubuntu Linux. OpenStack components are installed into Linux Containers (LXC) for isolation and ease of maintenance. This documentation is intended for deployers of the OpenStack-Ansible deployment system who are interested in installing an OpenStack environment. -The document is for informational purposes only and is provided "AS IS." Third-party trademarks and tradenames appearing in this document are the property of their respective owners. Such third-party trademarks have been printed in caps or initial caps and are used for referential -purposes only. We do not intend our use or display of other companies" +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. @@ -28,18 +28,18 @@ 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. +Ansible uses playbooks written in the YAML language for orchestration. For more information, see `Ansible - Intro to 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 -*target hosts*. +the deployment host and the hosts on which Ansible installs OSA as the +target hosts. A recommended minimal layout for deployments involves five target hosts in total: three infrastructure hosts, one compute host, and one logging host. All hosts will need at least one networking interface, but -multiple bonded interfaces are recommended. More information on setting up +we recommend multiple bonded 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 @@ -54,7 +54,7 @@ Linux Containers (LXC) ~~~~~~~~~~~~~~~~~~~~~~ Containers provide operating-system level virtualization by enhancing -the concept of **chroot** environments, which isolate resources and file +the concept of ``chroot`` environments, which 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 @@ -65,7 +65,7 @@ virtualization on Linux using kernel namespaces and includes the following features: - Resource isolation including CPU, memory, block I/O, and network - using *cgroups*. + using ``cgroups``. - Selective connectivity to physical and virtual network devices on the underlying physical host. diff --git a/doc/source/install-guide/overview-requirements.rst b/doc/source/install-guide/overview-requirements.rst index 11485ec341..a48e0c9889 100644 --- a/doc/source/install-guide/overview-requirements.rst +++ b/doc/source/install-guide/overview-requirements.rst @@ -1,19 +1,22 @@ `Home `_ OpenStack-Ansible Installation Guide +========================= Installation requirements -------------------------- +========================= -The minimum software requirements for OpenStack-Ansible are well defined, but -hardware requirements will vary based on the size of the OpenStack deployment. +.. note:: + + These are the minimum requirements for OpenStack-Ansible. Larger + deployments require additional resources. CPU requirements ~~~~~~~~~~~~~~~~ -Compute hosts should have multi-core processors that have `hardware-assisted +Compute hosts have multi-core processors that have `hardware-assisted virtualization extensions`_ available. These extensions provide a significant performance boost and improve security in virtualized environments. -Infrastructure hosts should have multi-core processors for the best +Infrastructure hosts have multi-core processors for best performance. Some services, such as MySQL, greatly benefit from additional CPU cores and other technologies, such as `Hyper-threading`_. @@ -23,7 +26,7 @@ cores and other technologies, such as `Hyper-threading`_. Disk requirements ~~~~~~~~~~~~~~~~~ -Different hosts will have different disk space requirements based on the +Different hosts have different disk space requirements based on the services running on each host: Deployment hosts @@ -31,23 +34,23 @@ Deployment hosts repository content and additional required software. Compute hosts - Disk space requirements will vary depending on the total number of instances + Disk space requirements vary depending on the total number of instances running on each host and the amount of disk space allocated to each instance. - Compute hosts should have at least 100GB of disk space available at an - absolute minimum. Deployers should consider disks that provide higher + Compute hosts have at least 100GB of disk space available at an + absolute minimum. Consider disks that provide higher 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. As with compute hosts, deployers should + space in OpenStack environments. As with compute hosts, choose disks that provide the highest I/O throughput with the lowest latency - for storage hosts. Storage hosts should contain 1TB of disk space at a + for storage hosts. Storage hosts contain 1TB of disk space at a minimum. Infrastructure hosts The OpenStack control plane contains storage-intensive services, such as the Image (glance) service as well as MariaDB. These control plane hosts - should have 100GB of disk space available at a minimum. + have 100GB of disk space available at a minimum. Logging hosts An OpenStack-Ansible deployment generates a significant amount of logging. @@ -56,48 +59,50 @@ Logging hosts need additional disk space to hold live and rotated (historical) log files. In addition, the storage performance must be enough to keep pace with the log traffic coming from various hosts and containers within the OpenStack - environment. Deployers should reserve at least 50GB of disk space for storing - logs on the logging hosts, but this minimum will grow as additional hosts are - deployed. + environment. Reserve a minimum of 50GB of disk space for storing + logs on the logging hosts. -Hosts that provide Block Storage (cinder) volumes should have logical volume -manager (LVM) support. Those hosts must have a *cinder-volumes* volume group + +Hosts that provide Block Storage (cinder) volumes must have logical volume +manager (LVM) support. Ensure those hosts have a ``cinder-volumes`` volume group that OpenStack-Ansible can configure for use with cinder. -Each control plane host will run services inside LXC containers. By default, -the container filesystems are deployed onto the root filesystem of each control -plane hosts. Deployers have the option to deploy those container filesystems -into logical volumes by creating a volume group called *lxc*. OpenStack-Ansible -will create a 5GB logical volume for the filesystem of each container running +Each control plane host runs services inside LXC containers. The container +filesystems are deployed by default onto the root filesystem of each control +plane hosts. You have the option to deploy those container filesystems +into logical volumes by creating a volume group called ``lxc``. OpenStack-Ansible +creates a 5GB logical volume for the filesystem of each container running on the host. Network requirements ~~~~~~~~~~~~~~~~~~~~ -It is possible to deploy an OpenStack environment with only one physical -network interface. This works for small environments but it will cause problems -when the environment grows. +.. note:: + + You can deploy an OpenStack environment with only one physical + network interface. This works for small environments, but it can cause + problems when your environment grows. For the best performance, reliability and scalability, deployers should consider a network configuration that contains the following features: * Bonded network interfaces: Increases performance and/or reliability - (dependent on bonding architecture) + (dependent on bonding architecture). * VLAN offloading: Increases performance by adding and removing VLAN tags in - hardware, rather than in the server's main CPU + hardware, rather than in the server's main CPU. * Gigabit or 10 Gigabit Ethernet: Supports higher network speeds, which can also improve storage performance when using the Block Storage (cinder) - service + service. * Jumbo frames: Increases network performance by allowing more data to be sent - in each packet + in each packet. Software requirements ~~~~~~~~~~~~~~~~~~~~~ -All hosts within an OpenStack-Ansible environment must meet the following +Ensure all hosts within an OpenStack-Ansible environment meet the following minimum requirements: * Ubuntu 14.04 LTS (Trusty Tahr) diff --git a/doc/source/install-guide/overview-security.rst b/doc/source/install-guide/overview-security.rst index 7148b89658..a8297dda2c 100644 --- a/doc/source/install-guide/overview-security.rst +++ b/doc/source/install-guide/overview-security.rst @@ -1,14 +1,15 @@ `Home `__ OpenStack-Ansible Installation Guide +======== Security --------- +======== The OpenStack-Ansible project provides several security features for -OpenStack deployments. This section of documentation covers some of those +OpenStack deployments. This section of documentation covers those features and how they can benefit deployers of various sizes. -Security requirements will always differ between deployers. For deployers -that need additional security measures in place, please refer to the official +Security requirements always differ between deployers. If you require +additional security measures, refer to the official `OpenStack Security Guide`_ for additional resources. AppArmor @@ -16,14 +17,14 @@ AppArmor The Linux kernel offers multiple `security modules`_ (LSMs) that that set `mandatory access controls`_ (MAC) on Linux systems. The OpenStack-Ansible -project configures `AppArmor`_, a Linux security module, to provide additional -security on LXC container hosts. AppArmor allows administrators to set -specific limits and policies around what resources a particular application -can access. Any activity outside the allowed policies is denied at the kernel -level. +project configures `AppArmor`_. AppArmor is a Linux security module that +provides additional security on LXC container hosts. AppArmor allows +administrators to set specific limits and policies around what resources a +particular application can access. Any activity outside the allowed policies +is denied at the kernel level. -In OpenStack-Ansible, AppArmor profiles are applied that limit the actions -that each LXC container may take on a system. This is done within the +AppArmor profiles that are applied in OpenStack-Ansible limit the actions +that each LXC container may take on a system. This is done within the `lxc_hosts role`_. .. _security modules: https://en.wikipedia.org/wiki/Linux_Security_Modules @@ -34,9 +35,9 @@ that each LXC container may take on a system. This is done within the Encrypted communication ~~~~~~~~~~~~~~~~~~~~~~~ -Data is encrypted while in transit between some OpenStack services in -OpenStack-Ansible deployments. Not all communication between all services is -currently encrypted. For more details on what traffic is encrypted, and how +While in transit, data is encrypted between some OpenStack services in +OpenStack-Ansible deployments. Not all communication between all services is +encrypted. For more details on what traffic is encrypted, and how to configure SSL certificates, refer to the documentation section titled `Securing services with SSL certificates`_. @@ -46,7 +47,7 @@ Host security hardening ~~~~~~~~~~~~~~~~~~~~~~~ Deployers can apply security hardening to OpenStack infrastructure and compute -hosts using the openstack-ansible-security role. The purpose of the role is to +hosts using the ``openstack-ansible-security`` role. The purpose of the role is to apply as many security configurations as possible without disrupting the operation of an OpenStack deployment. @@ -61,9 +62,9 @@ limit the damage that could be caused if an attacker gained access to a set of credentials. OpenStack-Ansible configures unique username and password combinations for -each service that talks to RabbitMQ and Galera/MariaDB. Each service that +each service that talks to RabbitMQ and Galera/MariaDB. Each service that connects to RabbitMQ uses a separate virtual host for publishing and consuming -messages. The MariaDB users for each service are only granted access to the +messages. The MariaDB users for each service are only granted access to the database(s) that they need to query. .. _principle of least privilege: https://en.wikipedia.org/wiki/Principle_of_least_privilege @@ -74,8 +75,12 @@ Securing network access to OpenStack services ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ OpenStack environments expose many service ports and API endpoints to the -network. **Deployers must limit access to these resources and expose them only -to trusted users and networks.** +network. + +.. note:: + + Deployers must limit access to these resources and expose them only + to trusted users and networks. The resources within an OpenStack environment can be divided into two groups: @@ -98,13 +103,12 @@ The resources within an OpenStack environment can be divided into two groups: * MariaDB * RabbitMQ -Users must be able to access certain public API endpoints, such as the Nova or -Neutron API, to manage instances. Deployers should configure firewalls to allow -access to these services, but that access should be limited to the fewest -networks possible. +To manage instances, you are able to access certain public API endpoints, such as +the Nova or Neutron API. Configure firewalls to limit network access to +these services. -Other services, such as MariaDB and RabbitMQ, **must be segmented away from -direct user access**. Deployers must configure a firewall to only allow +Other services, such as MariaDB and RabbitMQ, must be segmented away from +direct user access. You must configure a firewall to only allow connectivity to these services within the OpenStack environment itself. This reduces an attacker's ability to query or manipulate data in OpenStack's critical database and queuing services, especially if one of these services has diff --git a/doc/source/install-guide/overview-workflow.rst b/doc/source/install-guide/overview-workflow.rst index 4091e6c02e..5487193e39 100644 --- a/doc/source/install-guide/overview-workflow.rst +++ b/doc/source/install-guide/overview-workflow.rst @@ -1,7 +1,8 @@ `Home `_ OpenStack-Ansible Installation Guide +===================== Installation workflow ---------------------- +===================== This diagram shows the general workflow associated with an OpenStack-Ansible (OSA) installation. @@ -23,7 +24,7 @@ OpenStack-Ansible (OSA) installation. Network ranges ~~~~~~~~~~~~~~ -For consistency, the following IP addresses and hostnames will be +For consistency, the following IP addresses and hostnames are referred to in this installation workflow. +-----------------------+-----------------+ diff --git a/doc/source/install-guide/overview.rst b/doc/source/install-guide/overview.rst index d002357422..205166b622 100644 --- a/doc/source/install-guide/overview.rst +++ b/doc/source/install-guide/overview.rst @@ -1,7 +1,8 @@ `Home `_ OpenStack-Ansible Installation Guide +=================== Chapter 1. Overview -------------------- +=================== .. toctree::