In this article by James Denton, author of the book, Learning OpenStack, Networking (Neutron), we will create Neutron routers and attach them to networks. The Neutron L3 agent enables IP routing and NAT support for instances within the cloud by utilizing network namespaces to provide isolated routing instances. By creating networks and attaching them to routers, tenants can expose connected instances and their applications to the Internet.

The neutron-l3-agent service was installed on the controller node as part of the overall Neutron installation process.

(For more resources related to this topic, see here.)

Configuring the Neutron L3 agent

Before the neutron-l3-agent service can be started, it must be configured. Neutron stores the L3 agent configuration in the /etc/neutron/l3_agent.ini file. The most common configuration options will be covered here.

Defining an interface driver

Like previously installed agents, the Neutron L3 agent must be configured to use an interface driver that corresponds to the chosen networking plugin.

Using crudini, configure the Neutron L3 agent to use one of the following drivers:

For LinuxBridge:

# crudini --set /etc/neutron/l3_agent.ini DEFAULT interface_driver
neutron.agent.linux.interface.BridgeInterfaceDriver

For Open vSwitch:

# crudini --set /etc/neutron/l3_agent.ini DEFAULT interface_driver
neutron.agent.linux.interface.OVSInterfaceDriver

Setting the external network

The external network connected to a router is one that not only provides external connectivity to the router and the instances behind it, but also serves as the network from which floating IPs are derived. In Havana, each L3 agent in the cloud can be associated with only one external network. In Icehouse, L3 agents are capable of supporting multiple external networks.

To be eligible to serve as an external network, a provider network must have been configured with its router:external attribute set to true. In Havana, if more than one provider network has the attribute set to true, then the gateway_external_network_id configuration option must be used to associate an external network to the agent.

To define a specific external network, configure the gateway_external_network_id option as follows:

gateway_external_network_id = <UUID of eligible provider network>

In Havana, if this option is left empty, the agent will enforce that only a single external networks exists. The agent will automatically use the network for which the router:external attribute is set to true. The default configuration contains an empty or unset value and is sufficient for now.

Setting the external bridge

The L3 agent must be aware of how to connect the external interface of a router to the network. The external_network_bridge configuration option defines a bridge on the host in which the external interface will be connected.

In earlier releases of Havana, the default value of external_network_bridge was br-ex, a bridge expected to be configured manually outside of OpenStack and intended to be dedicated to the external network. As a result of the bridge not being fully managed by OpenStack, provider attributes of the network created within Neutron, including the segmentation ID, network type, and the provider bridge itself, are ignored.

To fully utilize a provider network and its attributes, the external_network_bridge configuration option should be set to an empty, or blank, value. By doing so, Neutron will adhere to the attributes of the network and place the external interface of routers into a bridge that it creates, along with a physical or virtual VLAN interface used to provide external connectivity. When using Open vSwitch, the external interface of the router is placed in the integration bridge and assigned to the appropriate local VLAN. With the LinuxBridge plugin, the external interface of routers is placed into a Linux bridge that corresponds to the external network.

Using crudini, set the external_network_bridge configuration option to an empty value as follows:

# crudini --set /etc/neutron/l3_agent.ini DEFAULT external_network_bridge

Enabling the metadata proxy

When Neutron routers are used as the gateway for instances, requests for metadata are proxied by the router and forwarded to the Nova metadata service. This feature is enabled by default and can be disabled by setting the enable_metadata_proxy value to false in the l3_agent.ini configuration file.

Starting the Neutron L3 agent

To start the neutron-l3-agent service and configure it to start at boot, issue the following commands on the controller node:

# service neutron-l3-agent start
# chkconfig neutron-l3-agent on

Verify the agent is running:

# service neutron-l3-agent status

The service should return an output similar to the following:

[root@controller neutron]# service neutron-l3-agent status
neutron-l3-agent (pid 13501) is running...

If the service remains stopped, troubleshoot any issues that may be found in the /var/log/neutron/l3-agent.log log file.

Router management in the CLI

Neutron offers a number of commands that can be used to create and manage routers. The primary commands associated with router management include:

router-create

router-delete

router-gateway-clear

router-gateway-set

router-interface-add

router-interface-delete

router-list

router-list-on-l3-agent

router-port-list

router-show

router-update

Creating routers in the CLI

Routers in Neutron are associated with tenants and are available for use only by users within the tenant that created them. As an administrator, you can create routers on behalf of tenants during the creation process.

To create a router, use the router-create command as follows:

Syntax: router-create [--tenant-id TENANT_ID]
[--admin-state-down] NAME

Working with router interfaces in the CLI

Neutron routers have two types of interfaces: gateway and internal. The gateway interface of a Neutron router is analogous to the WAN interface of a hardware router. It is the interface connected to an upstream device that provides connectivity to external resources. The internal interfaces of Neutron routers are analogous to the LAN interfaces of hardware routers. Internal interfaces are connected to tenant networks and often serve as the gateway for connected instances.

Attaching internal interfaces to routers

To create an interface in the router and attach it to a subnet, use the router-interface-add command as follows:

Syntax: router-interface-add <router-id> <INTERFACE>

In this case, INTERFACE is the ID of the subnet to be attached to the router.

In Neutron, a network may contain multiple subnets. It is important to attach the router to each subnet so that it properly serves as the gateway for those subnets.

