openstack/openstack-manuals
Code Issues Proposed changes
fad2bcd17b
openstack-manuals/doc/install-guide/section_neutron-controller-node.xml
Christian Berendt eb93b8bd46 [install-guide] change "API endpoints" to "API endpoint" 
An API endpoint on Keystone uses several URLs. We normally (not for
heat) only have one API endpoint for a service in the installation guide.

Change-Id: Idb22a6e0c06382e9e8069eed6e16e69c9c512bb3
2015-04-16 15:56:59 +02:00

456 lines
20 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 the OpenStack Networking (neutron) service,
you must create a database, service credentials, and API
endpoint.</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 service credentials, complete these steps:</para>
<substeps>
<step>
<para>Create the <literal>neutron</literal> user:</para>
<screen><prompt>$</prompt> <userinput>openstack user create --password-prompt neutron</userinput>
<computeroutput>User Password:
Repeat User Password:
+----------+----------------------------------+
| Field | Value |
+----------+----------------------------------+
| email | None |
| enabled | True |
| id | ab67f043d9304017aaa73d692eeb4945 |
| name | neutron |
| username | neutron |
+----------+----------------------------------+</computeroutput></screen>
</step>
<step>
<para>Add the <literal>admin</literal> role to the
<literal>neutron</literal> user:</para>
<screen><prompt>$</prompt> <userinput>openstack role add --project service --user neutron admin</userinput>
<computeroutput>+-------+----------------------------------+
| Field | Value |
+-------+----------------------------------+
| id | 1169d778631b4fd1aefd9d35314e1c56 |
| name | admin |
+-------+----------------------------------+</computeroutput></screen>
</step>
<step>
<para>Create the <literal>neutron</literal> service entity:</para>
<screen><prompt>$</prompt> <userinput>openstack service create --type network \
--description "OpenStack Networking" neutron</userinput>
<computeroutput>+-------------+----------------------------------+
| Field | Value |
+-------------+----------------------------------+
| description | OpenStack Networking |
| enabled | True |
| id | f71529314dab4a4d8eca427e701d209e |
| name | neutron |
| type | network |
+-------------+----------------------------------+</computeroutput></screen>
</step>
</substeps>
</step>
<step>
<para>Create the Networking service API endpoint:</para>
<screen><prompt>$</prompt> <userinput>openstack endpoint create \
--publicurl http://<replaceable>controller</replaceable>:9696 \
--adminurl http://<replaceable>controller</replaceable>:9696 \
--internalurl http://<replaceable>controller</replaceable>:9696 \
--region regionOne
network</userinput>
<computeroutput>+--------------+----------------------------------+
| Field | Value |
+--------------+----------------------------------+
| adminurl | http://controller:9696 |
| id | 04a7d3c1de784099aaba83a8a74100b3 |
| internalurl | http://controller:9696 |
| publicurl | http://controller:9696 |
| region | regionOne |
| service_id | f71529314dab4a4d8eca427e701d209e |
| service_name | neutron |
| service_type | network |
+--------------+----------------------------------+</computeroutput></screen>
</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 queue
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 queue, topology change notifications,
and plug-in.</para>
<note>
<para>Default configuration files vary by distribution. You might need
to add these sections and options rather than modifying existing
sections and options. Also, an ellipsis (...) in the configuration
snippets indicates potential default configuration options that you
should retain.</para>
</note>
<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> and
<literal>[oslo_messaging_rabbit]</literal> sections, configure
<application>RabbitMQ</application> message queue access:</para>
<programlisting language="ini">[DEFAULT]
...
rpc_backend = rabbit
[oslo_messaging_rabbit]
...
rabbit_host = <replaceable>controller</replaceable>
rabbit_userid = openstack
rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
<para>Replace <replaceable>RABBIT_PASS</replaceable> with the
password you chose for the <literal>openstack</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
auth_url = http://<replaceable>controller</replaceable>:35357
auth_plugin = password
project_domain_id = default
user_domain_id = default
project_name = service
username = neutron
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>
<note>
<para>Comment out or remove any other options in the
<literal>[keystone_authtoken]</literal> section.</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> and
<literal>[nova]</literal> sections, 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]
...
auth_url = http://<replaceable>controller</replaceable>:35357
auth_plugin = password
project_domain_id = default
user_domain_id = default
region_name = regionOne
project_name = service
username = nova
password = <replaceable>NOVA_PASS</replaceable></programlisting>
<para>Replace <literal>NOVA_PASS</literal> with the password
you chose for the <literal>nova</literal> user in the Identity
service.</para>
</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>,
<glossterm baseform="VLAN network">VLAN</glossterm>,
<glossterm>generic routing encapsulation (GRE)</glossterm>, and
<glossterm>virtual extensible LAN (VXLAN)</glossterm>
network type drivers, GRE tenant networks, and the OVS
mechanism driver:</para>
<programlisting language="ini">[ml2]
...
type_drivers = flat,vlan,gre,vxlan
tenant_network_types = gre
mechanism_drivers = openvswitch</programlisting>
<warning>
<para>Once you configure the ML2 plug-in, changing values in
the <literal>type_drivers</literal> option 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 on the controller
node 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 os="ubuntu;rhel;centos;fedora">
<para>Populate the database:</para>
<!-- FIXME: Change database version from 'head' to 'kilo' after
release. -->
<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 head" 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;opensuse;sles"><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></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><prompt>#</prompt> <userinput>systemctl enable neutron-server.service</userinput>
<prompt>#</prompt> <userinput>systemctl start neutron-server.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