openstack/openstack-manuals
Code Issues Proposed changes

Inst guide, Basic Env, toc changes

Browse Source 
-Add figures for networking-neutron and networking-nova
instead of links to arch. section.
-Remove hidden toc and includes. Add main toc
for Basic Env. section.
-Remove hidden toc from networking section.
Add toc for networking.
-Consolidate smaller sections under new heading.

Change-Id: Ie75a0edaf76e8bb77da490b421221c56a5808663
Implements: blueprint installguide-liberty
This commit is contained in:
Karen Bradshaw
2015-07-25 13:28:49 -04:00
parent e98fbb41a2
commit bdcedc2480
9 changed files with 406 additions and 395 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
doc/install-guide-rst/source/basic_environment.rst
View File

@@ -9,7 +9,7 @@ Basic environment
to install Kilo, you must use the `Kilo
version <http://docs.openstack.org>`__ of this guide instead.
This chapter explains how to configure each node in the
This section explains how to configure each node in the
:ref:`overview-example-architectures`,
including the two-node architecture with legacy
networking :ref:`figure-legacy-network-hw`
@@ -37,22 +37,165 @@ and three-node architecture with OpenStack Networking
when the service uses SysV Init scripts instead of native systemd
files. This warning can be ignored.
.. include:: basics-prerequisites.rst
.. include:: basics-security.rst
.. include:: basics-networking.rst
.. include:: basics-ntp.rst
.. include:: basics-packages.rst
.. include:: basics-database.rst
.. include:: basics-queue.rst
Before you begin
~~~~~~~~~~~~~~~~
For best performance, we recommend that your environment meets or
exceeds the hardware requirements in
:ref:`figure-neutron-network-hw` or
:ref:`figure-legacy-network-hw`. However, OpenStack does not require a
significant amount of resources and the following minimum requirements
should support a proof-of-concept environment with core services
and several :term:`CirrOS` instances:
- Controller Node: 1 processor, 2 GB memory, and 5 GB storage
- Network Node: 1 processor, 512 MB memory, and 5 GB storage
- Compute Node: 1 processor, 2 GB memory, and 10 GB storage
To minimize clutter and provide more resources for OpenStack, we
recommend a minimal installation of your Linux distribution. Also, we
strongly recommend that you install a 64-bit version of your
distribution on at least the compute node. If you install a 32-bit
version of your distribution on the compute node, attempting to start an
instance using a 64-bit image will fail.
.. note::
A single disk partition on each node works for most basic
installations. However, you should consider
:term:`Logical Volume Manager (LVM)` for installations with
optional services such as Block Storage.
Many users build their test environment on a
:term:`virtual machine (VM)`. The primary benefits of VMs include
the following:
- One physical server can support multiple nodes, each with almost any
number of network interfaces.
- Ability to take periodic "snap shots" throughout the installation
process and "roll back" to a working configuration in the event of a
problem.
However, VMs will reduce performance of your instances, particularly if
your hypervisor and/or processor lacks support for hardware acceleration
of nested VMs.
.. note::
If you choose to install on VMs, make sure your hypervisor permits
:term:`promiscuous mode` and disables MAC address filtering on the
:term:`external network`.
For more information about system requirements, see the `OpenStack
Operations Guide <http://docs.openstack.org/ops/>`_.
Security
~~~~~~~~
OpenStack services support various security methods including password,
policy, and encryption. Additionally, supporting services including the
database server and message broker support at least password security.
To ease the installation process, this guide only covers password
security where applicable. You can create secure passwords manually,
generate them using a tool such as
`pwgen <http://sourceforge.net/projects/pwgen/>`__, or by running the
following command:
.. code-block:: console
$ openssl rand -hex 10
For OpenStack services, this guide uses `SERVICE_PASS` to reference
service account passwords and `SERVICE_DBPASS` to reference database
passwords.
The following table provides a list of services that require passwords
and their associated references in the guide:
.. list-table:: **Passwords**
:widths: 50 60
:header-rows: 1
* - Password name
- Description
* - Database password (no variable used)
- Root password for the database
* - `ADMIN_PASS`
- Password of user ``admin``
* - `CEILOMETER_DBPASS`
- Database password for the Telemetry service
* - `CEILOMETER_PASS`
- Password of Telemetry service user ``ceilometer``
* - `CINDER_DBPASS`
- Database password for the Block Storage service
* - `CINDER_PASS`
- Password of Block Storage service user ``cinder``
* - `DASH_DBPASS`
- Database password for the dashboard
* - `DEMO_PASS`
- Password of user ``demo``
* - `GLANCE_DBPASS`
- Database password for Image service
* - `GLANCE_PASS`
- Password of Image service user ``glance``
* - `HEAT_DBPASS`
- Database password for the Orchestration service
* - `HEAT_DOMAIN_PASS`
- Password of Orchestration domain
* - `HEAT_PASS`
- Password of Orchestration service user ``heat``
* - `KEYSTONE_DBPASS`
- Database password of Identity service
* - `NEUTRON_DBPASS`
- Database password for the Networking service
* - `NEUTRON_PASS`
- Password of Networking service user ``neutron``
* - `NOVA_DBPASS`
- Database password for Compute service
* - `NOVA_PASS`
- Password of Compute service user ``nova``
* - `RABBIT_PASS`
- Password of user guest of RabbitMQ
* - `SAHARA_DBPASS`
- Database password of Data processing service
* - `SWIFT_PASS`
- Password of Object Storage service user ``swift``
* - `TROVE_DBPASS`
- Database password of Database service
* - `TROVE_PASS`
- Password of Database service user ``trove``
|
OpenStack and supporting services require administrative privileges
during installation and operation. In some cases, services perform
modifications to the host that can interfere with deployment automation
tools such as Ansible, Chef, and Puppet. For example, some OpenStack
services add a root wrapper to ``sudo`` that can interfere with security
policies. See the `Cloud Administrator
Guide <http://docs.openstack.org/admin-guide-cloud/content/root-wrap-reference.html>`__
for more information.
Also, the Networking service assumes default
values for kernel network parameters and modifies firewall rules. To
avoid most issues during your initial installation, we recommend using a
stock deployment of a supported distribution on your hosts. However, if
you choose to automate deployment of your hosts, review the
configuration and policies applied to them before proceeding further.
Networking, NTP, OpenStack service dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. toctree::
:hidden:
:maxdepth: 2
basics-prerequisites.rst
basics-security.rst
basics-networking.rst
basics-ntp.rst
basics-packages.rst
basics-database.rst
basics-queue.rst

