openstack/openstack-manuals
Code Issues Proposed changes
6f3b65f959
openstack-manuals/doc/install-guide/section_neutron-controller-node.xml
Matthew Kassawara 8f963115d7 Update installation guide for Juno release 
I updated the installation guide for Juno release packages as
follows:

1) Converted 'systemctl' commands to single lines.
2) Converted more sections to use 'systemctl' commands.
3) Added note about lengthy installation time for
   'openstack-selinux' package.
4) Explicitly configured UUID tokens and SQL driver in
   keystone. RDO needs to update or remove the 'dist'
   configuration files for services.
5) Explicitly configured local file system store options
   in [glance_store] section that appeared two days before
   official release. Although the Ubuntu and RDO packages
   appear to work by default, late changes to configuration
   files tend to cause problems at some point.
6) Explicitly configured authentication strategy to keystone
   in nova on controller and compute nodes. I think we should
   avoid relying on defaults for this option and reconsider
   for Kilo, particularly with RDO packages.
7) Explicitly installed 'sysfsutils' package on nova compute nodes
   because nova looks for it during cinder volume operations.
8) Removed explicit installation of 'ipset' package on neutron
   network and compute nodes because the Ubuntu and RDO packages
   install it as a dependency. Not sure about SUSE, so I left
   the explicit installation.
9) Changed cinder example devices from /dev/sdb to /dev/sdb1
   because LVM on CentOS didn't like the former.

Note: The configuration changes mostly apply to RDO packages on
CentOS, but given the time constraints, I fixed some other issues.
Also, this patch ignores the sahara chapter.

Closes-Bug: #1383925

Change-Id: I0c9bbbfe72b8f0358f00d4f82b90ce4976a90ea2
2014-10-29 13:50:45 -05:00

