openstack/openstack-manuals
Code Issues Proposed changes
Files
801f3cf72c49bedb03e4da19cb94f005a0c33905
openstack-manuals/doc/install-guide/section_neutron-ml2-controller-node.xml
Matthew Kassawara 34f04d6155 Improve install guide neutron ML2 sections 
I improved the neutron ML2 sections of the installation guide
as follows:

1) Removed 'openstack-config' steps.
2) Broke Debian steps into separate procedures for easier
   management.
3) Changed 'core_plugin' and 'service_plugins' keys in neutron.conf
   to use more compatible long values.

Please keep reviews in scope. Other patches depend on this patch.

Change-Id: Ia30d6656de0a0e44d53b12a0a044eeda87b3c873
Implements: blueprint installation-guide-improvements
2014-08-29 18:34:21 +00:00

344 lines
16 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="UTF-8"?>
<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="neutron-ml2-controller-node">
<title>Configure controller node</title>
<procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
<title>Prerequisites</title>
<para>Before you configure OpenStack Networking (neutron), you must create
a database and Identity service credentials including a user and
service.</para>
<step>
<para>Connect to the database as the root user, create the
<literal>neutron</literal> database, and grant the proper
access to it:</para>
<para>Replace <replaceable>NEUTRON_DBPASS</replaceable> with a suitable
password.</para>
<screen><prompt>$</prompt> <userinput>mysql -u root -p</userinput>
<prompt>mysql></prompt> <userinput>CREATE DATABASE neutron;</userinput>
<prompt>mysql></prompt> <userinput>GRANT ALL PRIVILEGES ON neutron.* TO 'neutron'@'localhost' \
IDENTIFIED BY '<replaceable>NEUTRON_DBPASS</replaceable>';</userinput>
<prompt>mysql></prompt> <userinput>GRANT ALL PRIVILEGES ON neutron.* TO 'neutron'@'%' \
IDENTIFIED BY '<replaceable>NEUTRON_DBPASS</replaceable>';</userinput></screen>
</step>
<step>
<para>Create Identity service credentials for Networking:</para>
<substeps>
<step>
<para>Create the <literal>neutron</literal> user:</para>
<para>Replace <replaceable>NEUTRON_PASS</replaceable> with a suitable
password and <replaceable>neutron@example.com</replaceable> with
a suitable e-mail address.</para>
<screen><prompt>$</prompt> <userinput>keystone user-create --name neutron --pass <replaceable>NEUTRON_PASS</replaceable> \
--email <replaceable>neutron@example.com</replaceable></userinput></screen>
</step>
<step>
<para>Link the <literal>neutron</literal> user to the
<literal>service</literal> tenant and <literal>admin</literal>
role:</para>
<screen><prompt>$</prompt> <userinput>keystone user-role-add --user neutron --tenant service --role admin</userinput></screen>
</step>
<step>
<para>Create the <literal>neutron</literal> service:</para>
<screen><prompt>$</prompt> <userinput>keystone service-create --name neutron --type network \
--description "OpenStack Networking"</userinput></screen>
</step>
<step>
<para>Create the service endpoint:</para>
<screen><prompt>$</prompt> <userinput>keystone endpoint-create \
--service-id \
$(keystone service-list | awk '/ network / {print $2}') \
--publicurl http://<replaceable>controller</replaceable>:9696 \
--adminurl http://<replaceable>controller</replaceable>:9696 \
--internalurl http://<replaceable>controller</replaceable>:9696</userinput></screen>
</step>
</substeps>
</step>
</procedure>
<procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
<title>To install the Networking components</title>
<step>
<screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install neutron-server neutron-plugin-ml2</userinput></screen>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-neutron openstack-neutron-ml2 python-neutronclient</userinput></screen>
<screen os="sles;opensuse"><prompt>#</prompt> <userinput>zypper install openstack-neutron openstack-neutron-server</userinput></screen>
<note os="sles;opensuse">
<para>SUSE does not use a separate ML2 plug-in package.</para>
</note>
</step>
</procedure>
<procedure os="debian">
<title>To install and configure the Networking components</title>
<step>
<screen><prompt>#</prompt> <userinput>apt-get install neutron-server</userinput></screen>
<note>
<para>Debian does not use a separate ML2 plug-in package.</para>
</note>
</step>
<step>
<para>Respond to prompts for
<link linkend="debconf-dbconfig-common">database management</link>,
<link linkend="debconf-keystone_authtoken">Identity service
credentials</link>,
<link linkend="debconf-api-endpoints">service endpoint
registration</link>, and
<link linkend="debconf-rabbitmq">message broker
credentials</link>.</para>
</step>
<step>
<para>Select the ML2 plug-in:</para>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata scale="50"
fileref="figures/debconf-screenshots/neutron_1_plugin_selection.png"
/>
</imageobject>
</mediaobject>
</informalfigure>
<note>
<para>Selecting the ML2 plug-in also populates the
<option>service_plugins</option> and
<option>allow_overlapping_ips</option> keys in the
<filename>/etc/neutron/neutron.conf</filename> file with the
appropriate values.</para>
</note>
</step>
</procedure>
<procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
<title>To configure the Networking server component</title>
<para>The Networking server component configuration includes the database,
authentication mechanism, message broker, topology change notifier,
and plug-in.</para>
<step>
<para>Configure Networking to use the database:</para>
<substeps>
<step>
<para>Edit the <filename>/etc/neutron/neutron.conf</filename>
file and add the following key to the
<literal>[database]</literal> section:</para>
<para>Replace <replaceable>NEUTRON_DBPASS</replaceable> with the
password you chose for the database.</para>
<programlisting language="ini">[database]
...
connection = mysql://neutron:<replaceable>NEUTRON_DBPASS</replaceable>@<replaceable>controller</replaceable>/neutron</programlisting>
</step>
</substeps>
</step>
<step>
<para>Configure Networking to use the Identity service for
authentication:</para>
<substeps>
<step>
<para>Edit the <filename>/etc/neutron/neutron.conf</filename>
file and add the following key to the
<literal>[DEFAULT]</literal> section:</para>
<programlisting language="ini">[DEFAULT]
...
auth_strategy = keystone</programlisting>
<para>Add the following keys to the
<literal>[keystone_authtoken]</literal> section:</para>
<para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
password you chose for the <literal>neutron</literal> user
in the Identity service.</para>
<programlisting language="ini">[keystone_authtoken]
...
auth_uri = http://<replaceable>controller</replaceable>:5000
auth_host = <replaceable>controller</replaceable>
auth_protocol = http
auth_port = 35357
admin_tenant_name = service
admin_user = neutron
admin_password = <replaceable>NEUTRON_PASS</replaceable></programlisting>
</step>
</substeps>
</step>
<step>
<para>Configure Networking to use the message broker:</para>
<substeps>
<step>
<para>Edit the <filename>/etc/neutron/neutron.conf</filename> file
and add the following keys to the <literal>[DEFAULT]</literal>
section:</para>
<para>Replace <replaceable>RABBIT_PASS</replaceable> with the
password you chose for the <literal>guest</literal> account in
<application>RabbitMQ</application>.</para>
<programlisting language="ini">[DEFAULT]
...
rpc_backend = neutron.openstack.common.rpc.impl_kombu
rabbit_host = <replaceable>controller</replaceable>
rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
</step>
</substeps>
</step>
<step>
<para>Configure Networking to notify Compute about network topology
changes:</para>
<para>Replace <replaceable>SERVICE_TENANT_ID</replaceable> with the
<literal>service</literal> tenant identifier (id) in the Identity
service and <replaceable>NOVA_PASS</replaceable> with the password
you chose for the <literal>nova</literal> user in the Identity
service.</para>
<substeps>
<step>
<para>Edit the <filename>/etc/neutron/neutron.conf</filename> file
and add the following keys to the <literal>[DEFAULT]</literal>
section:</para>
<programlisting language="ini">[DEFAULT]
...
notify_nova_on_port_status_changes = True
notify_nova_on_port_data_changes = True
nova_url = http://<replaceable>controller</replaceable>:8774/v2
nova_admin_username = nova
nova_admin_tenant_id = <replaceable>SERVICE_TENANT_ID</replaceable>
nova_admin_password = <replaceable>NOVA_PASS</replaceable>
nova_admin_auth_url = http://<replaceable>controller</replaceable>:35357/v2.0</programlisting>
</step>
</substeps>
<note>
<para>To obtain the <literal>service</literal> tenant
identifier (id):</para>
<screen><prompt>$</prompt> <userinput>source admin-openrc.sh</userinput>
<prompt>$</prompt> <userinput>keystone tenant-get service</userinput>
<computeroutput>+-------------+----------------------------------+
| Property | Value |
+-------------+----------------------------------+
| description | Service Tenant |
| enabled | True |
| id | f727b5ec2ceb4d71bad86dfc414449bf |
| name | service |
+-------------+----------------------------------+</computeroutput></screen>
</note>
</step>
<step>
<para>Configure Networking to use the Modular Layer 2 (ML2) plug-in
and associated services:</para>
<substeps>
<step>
<para>Edit the <filename>/etc/neutron/neutron.conf</filename> file
and add the following keys to the <literal>[DEFAULT]</literal>
section:</para>
<programlisting language="ini">[DEFAULT]
...
core_plugin = ml2
service_plugins = router
allow_overlapping_ips = True</programlisting>
<note>
<para>We recommend adding <literal>verbose = True</literal> to
the <literal>[DEFAULT]</literal> section in
<filename>/etc/neutron/neutron.conf</filename> to assist with
troubleshooting.</para>
</note>
</step>
</substeps>
</step>
</procedure>
<procedure>
<title>To configure the Modular Layer 2 (ML2) plug-in</title>
<para>The ML2 plug-in uses the Open vSwitch (OVS) mechanism (agent) to
build the virtual networking framework for instances. However, the
controller node does not need the OVS agent or service because it
does not handle instance network traffic.</para>
<step>
<para>Edit the
<filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>
file:</para>
<para>Add the following keys to the <literal>[ml2]</literal>
section:</para>
<programlisting language="ini">[ml2]
...
type_drivers = gre
tenant_network_types = gre
mechanism_drivers = openvswitch</programlisting>
<para>Add the following key to the
<literal>[ml2_type_gre]</literal> section:</para>
<programlisting language="ini">[ml2_type_gre]
...
tunnel_id_ranges = 1:1000</programlisting>
<para>Add the <literal>[securitygroup]</literal> section and the
following keys to it:</para>
<programlisting language="ini">[securitygroup]
...
firewall_driver = neutron.agent.linux.iptables_firewall.OVSHybridIptablesFirewallDriver
enable_security_group = True</programlisting>
</step>
</procedure>
<procedure>
<title>To configure Compute to use Networking</title>
<para>By default, most distributions configure Compute to use legacy
networking. You must reconfigure Compute to manage networks through
Networking.</para>
<step>
<para>Edit the <filename>/etc/nova/nova.conf</filename> and add the
following keys to the <literal>[DEFAULT]</literal> section:</para>
<para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
password you chose for the <literal>neutron</literal> user
in the Identity service.</para>
<programlisting language="ini">[DEFAULT]
...
network_api_class = nova.network.neutronv2.api.API
neutron_url = http://<replaceable>controller</replaceable>:9696
neutron_auth_strategy = keystone
neutron_admin_tenant_name = service
neutron_admin_username = neutron
neutron_admin_password = <replaceable>NEUTRON_PASS</replaceable>
neutron_admin_auth_url = http://<replaceable>controller</replaceable>:35357/v2.0
linuxnet_interface_driver = nova.network.linux_net.LinuxOVSInterfaceDriver
firewall_driver = nova.virt.firewall.NoopFirewallDriver
security_group_api = neutron</programlisting>
<note>
<para>By default, Compute uses an internal firewall service. Since
Networking includes a firewall service, you must disable the
Compute firewall service by using the
<literal>nova.virt.firewall.NoopFirewallDriver</literal> firewall
driver.</para>
</note>
</step>
</procedure>
<procedure>
<title>To finalize installation</title>
<step os="rhel;centos;fedora">
<para>The Networking service initialization scripts expect a symbolic
link <filename>/etc/neutron/plugin.ini</filename> pointing to the
configuration file associated with your chosen plug-in. Using
ML2, for example, the symbolic link must point to
<filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>.
If this symbolic link does not exist, create it using the
following commands:</para>
<screen><prompt>#</prompt> <userinput>ln -s /etc/neutron/plugins/ml2/ml2_conf.ini /etc/neutron/plugin.ini</userinput></screen>
</step>
<step os="sles;opensuse">
<para>The Networking service initialization scripts expect the variable
<literal>NEUTRON_PLUGIN_CONF</literal> in file
<filename>/etc/sysconfig/neutron</filename> to reference the
configuration file associated with your chosen plug-in. Using
ML2, for example, edit the
<filename>/etc/sysconfig/neutron</filename> file and add the
following:</para>
<programlisting>NEUTRON_PLUGIN_CONF="/etc/neutron/plugins/ml2/ml2_conf.ini"</programlisting>
</step>
<step>
<para>Restart the Compute services:</para>
<screen os="rhel;centos;fedora;sles;opensuse"><prompt>#</prompt> <userinput>service openstack-nova-api restart</userinput>
<prompt>#</prompt> <userinput>service openstack-nova-scheduler restart</userinput>
<prompt>#</prompt> <userinput>service openstack-nova-conductor restart</userinput></screen>
<screen os="ubuntu;debian"><prompt>#</prompt> <userinput>service nova-api restart</userinput>
<prompt>#</prompt> <userinput>service nova-scheduler restart</userinput>
<prompt>#</prompt> <userinput>service nova-conductor restart</userinput></screen>
</step>
<step os="rhel;centos;fedora;sles;opensuse">
<para>Start the Networking service and configure it to start when the
system boots:</para>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>service neutron-server start</userinput>
<prompt>#</prompt> <userinput>chkconfig neutron-server on</userinput></screen>
<screen os="sles;opensuse"><prompt>#</prompt> <userinput>service openstack-neutron start</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-neutron on</userinput></screen>
</step>
<step os="ubuntu;debian">
<para>Restart the Networking service:</para>
<screen><prompt>#</prompt> <userinput>service neutron-server restart</userinput></screen>
</step>
</procedure>
</section>
View Git Blame Copy Permalink