150
doc/install-guide-rst/source/basics-database.rst
View File

@@ -1,150 +0,0 @@
.. highlight:: ini
:linenothreshold: 1
SQL database
~~~~~~~~~~~~
Most OpenStack services use an SQL database to store information. The
database typically runs on the controller node. The procedures in this
guide use MariaDB or MySQL depending on the distribution. OpenStack
services also support other SQL databases including
`PostgreSQL <http://www.postgresql.org/>`__.
**To install and configure the database server**
1. Install the packages:
.. only:: rdo or ubuntu or obs
.. note::
The Python MySQL library is compatible with MariaDB.
.. only:: ubuntu
.. code-block:: console
# apt-get install mariadb-server python-mysqldb
.. only:: debian
.. code-block:: console
# apt-get install mysql-server python-mysqldb
.. only:: rdo
.. code-block:: console
# yum install mariadb mariadb-server MySQL-python
.. only:: obs
.. code-block:: console
# zypper install mariadb-client mariadb python-mysql
.. only:: ubuntu or debian
2. Choose a suitable password for the database root account.
3. Create and edit the :file:`/etc/mysql/conf.d/mysqld_openstack.cnf` file
and complete the following actions:
- In the ``[mysqld]`` section, set the
``bind-address`` key to the management IP
address of the controller node to enable access by other
nodes via the management network:
.. code:: ini
[mysqld]
...
bind-address = 10.0.0.11
- In the ``[mysqld]`` section, set the following keys to enable
useful options and the UTF-8 character set:
.. code:: ini
[mysqld]
...
default-storage-engine = innodb
innodb_file_per_table
collation-server = utf8_general_ci
init-connect = 'SET NAMES utf8'
character-set-server = utf8
.. only:: obs or rdo
2. Create and edit the :file:`/etc/my.cnf.d/mariadb_openstack.cnf` file
and complete the following actions:
- In the ``[mysqld]`` section, set the
``bind-address`` key to the management IP
address of the controller node to enable access by other
nodes via the management network:
.. code:: ini
[mysqld]
...
bind-address = 10.0.0.11
- In the ``[mysqld]`` section, set the following keys to enable
useful options and the UTF-8 character set:
.. code:: ini
[mysqld]
...
default-storage-engine = innodb
innodb_file_per_table
collation-server = utf8_general_ci
init-connect = 'SET NAMES utf8'
character-set-server = utf8
**To finalize installation**
.. only:: ubuntu or debian
1. Restart the database service:
.. code-block:: console
# service mysql restart
.. only:: rdo or obs
1. Start the database service and configure it to start when the system
boots:
.. only:: rdo
.. code-block:: console
# systemctl enable mariadb.service
# systemctl start mariadb.service
.. only:: obs
.. code-block:: console
# systemctl enable mysql.service
# systemctl start mysql.service
.. only:: ubuntu or debian
2. Secure the database service:
.. literalinclude:: mariadb_output.txt
.. only:: rdo or obs
2. Secure the database service including choosing a suitable
password for the root account:
.. literalinclude:: mariadb_output.txt

