From f3ecb24050461b5daa88e3124ab2eb311b285a5e Mon Sep 17 00:00:00 2001
From: Matt Kassawara <mkassawara@gmail.com>
Date: Mon, 24 Mar 2014 20:31:45 -0600
Subject: [PATCH] Restructured and updated Nova networking sections
As part of the installation guide improvement project, I performed
the following operations on the Nova networking sections of the
installation guide:
1) Split configuration and initial network creation section to align
with structure of Neutron chapter.
2) Aligned phrasing/wording and examples with Neutron chapter.
3) Removed defunct ch_neutron.xml from repository.
4) Modified links affected by these changes.
5) Updated glossary as necessary.
Change-Id: I690a7c2565826f4370940a716a6200e974211d8f
Partial-Bug: #1291071
Implements: blueprint networking-install-guide-improvements
---
doc/glossary/glossary-terms.xml | 20 +++
doc/install-guide/ch_networking.xml | 13 ++
doc/install-guide/ch_neutron.xml | 46 -------
doc/install-guide/section_nova-boot.xml | 2 +-
.../section_nova-networking-compute-node.xml | 122 ++++++++----------
...ection_nova-networking-initial-network.xml | 43 ++++++
6 files changed, 129 insertions(+), 117 deletions(-)
delete mode 100644 doc/install-guide/ch_neutron.xml
create mode 100644 doc/install-guide/section_nova-networking-initial-network.xml
diff --git a/doc/glossary/glossary-terms.xml b/doc/glossary/glossary-terms.xml
index 806aefacdd..e6f65a8a15 100644
--- a/doc/glossary/glossary-terms.xml
+++ b/doc/glossary/glossary-terms.xml
@@ -2954,6 +2954,16 @@
Currently not supported in Identity Service.</para>
</glossdef>
</glossentry>
+ <glossentry>
+ <glossterm>multi-host</glossterm>
+ <glossdef>
+ <para>High-availability mode for legacy (nova) networking.
+ Each compute node handles NAT and DHCP and acts as a
+ gateway for all of the VMs on it. A networking failure
+ on one compute node doesn't affect VMs on other compute
+ nodes.</para>
+ </glossdef>
+ </glossentry>
<glossentry>
<glossterm>MultiNic</glossterm>
<glossdef>
@@ -4749,6 +4759,16 @@
<para>An L2 network segment within Networking.</para>
</glossdef>
</glossentry>
+ <glossentry>
+ <glossterm>virtual networking</glossterm>
+ <glossdef>
+ <para>A generic term for virtualization of network functions
+ such as switching, routing, load balancing, and
+ security using a combination of VMs and overlays on
+ physical network infrastructure.
+ </para>
+ </glossdef>
+ </glossentry>
<glossentry>
<glossterm>Virtual Network Computing (VNC)</glossterm>
<glossdef>
diff --git a/doc/install-guide/ch_networking.xml b/doc/install-guide/ch_networking.xml
index e53b5437d3..e9a42809aa 100644
--- a/doc/install-guide/ch_networking.xml
+++ b/doc/install-guide/ch_networking.xml
@@ -17,6 +17,18 @@
<para>We are updating this material for Icehouse. You may find structure
and/or content issues during this process.</para>
</warning>
+ <para>Configuring networking in OpenStack can be a bewildering experience.
+ This guide provides step-by-step instructions for both OpenStack
+ Networking (neutron) and the legacy (nova) networking service. If you are
+ unsure which to use, we recommend trying OpenStack Networking because it
+ offers a considerable number of features and flexibility including
+ <glossterm baseform="plug-in">plug-ins</glossterm> for a variety of
+ emerging products supporting <glossterm>virtual networking</glossterm>.
+ See the
+ <link xlink:href="http://docs.openstack.org/admin-guide-cloud/content/ch_networking.html">Networking</link>
+ chapter of the
+ <citetitle>OpenStack Cloud Administrator Guide</citetitle> for more
+ information.</para>
<section xml:id="section_neutron-networking">
<title>Networking (neutron)</title>
<xi:include href="section_neutron-concepts.xml"/>
@@ -28,5 +40,6 @@
<section xml:id="section_nova-networking">
<title>Legacy networking</title>
<xi:include href="section_nova-networking-compute-node.xml"/>
+ <xi:include href="section_nova-networking-initial-network.xml"/>
</section>
</chapter>
diff --git a/doc/install-guide/ch_neutron.xml b/doc/install-guide/ch_neutron.xml
deleted file mode 100644
index cfaafec210..0000000000
--- a/doc/install-guide/ch_neutron.xml
+++ /dev/null
@@ -1,46 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="ch_neutron">
- <title>Add the Networking service</title>
-<!-- FIXME Temporarily replacing this warning.
- <warning>
- <para>This chapter is a bit more adventurous than we would
- like. We are working on cleanup and improvements to it.
- Like for the rest of the Installation Guide, feedback
- through bug reports and patches to improve it are
- welcome.</para>
- </warning>
--->
- <warning>
- <para>We are updating this material for Icehouse. You may find structure
- and/or content issues during this process.</para>
- </warning>
- <section xml:id="neutron-considerations">
- <title>Networking considerations</title>
- <para>OpenStack Networking drivers range from software bridges
- to full control of certain switching hardware. This guide
- focuses on the Open vSwitch driver. However, the theories
- presented here are mostly applicable to other mechanisms,
- and the <link
- xlink:href="http://docs.openstack.org/trunk/config-reference/content/ch_configuring-openstack-networking.html"
- >Networking</link> chapter
- of the <citetitle>OpenStack Configuration Reference</citetitle>
- offers additional information.</para>
- <para>To prepare for installation, see <xref
- linkend="basics-packages"/>.</para>
- <warning>
- <para>If you previously set up networking for your compute node by using
- <systemitem class="service"
- >nova-network</systemitem>, this configuration
- overrides those settings.</para>
- </warning>
- </section>
- <xi:include href="section_neutron-concepts.xml"/>
- <xi:include href="section_neutron-controller-node.xml"/>
- <xi:include href="section_neutron-network-node.xml"/>
- <xi:include href="section_neutron-compute-node.xml"/>
- <xi:include href="section_neutron-initial-networks.xml"/>
- <xi:include href="section_neutron-deploy-use-cases.xml"/>
-</chapter>
diff --git a/doc/install-guide/section_nova-boot.xml b/doc/install-guide/section_nova-boot.xml
index e54c884c16..b2635fd664 100644
--- a/doc/install-guide/section_nova-boot.xml
+++ b/doc/install-guide/section_nova-boot.xml
@@ -29,7 +29,7 @@
/>.</para>
</listitem>
<listitem>
- <para>Configured networking. See <xref linkend="nova-network"
+ <para>Configured networking. See <xref linkend="ch_networking"
/>.</para>
</listitem>
</itemizedlist>
diff --git a/doc/install-guide/section_nova-networking-compute-node.xml b/doc/install-guide/section_nova-networking-compute-node.xml
index 7a99c42485..ddae05f320 100644
--- a/doc/install-guide/section_nova-networking-compute-node.xml
+++ b/doc/install-guide/section_nova-networking-compute-node.xml
@@ -1,40 +1,29 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="nova-network">
- <title>Configure networking</title>
- <warning>
- <para>We are updating this material for Icehouse. You may find structure
- and/or content issues during this process.</para>
- </warning>
- <para>Configuring networking in OpenStack can be a bewildering experience. The
- following example shows the simplest production-ready
- configuration that is available: the legacy networking in
- OpenStack Compute, with a flat network, that takes care of
- DHCP.</para>
- <para>This set up uses multi-host functionality. Networking is
- configured to be highly available by distributing networking
- functionality across multiple hosts. As a result, no single
- network controller acts as a single point of failure. This process
- configures each compute node for networking.</para>
+ xml:id="nova-networking-compute-node">
+ <title>Configure compute node</title>
+ <para>Legacy networking only involves compute nodes. This section covers
+ deployment of a simple <glossterm>flat network</glossterm> that provides
+ IP addresses to your instances via <glossterm>DHCP</glossterm>. If your
+ environment includes multiple compute nodes, the
+ <glossterm>multi-host</glossterm> feature provides redundancy by spreading
+ network functions across compute nodes.</para>
<procedure>
+ <title>To use legacy networking:</title>
<step>
- <para>Install the appropriate packages for compute networking on the
- compute node only. These packages are not required on the controller
- node.</para>
- <para os="ubuntu;debian">So that the <systemitem class="service"
- >nova-network</systemitem> service can forward metadata requests on
- each compute node, each compute node must install the <systemitem
- class="service">nova-api-metadata</systemitem> service, as
- follows:</para>
+ <para>Install the packages:</para>
<screen os="ubuntu;debian"><prompt>#</prompt> <userinput>apt-get install nova-network nova-api-metadata</userinput></screen>
- <screen os="centos;rhel;fedora"><prompt>#</prompt> <userinput>yum install openstack-nova-network</userinput></screen>
- <screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install openstack-nova-network</userinput></screen>
+ <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-nova-network openstack-nova-api</userinput></screen>
+ <screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install openstack-nova-network openstack-nova-api</userinput></screen>
</step>
- <step>
- <para>Edit the <filename>nova.conf</filename> file to define the
- networking mode:</para>
- <screen os="fedora;rhel;centos;opensuse;sles"><prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT \
+ <step os="rhel;centos;fedora;sles;opensuse">
+ <para>Configure parameters in the
+ <filename>/etc/nova/nova.conf</filename> file:</para>
+ <substeps>
+ <step>
+ <para>Under the <literal>[DEFAULT]</literal> section:</para>
+ <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT \
network_manager nova.network.manager.FlatDHCPManager</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT \
firewall_driver nova.virt.libvirt.firewall.IptablesFirewallDriver</userinput>
@@ -47,51 +36,44 @@
<prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT flat_interface eth1</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT flat_network_bridge br100</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT public_interface eth1</userinput></screen>
- <screen os="opensuse;sles">
+ <screen os="opensuse;sles">
<prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT network_api_class nova.network.api.API</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/nova/nova.conf DEFAULT security_group_api nova</userinput></screen>
- <para os="ubuntu;debian">Edit the
- <filename>/etc/nova/nova.conf</filename> file and add these
- lines to the <literal>[DEFAULT]</literal> section:</para>
- <programlisting os="ubuntu;debian" language="ini">[DEFAULT]
-...
-
-network_manager=nova.network.manager.FlatDHCPManager
-firewall_driver=nova.virt.libvirt.firewall.IptablesFirewallDriver
-network_size=254
-allow_same_net_traffic=False
-multi_host=True
-send_arp_for_ha=True
-share_dhcp_address=True
-force_dhcp_release=True
-flat_network_bridge=br100
-flat_interface=eth1
-public_interface=eth1</programlisting>
+ </step>
+ </substeps>
</step>
- <step os="fedora;rhel;centos">
- <para>Provide a local metadata service that is reachable from
- instances on this compute node. Perform this step only on
- compute nodes that do not run the <systemitem class="service"
- >nova-api</systemitem> service.</para>
- <screen><prompt>#</prompt> <userinput>yum install openstack-nova-api</userinput>
-<prompt>#</prompt> <userinput>service openstack-nova-metadata-api start</userinput>
-<prompt>#</prompt> <userinput>chkconfig openstack-nova-metadata-api on</userinput></screen>
+ <step os="ubuntu;debian">
+ <para>Edit the <filename>/etc/nova/nova.conf</filename> file:</para>
+ <substeps>
+ <step>
+ <para>Add the following keys under the <literal>[DEFAULT]</literal>
+ section:</para>
+ <programlisting language="ini">[DEFAULT]
+...
+network_manager = nova.network.manager.FlatDHCPManager
+firewall_driver = nova.virt.libvirt.firewall.IptablesFirewallDriver
+network_size = 254
+allow_same_net_traffic = False
+multi_host = True
+send_arp_for_ha = True
+share_dhcp_address = True
+force_dhcp_release = True
+flat_network_bridge = br100
+flat_interface = eth1
+public_interface = eth1</programlisting>
+ </step>
+ </substeps>
</step>
<step>
- <para os="ubuntu;debian">Restart the network service:</para>
- <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>service nova-network restart</userinput></screen>
- <para os="fedora;rhel;centos;opensuse;sles">Start the network
- service and configure it to start when the system
- boots:</para>
- <screen os="centos;rhel;fedora;opensuse;sles"><prompt>#</prompt> <userinput>service openstack-nova-network start</userinput>
-<prompt>#</prompt> <userinput>chkconfig openstack-nova-network on</userinput></screen>
+ <para os="ubuntu;debian">Restart the services:</para>
+ <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>service nova-network restart</userinput>
+<prompt>#</prompt> <userinput>service nova-api-metadata restart</userinput></screen>
+ <para os="rhel;centos;fedora;sles;opensuse">Start the services and
+ configure them to start when the system boots:</para>
+ <screen os="rhel;centos;fedora;sles;opensuse"><prompt>#</prompt> <userinput>service openstack-nova-network start</userinput>
+<prompt>#</prompt> <userinput>service openstack-nova-metadata-api start</userinput>
+<prompt>#</prompt> <userinput>chkconfig openstack-nova-network on</userinput>
+<prompt>#</prompt> <userinput>chkconfig openstack-nova-metadata-api on</userinput></screen>
</step>
</procedure>
- <para>Create a network that virtual machines can use. Do this once
- for the entire installation and not on each compute node. Run the
- <command>nova network-create</command> command on the
- controller:</para>
- <screen><prompt>$</prompt> <userinput>source openrc.sh</userinput></screen>
- <screen><prompt>$</prompt> <userinput>nova network-create vmnet --fixed-range-v4=10.0.0.0/24 \
- --bridge=br100 --multi-host=T</userinput></screen>
</section>
diff --git a/doc/install-guide/section_nova-networking-initial-network.xml b/doc/install-guide/section_nova-networking-initial-network.xml
new file mode 100644
index 0000000000..f240d5fe08
--- /dev/null
+++ b/doc/install-guide/section_nova-networking-initial-network.xml
@@ -0,0 +1,43 @@
+<section xmlns="http://docbook.org/ns/docbook"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="nova-network-initial-network">
+ <title>Create initial network</title>
+ <para>Before launching your first instance, you must create the necessary
+ virtual network infrastructure to which the instance will connect.
+ This network typically provides internet access
+ <emphasis>from</emphasis> instances. You can enable internet access
+ <emphasis>to</emphasis> individual instances using a
+ <glossterm>floating IP address</glossterm> and suitable
+ <glossterm>security group</glossterm> rules. The <literal>admin</literal>
+ tenant owns this network because it provides external network access
+ for multiple tenants.</para>
+ <para>This network shares the same <glossterm>subnet</glossterm>
+ associated with the physical network connected to the external
+ <glossterm>interface</glossterm> on the compute node. You should specify
+ an exclusive slice of this subnet to prevent interference with other
+ devices on the external network.</para>
+ <note>
+ <para>Perform these commands on the controller node.</para>
+ </note>
+ <procedure>
+ <title>To create the network:</title>
+ <step>
+ <para>Source the <literal>admin</literal> tenant credentials:</para>
+ <screen><prompt>$</prompt> <userinput>source admin-openrc.sh</userinput></screen>
+ </step>
+ <step>
+ <para>Create the network:</para>
+ <para>Replace <replaceable>NETWORK_CIDR</replaceable> with the subnet
+ associated with the physical network.</para>
+ <screen><prompt>$</prompt> <userinput>nova network-create demo-net --bridge br100 --multi-host T \
+ --fixed-range-v4 <replaceable>NETWORK_CIDR</replaceable></userinput></screen>
+ <para>For example, using an exclusive slice of
+ <literal>203.0.113.0/24</literal> with IP address range
+ <literal>203.0.113.24</literal> to <literal>203.0.113.32</literal>:
+ </para>
+ <screen><prompt>$</prompt> <userinput>nova network-create demo-net --bridge br100 --multi-host T \
+ --fixed-range-v4 203.0.113.24/29</userinput></screen>
+ </step>
+ </procedure>
+</section>