459 lines
22 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-controller-node">
<title>Install and configure controller node</title>
<procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
<title>To configure prerequisites</title>
<para>Before you configure OpenStack Networking (neutron), you must create
a database and Identity service credentials including endpoints.</para>
<step>
<para>To create the database, complete these steps:</para>
<substeps>
<step>
<para>Use the database access client to connect to the database
server as the <literal>root</literal> user:</para>
<screen><prompt>$</prompt> <userinput>mysql -u root -p</userinput></screen>
</step>
<step>
<para>Create the <literal>neutron</literal> database:</para>
<screen><userinput>CREATE DATABASE neutron;</userinput></screen>
</step>
<step>
<para>Grant proper access to the <literal>neutron</literal>
database:</para>
<screen><userinput>GRANT ALL PRIVILEGES ON neutron.* TO 'neutron'@'localhost' \
IDENTIFIED BY '<replaceable>NEUTRON_DBPASS</replaceable>';</userinput>
<userinput>GRANT ALL PRIVILEGES ON neutron.* TO 'neutron'@'%' \
IDENTIFIED BY '<replaceable>NEUTRON_DBPASS</replaceable>';</userinput></screen>
<para>Replace <replaceable>NEUTRON_DBPASS</replaceable> with a
suitable password.</para>
</step>
<step>
<para>Exit the database access client.</para>
</step>
</substeps>
</step>
<step>
<para>Source the <literal>admin</literal> credentials to gain access to
admin-only CLI commands:</para>
<screen><prompt>$</prompt> <userinput>source admin-openrc.sh</userinput></screen>
</step>
<step>
<para>To create the Identity service credentials, complete these
steps:</para>
<substeps>
<step>
<para>Create the <literal>neutron</literal> user:</para>
<screen><prompt>$</prompt> <userinput>keystone user-create --name neutron --pass <replaceable>NEUTRON_PASS</replaceable></userinput>
<computeroutput>+----------+----------------------------------+
| Property | Value |
+----------+----------------------------------+
| email | |
| enabled | True |
| id | 7fd67878dcd04d0393469ef825a7e005 |
| name | neutron |
| username | neutron |
+----------+----------------------------------+</computeroutput></screen>
<para>Replace <replaceable>NEUTRON_PASS</replaceable> with a suitable
password.</para>
</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>
<note>
<para>This command provides no output.</para>
</note>
</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>
<computeroutput>+-------------+----------------------------------+
| Property | Value |
+-------------+----------------------------------+
| description | OpenStack Networking |
| enabled | True |
| id | 6369ddaf99a447f3a0d41dac5e342161 |
| name | neutron |
| type | network |
+-------------+----------------------------------+</computeroutput></screen>
</step>
<step>
<para>Create the Identity service endpoints:</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 \
--region regionOne</userinput>
<computeroutput>+-------------+----------------------------------+
| Property | Value |
+-------------+----------------------------------+
| adminurl | http://controller:9696 |
| id | fa18b41938a94bf6b35e2c152063ee21 |
| internalurl | http://controller:9696 |
| publicurl | http://controller:9696 |
| region | regionOne |
| service_id | 6369ddaf99a447f3a0d41dac5e342161 |
+-------------+----------------------------------+</computeroutput></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 python-neutronclient</userinput></screen>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-neutron openstack-neutron-ml2 python-neutronclient which</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> options 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 notifications,
and plug-in.</para>
<step>
<para>Edit the <filename>/etc/neutron/neutron.conf</filename> file
and complete the following actions:</para>
<substeps>
<step>
<para>In the <literal>[database]</literal> section, configure
database access:</para>
<programlisting language="ini">[database]
...
connection = mysql://neutron:<replaceable>NEUTRON_DBPASS</replaceable>@<replaceable>controller</replaceable>/neutron</programlisting>
<para>Replace <replaceable>NEUTRON_DBPASS</replaceable> with the
password you chose for the database.</para>
</step>
<step>
<para>In the <literal>[DEFAULT]</literal> section, configure
<application>RabbitMQ</application> message broker access:</para>
<programlisting language="ini">[DEFAULT]
...
rpc_backend = rabbit
rabbit_host = <replaceable>controller</replaceable>
rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
<para>Replace <replaceable>RABBIT_PASS</replaceable> with the
password you chose for the <literal>guest</literal> account in
<application>RabbitMQ</application>.</para>
</step>
<step>
<para>In the <literal>[DEFAULT]</literal> and
<literal>[keystone_authtoken]</literal> sections,
configure Identity service access:</para>
<programlisting language="ini">[DEFAULT]
...
auth_strategy = keystone
[keystone_authtoken]
...
auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0
identity_uri = http://<replaceable>controller</replaceable>:35357
admin_tenant_name = service
admin_user = neutron
admin_password = <replaceable>NEUTRON_PASS</replaceable></programlisting>
<para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
password you chose or the <literal>neutron</literal> user in the
Identity service.</para>
<note>
<para>Comment out any <literal>auth_host</literal>,
<literal>auth_port</literal>, and
<literal>auth_protocol</literal> options because the
<literal>identity_uri</literal> option replaces them.</para>
</note>
</step>
<step>
<para>In the <literal>[DEFAULT]</literal> section, enable the
Modular Layer 2 (ML2) plug-in, router service, and overlapping
IP addresses:</para>
<programlisting language="ini">[DEFAULT]
...
core_plugin = ml2
service_plugins = router
allow_overlapping_ips = True</programlisting>
</step>
<step>
<para>In the <literal>[DEFAULT]</literal> section, configure
Networking to notify Compute of network topology changes:</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_auth_url = http://<replaceable>controller</replaceable>:35357/v2.0
nova_region_name = regionOne
nova_admin_username = nova
nova_admin_tenant_id = <replaceable>SERVICE_TENANT_ID</replaceable>
nova_admin_password = <replaceable>NOVA_PASS</replaceable></programlisting>
<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>
<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>(Optional) To assist with troubleshooting,
enable verbose logging in the <literal>[DEFAULT]</literal>
section:</para>
<programlisting language="ini">[DEFAULT]
...
verbose = True</programlisting>
</step>
</substeps>
</step>
</procedure>
<procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
<title>To configure the Modular Layer 2 (ML2) plug-in</title>
<para>The ML2 plug-in uses the
<glossterm baseform="Open vSwitch">Open vSwitch (OVS)</glossterm>
mechanism (agent) to build the virtual networking framework for
instances. However, the controller node does not need the OVS
components because it does not handle instance network traffic.</para>
<step>
<para>Edit the
<filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>
file and complete the following actions:</para>
<substeps>
<step>
<para>In the <literal>[ml2]</literal> section, enable the
<glossterm baseform="flat network">flat</glossterm> and
<glossterm>generic routing encapsulation (GRE)</glossterm>
network type drivers, GRE tenant networks, and the OVS
mechanism driver:</para>
<programlisting language="ini">[ml2]
...
type_drivers = flat,gre
tenant_network_types = gre
mechanism_drivers = openvswitch</programlisting>
<warning>
<para>Once you configure the ML2 plug-in, be aware that disabling
a network type driver and re-enabling it later can lead to
database inconsistency.</para>
</warning>
</step>
<step>
<para>In the <literal>[ml2_type_gre]</literal> section, configure
the tunnel identifier (id) range:</para>
<programlisting language="ini">[ml2_type_gre]
...
tunnel_id_ranges = 1:1000</programlisting>
</step>
<step>
<para>In the <literal>[securitygroup]</literal> section, enable
security groups, enable <glossterm>ipset</glossterm>, and
configure the OVS <glossterm>iptables</glossterm> firewall
driver:</para>
<programlisting language="ini">[securitygroup]
...
enable_security_group = True
enable_ipset = True
firewall_driver = neutron.agent.linux.iptables_firewall.OVSHybridIptablesFirewallDriver</programlisting>
</step>
</substeps>
</step>
</procedure>
<procedure>
<title>To configure Compute to use Networking</title>
<para>By default, distribution packages 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> file and
complete the following actions:</para>
<substeps>
<step os="ubuntu;rhel;centos;fedora;sles;opensuse">
<para>In the <literal>[DEFAULT]</literal> section, configure
the <glossterm baseform="API">APIs</glossterm> and drivers:</para>
<programlisting language="ini">[DEFAULT]
...
network_api_class = nova.network.neutronv2.api.API
security_group_api = neutron
linuxnet_interface_driver = nova.network.linux_net.LinuxOVSInterfaceDriver
firewall_driver = nova.virt.firewall.NoopFirewallDriver</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>
<step>
<para>In the <literal>[neutron]</literal> section, configure
access parameters:</para>
<programlisting language="ini">[neutron]
...
url = http://<replaceable>controller</replaceable>:9696
auth_strategy = keystone
admin_auth_url = http://<replaceable>controller</replaceable>:35357/v2.0
admin_tenant_name = service
admin_username = neutron
admin_password = <replaceable>NEUTRON_PASS</replaceable></programlisting>
<para>Replace <replaceable>NEUTRON_PASS</replaceable> with the
password you chose for the <literal>neutron</literal> user
in the Identity service.</para>
</step>
</substeps>
</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 ML2 plug-in configuration file,
<filename>/etc/neutron/plugins/ml2/ml2_conf.ini</filename>.
If this symbolic link does not exist, create it using the
following command:</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 the
<filename>/etc/sysconfig/neutron</filename> file to
reference the ML2 plug-in configuration file. 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>Populate the database:</para>
<screen><prompt>#</prompt> <userinput>su -s /bin/sh -c "neutron-db-manage --config-file /etc/neutron/neutron.conf \
--config-file /etc/neutron/plugins/ml2/ml2_conf.ini upgrade juno" neutron</userinput></screen>
<note>
<para>Database population occurs later for Networking because the
script requires complete server and plug-in configuration
files.</para>
</note>
</step>
<step>
<para>Restart the Compute services:</para>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>systemctl restart openstack-nova-api.service openstack-nova-scheduler.service \
openstack-nova-conductor.service</userinput></screen>
<para os="sles">On SLES:</para>
<screen os="sles"><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>
<para os="opensuse">On openSUSE:</para>
<screen os="opensuse"><prompt>#</prompt> <userinput>systemctl restart openstack-nova-api.service openstack-nova-scheduler.service \
openstack-nova-conductor.service</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>systemctl enable neutron-server.service</userinput>
<prompt>#</prompt> <userinput>systemctl start neutron-server.service</userinput></screen>
<para os="sles">On SLES:</para>
<screen os="sles"><prompt>#</prompt> <userinput>service openstack-neutron start</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-neutron on</userinput></screen>
<para os="opensuse">On openSUSE:</para>
<screen os="opensuse"><prompt>#</prompt> <userinput>systemctl enable openstack-neutron.service</userinput>
<prompt>#</prompt> <userinput>systemctl start openstack-neutron.service</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>
<procedure>
<title>Verify operation</title>
<note>
<para>Perform these commands on the controller node.</para>
</note>
<step>
<para>Source the <literal>admin</literal> credentials to gain access to
admin-only CLI commands:</para>
<screen><prompt>$</prompt> <userinput>source admin-openrc.sh</userinput></screen>
</step>
<step>
<para>List loaded extensions to verify successful launch of the
<literal>neutron-server</literal> process:</para>
<screen><prompt>$</prompt> <userinput>neutron ext-list</userinput>
<computeroutput>+-----------------------+-----------------------------------------------+
| alias | name |
+-----------------------+-----------------------------------------------+
| security-group | security-group |
| l3_agent_scheduler | L3 Agent Scheduler |
| ext-gw-mode | Neutron L3 Configurable external gateway mode |
| binding | Port Binding |
| provider | Provider Network |
| agent | agent |
| quotas | Quota management support |
| dhcp_agent_scheduler | DHCP Agent Scheduler |
| l3-ha | HA Router extension |
| multi-provider | Multi Provider Network |
| external-net | Neutron external network |
| router | Neutron L3 Router |
| allowed-address-pairs | Allowed Address Pairs |
| extraroute | Neutron Extra Route |
| extra_dhcp_opt | Neutron Extra DHCP opts |
| dvr | Distributed Virtual Router |
+-----------------------+-----------------------------------------------+</computeroutput></screen>
</step>
</procedure>
</section>
View Git Blame Copy Permalink