11
doc/install-guide-rst/source/basics-networking-neutron.rst
View File

@@ -1,8 +1,8 @@
.. highlight:: ini
==============================
OpenStack Networking (neutron)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
==============================
The example architecture with OpenStack Networking (neutron) requires
one controller node, one network node, and at least one compute node.
@@ -52,7 +52,12 @@ network infrastructure.
|
:ref:`figure-neutron-networks`
.. figure:: figures/installguidearch-neutron-networks.png
:alt: Minimal architecture example with OpenStack Networking
(neutron)—Network layout
**Minimal architecture example with OpenStack Networking
(neutron)—Network layout**
|

11
doc/install-guide-rst/source/basics-networking-nova.rst
View File

@@ -1,8 +1,8 @@
.. highlight:: ini
================================
Legacy networking (nova-network)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
================================
The example architecture with legacy networking (nova-network) requires
a controller node and at least one compute node. The controller node
@@ -40,7 +40,12 @@ network infrastructure.
|
:ref:`figure-nova-networks`
.. figure:: figures/installguidearch-nova-networks.png
:alt: Minimal architecture example with legacy networking
(nova-network)—Network layout
**Minimal architecture example with legacy networking
(nova-network)—Network layout**
|

17
doc/install-guide-rst/source/basics-networking.rst
View File

@@ -1,5 +1,11 @@
==========
Networking
~~~~~~~~~~
==========
.. toctree::
basics-networking-neutron.rst
basics-networking-nova.rst
.. only:: ubuntu
@@ -84,12 +90,3 @@ Internet access for OpenStack services.
by default. For more information about securing your environment,
refer to the
`OpenStack Security Guide <http://docs.openstack.org/sec/>`__.
.. include:: basics-networking-neutron.rst
.. include:: basics-networking-nova.rst
.. toctree::
:hidden:
basics-networking-neutron.rst
basics-networking-nova.rst

228
doc/install-guide-rst/source/basics-packages.rst
View File