Once the command is executed, Neutron creates a port in the database that is associated with the router interface. The L3 agent is responsible for connecting interfaces within the router namespace to the proper bridge.

Attaching a gateway interface to a router

The external interface of a Neutron router is referred to as the gateway interface. A router is limited to a single gateway interface. To be eligible for use as an external network that can be used for gateway interfaces, a provider network must have its router:external attribute set to true.

To attach a gateway interface to a router, use the router-gateway-set command as follows:

Syntax: router-gateway-set <router-id> <external-network-id> [--disable-snat]

The default behavior of a Neutron router is to source NAT all outbound traffic from instances that do not have a corresponding floating IP. To disable this functionality, append --disable-snat to the router-gateway-set command.

Listing interfaces attached to routers

To list the interfaces attached to routers, use the router-port-list command as follows:

Syntax: router-port-list <router-id>

The returned output includes the Neutron port ID, MAC address, IP address, and associated subnet of attached interfaces.

Deleting internal interfaces

To delete an internal interface from a router, use the router-interface-delete command as follows:

Syntax: router-interface-delete <router-id> <INTERFACE>

Here, INTERFACE is the ID of the subnet to be removed from the router. Deleting an interface from a router results in the associated Neutron port being removed from the database.

Clearing the gateway interface

Gateway interfaces cannot be removed from a router using the router-interface-delete command. Instead, the router-gateway-clear command must be used.

To clear the gateway of a router, use the router-gateway-clear command as follows:

Syntax: router-gateway-clear <router-id>

Neutron includes checks that will prohibit the clearing of a gateway interface in the event that floating IPs or other resources from the network are associated with the router.

Listing routers in the CLI

To display a list of existing routers, use the Neutron router-list command as follows:

Syntax: router-list [--tenant-id TENANT_ID]

The returned output includes the router ID, name, external gateway network, and the SNAT state.

Users will only see routers that exist in their tenant or project. When executed by an administrator, Neutron will return a listing of all routers across all tenants unless, the tenant ID is specified.

Displaying router attributes in the CLI

To display the attributes of a router, use the Neutron router-show command as follows:

Syntax: router-show <router id>

Among the output returned is the admin state, the external network, the SNAT state, and the tenant ID associated with the router.

Updating router attributes in the CLI

To update the attributes of a router, use the Neutron router-update command as follows:

Syntax: router-update <router id> [--admin-state-up]
[--routes destination=<network/cidr>,nexthop=<gateway_ip>]

The admin-state-up attribute is a Boolean, which when set to false, does not allow Neutron to update interfaces within the router. This includes not adding floating IPs or additional internal interfaces to the router. Setting the value to true will allow queued changes to be applied.

The routes option allows you to add static routes to the routing table of a Neutron router. To add static routes, use the following syntax:

Syntax: neutron router-update <router id> --routes type=dict list=true
destination=<network/cidr>,nexthop=<gateway_ip>

Adding static routes to a router is an undocumented and broken feature in Havana. In Havana, the command results in the route being added to the database and router show output, while not being added to the routing table. To resolve this, add the following line to the [DEFAULT] block of the /etc/neutron/l3_agent.ini configuration file:

root_helper = sudo neutron-rootwrap /etc/neutron/rootwrap.conf

Restart the neutron-l3-agent service for changes to take effect.

Deleting routers in the CLI

To delete a router, use the Neutron router-delete command as follows:

Syntax: router-delete <router id>

Before a router can be deleted, all floating IPs and internal interfaces associated with the router must be unassociated or deleted. This may require deleting instances or detaching connected interfaces from instances.

Network Address Translation

Network Address Translation (NAT) is a networking concept that was developed in the early 1990s in response to the rapid depletion of IP addresses throughout the world. Prior to NAT, every host connected to the Internet had a unique IP address.

OpenStack routers support two types of NAT:

one-to-one

many-to-one

A one-to-one NAT is a method in which one IP address is directly mapped to another. Commonly referred to as a static NAT, a one-to-one NAT is often used to map a unique public address to a privately addressed host. Floating IPs utilize one-to-one NAT concepts.

A many-to-one NAT is a method in which multiple addresses are mapped to a single address. A many-to-one NAT employs the use of port address translation (PAT). Neutron uses PAT to provide external access to instances behind the router when floating IPs are not assigned.

For more information on network address translation, please visit Wikipedia at http://en.wikipedia.org/wiki/Network_address_translation.

Floating IP addresses

Tenant networks, when attached to a Neutron router, are meant to utilize the router as their default gateway. By default, when a router receives traffic from an instance and routes it upstream, the router performs a port address translation and modifies the source address of the packet to appear as its own external interface address. This ensures that the packet can be routed upstream and returned to the router, where it will modify the destination address to be that of the instance that initiated the connection. Neutron refers to this type of behavior as Source NAT.

When users require direct inbound access to instances, a floating IP address can be utilized. A floating IP address in OpenStack is a static NAT that maps an external address to an internal address. This method of NAT allows instances to be reachable from external networks, such as the Internet. Floating IP addresses are configured on the external interface of the router that serves as the gateway for the instance, which is then responsible for modifying the source and/or destination address of packets depending on their direction.

In this article, we learned that Neutron routers being a core component of networking in OpenStack, provides tenants the flexibility to design the network to best suit their application.