@@ -1,5 +1,12 @@
.. highlight:: ini
:linenothreshold: 1
==============================
OpenStack service dependencies
==============================
OpenStack packages
~~~~~~~~~~~~~~~~~~
------------------
Distributions release OpenStack packages as part of the distribution or
using other methods because of differing release schedules. Perform
@@ -235,3 +242,222 @@ these procedures on all nodes.
.. note::
The installation process for this package can take a while.
|
SQL database
------------
Most OpenStack services use an SQL database to store information. The
database typically runs on the controller node. The procedures in this
guide use MariaDB or MySQL depending on the distribution. OpenStack
services also support other SQL databases including
`PostgreSQL <http://www.postgresql.org/>`__.
**To install and configure the database server**
1. Install the packages:
.. only:: rdo or ubuntu or obs
.. note::
The Python MySQL library is compatible with MariaDB.
.. only:: ubuntu
.. code-block:: console
# apt-get install mariadb-server python-mysqldb
.. only:: debian
.. code-block:: console
# apt-get install mysql-server python-mysqldb
.. only:: rdo
.. code-block:: console
# yum install mariadb mariadb-server MySQL-python
.. only:: obs
.. code-block:: console
# zypper install mariadb-client mariadb python-mysql
.. only:: ubuntu or debian
2. Choose a suitable password for the database root account.
3. Create and edit the :file:`/etc/mysql/conf.d/mysqld_openstack.cnf` file
and complete the following actions:
- In the ``[mysqld]`` section, set the
``bind-address`` key to the management IP
address of the controller node to enable access by other
nodes via the management network:
.. code:: ini
[mysqld]
...
bind-address = 10.0.0.11
- In the ``[mysqld]`` section, set the following keys to enable
useful options and the UTF-8 character set:
.. code:: ini
[mysqld]
...
default-storage-engine = innodb
innodb_file_per_table
collation-server = utf8_general_ci
init-connect = 'SET NAMES utf8'
character-set-server = utf8
.. only:: obs or rdo
2. Create and edit the :file:`/etc/my.cnf.d/mariadb_openstack.cnf` file
and complete the following actions:
- In the ``[mysqld]`` section, set the
``bind-address`` key to the management IP
address of the controller node to enable access by other
nodes via the management network:
.. code:: ini
[mysqld]
...
bind-address = 10.0.0.11
- In the ``[mysqld]`` section, set the following keys to enable
useful options and the UTF-8 character set:
.. code:: ini
[mysqld]
...
default-storage-engine = innodb
innodb_file_per_table
collation-server = utf8_general_ci
init-connect = 'SET NAMES utf8'
character-set-server = utf8
**To finalize installation**
.. only:: ubuntu or debian
1. Restart the database service:
.. code-block:: console
# service mysql restart
.. only:: rdo or obs
1. Start the database service and configure it to start when the system
boots:
.. only:: rdo
.. code-block:: console
# systemctl enable mariadb.service
# systemctl start mariadb.service
.. only:: obs
.. code-block:: console
# systemctl enable mysql.service
# systemctl start mysql.service
.. only:: ubuntu or debian
2. Secure the database service:
.. literalinclude:: mariadb_output.txt
.. only:: rdo or obs
2. Secure the database service including choosing a suitable
password for the root account:
.. literalinclude:: mariadb_output.txt
|
Message queue
-------------
OpenStack uses a :term:`message queue` to coordinate operations and
status information among services. The message queue service typically
runs on the controller node. OpenStack supports several message queue
services including `RabbitMQ <http://www.rabbitmq.com>`__,
`Qpid <http://qpid.apache.org>`__, and `ZeroMQ <http://zeromq.org>`__.
However, most distributions that package OpenStack support a particular
message queue service. This guide implements the RabbitMQ message queue
service because most distributions support it. If you prefer to
implement a different message queue service, consult the documentation
associated with it.
**To install the message queue service**
* Install the package:
.. only:: ubuntu or debian
.. code-block:: console
# apt-get install rabbitmq-server
.. only:: rdo
.. code-block:: console
# yum install rabbitmq-server
.. only:: obs
.. code-block:: console
# zypper install rabbitmq-server
**To configure the message queue service**
#. Start the message queue service and configure it to start when the
system boots:
.. only:: rdo or obs
.. code-block:: console
# systemctl enable rabbitmq-server.service
# systemctl start rabbitmq-server.service
#. Add the ``openstack`` user:
.. code-block:: console
# rabbitmqctl add_user openstack `RABBIT_PASS`
Creating user "openstack" ...
...done.
Replace `RABBIT_PASS` with a suitable password.
#. Permit configuration, write, and read access for the
``openstack`` user:
.. code-block:: console
# rabbitmqctl set_permissions openstack ".*" ".*" ".*"
Setting permissions for user "openstack" in vhost "/" ...
...done.

54
doc/install-guide-rst/source/basics-prerequisites.rst
View File

@@ -1,54 +0,0 @@
Before you begin
~~~~~~~~~~~~~~~~
For best performance, we recommend that your environment meets or
exceeds the hardware requirements in
:ref:`figure-neutron-network-hw` or
:ref:`figure-legacy-network-hw`. However, OpenStack does not require a
significant amount of resources and the following minimum requirements
should support a proof-of-concept environment with core services
and several :term:`CirrOS` instances:
- Controller Node: 1 processor, 2 GB memory, and 5 GB storage
- Network Node: 1 processor, 512 MB memory, and 5 GB storage
- Compute Node: 1 processor, 2 GB memory, and 10 GB storage
To minimize clutter and provide more resources for OpenStack, we
recommend a minimal installation of your Linux distribution. Also, we
strongly recommend that you install a 64-bit version of your
distribution on at least the compute node. If you install a 32-bit
version of your distribution on the compute node, attempting to start an
instance using a 64-bit image will fail.
.. note::
A single disk partition on each node works for most basic
installations. However, you should consider
:term:`Logical Volume Manager (LVM)` for installations with
optional services such as Block Storage.
Many users build their test environment on a
:term:`virtual machine (VM)`. The primary benefits of VMs include
the following:
- One physical server can support multiple nodes, each with almost any
number of network interfaces.
- Ability to take periodic "snap shots" throughout the installation
process and "roll back" to a working configuration in the event of a
problem.
However, VMs will reduce performance of your instances, particularly if
your hypervisor and/or processor lacks support for hardware acceleration
of nested VMs.
.. note::
If you choose to install on VMs, make sure your hypervisor permits
:term:`promiscuous mode` and disables MAC address filtering on the
:term:`external network`.
For more information about system requirements, see the `OpenStack
Operations Guide <http://docs.openstack.org/ops/>`_.

67
doc/install-guide-rst/source/basics-queue.rst
View File

@@ -1,67 +0,0 @@
Message queue
~~~~~~~~~~~~~
OpenStack uses a :term:`message queue` to coordinate operations and
status information among services. The message queue service typically
runs on the controller node. OpenStack supports several message queue
services including `RabbitMQ <http://www.rabbitmq.com>`__,
`Qpid <http://qpid.apache.org>`__, and `ZeroMQ <http://zeromq.org>`__.
However, most distributions that package OpenStack support a particular
message queue service. This guide implements the RabbitMQ message queue
service because most distributions support it. If you prefer to
implement a different message queue service, consult the documentation
associated with it.
**To install the message queue service**
* Install the package:
.. only:: ubuntu or debian
.. code-block:: console
# apt-get install rabbitmq-server
.. only:: rdo
.. code-block:: console
# yum install rabbitmq-server
.. only:: obs
.. code-block:: console
# zypper install rabbitmq-server
**To configure the message queue service**
#. Start the message queue service and configure it to start when the
system boots:
.. only:: rdo or obs
.. code-block:: console
# systemctl enable rabbitmq-server.service
# systemctl start rabbitmq-server.service
#. Add the ``openstack`` user:
.. code-block:: console
# rabbitmqctl add_user openstack `RABBIT_PASS`
Creating user "openstack" ...
...done.
Replace `RABBIT_PASS` with a suitable password.
#. Permit configuration, write, and read access for the
``openstack`` user:
.. code-block:: console
# rabbitmqctl set_permissions openstack ".*" ".*" ".*"
Setting permissions for user "openstack" in vhost "/" ...
...done.

94
doc/install-guide-rst/source/basics-security.rst
View File

@@ -1,94 +0,0 @@
Security
~~~~~~~~
OpenStack services support various security methods including password,
policy, and encryption. Additionally, supporting services including the
database server and message broker support at least password security.
To ease the installation process, this guide only covers password
security where applicable. You can create secure passwords manually,
generate them using a tool such as
`pwgen <http://sourceforge.net/projects/pwgen/>`__, or by running the
following command:
.. code-block:: console
$ openssl rand -hex 10
For OpenStack services, this guide uses `SERVICE_PASS` to reference
service account passwords and `SERVICE_DBPASS` to reference database
passwords.
The following table provides a list of services that require passwords
and their associated references in the guide:
.. list-table:: **Passwords**
:widths: 50 60
:header-rows: 1
* - Password name
- Description
* - Database password (no variable used)
- Root password for the database
* - `ADMIN_PASS`
- Password of user ``admin``
* - `CEILOMETER_DBPASS`
- Database password for the Telemetry service
* - `CEILOMETER_PASS`
- Password of Telemetry service user ``ceilometer``
* - `CINDER_DBPASS`
- Database password for the Block Storage service
* - `CINDER_PASS`
- Password of Block Storage service user ``cinder``
* - `DASH_DBPASS`
- Database password for the dashboard
* - `DEMO_PASS`
- Password of user ``demo``
* - `GLANCE_DBPASS`
- Database password for Image service
* - `GLANCE_PASS`
- Password of Image service user ``glance``
* - `HEAT_DBPASS`
- Database password for the Orchestration service
* - `HEAT_DOMAIN_PASS`
- Password of Orchestration domain
* - `HEAT_PASS`
- Password of Orchestration service user ``heat``
* - `KEYSTONE_DBPASS`
- Database password of Identity service
* - `NEUTRON_DBPASS`
- Database password for the Networking service
* - `NEUTRON_PASS`
- Password of Networking service user ``neutron``
* - `NOVA_DBPASS`
- Database password for Compute service
* - `NOVA_PASS`
- Password of Compute service user ``nova``
* - `RABBIT_PASS`
- Password of user guest of RabbitMQ
* - `SAHARA_DBPASS`
- Database password of Data processing service
* - `SWIFT_PASS`
- Password of Object Storage service user ``swift``
* - `TROVE_DBPASS`
- Database password of Database service
* - `TROVE_PASS`
- Password of Database service user ``trove``
|
OpenStack and supporting services require administrative privileges
during installation and operation. In some cases, services perform
modifications to the host that can interfere with deployment automation
tools such as Ansible, Chef, and Puppet. For example, some OpenStack
services add a root wrapper to ``sudo`` that can interfere with security
policies. See the `Cloud Administrator
Guide <http://docs.openstack.org/admin-guide-cloud/content/root-wrap-reference.html>`__
for more information.
Also, the Networking service assumes default
values for kernel network parameters and modifies firewall rules. To
avoid most issues during your initial installation, we recommend using a
stock deployment of a supported distribution on your hosts. However, if
you choose to automate deployment of your hosts, review the
configuration and policies applied to them before proceeding further.