Neutron API Basics

In this article by James Denton, the author of the book OpenStack Networking Essentials, you can see that Neutron is a virtual networking service that allows users to define network connectivity and IP addressing for instances and other cloud resources using an application programmable interface (API). The Neutron API is made up of core elements that define basic network architectures and extensions that extend base functionality. Neutron accomplishes this by virtue of its data model that consists of networks, subnets, and ports. These objects help define characteristics of the network in an easily storable format.

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

These core elements are used to build a logical network data model using information that corresponds to layers 1 through 3 of the OSI model, shown in the following screenshot:

For more information on the OSI model, check out the Wikipedia article at https://en.wikipedia.org/wiki/OSI_model.

Neutron uses plugins and drivers to identify network features and construct the virtual network infrastructure based on information stored in the database. A core plugin, such as the Modular Layer 2 (ML2) plugin included with Neutron, implements the core Neutron API and is responsible for adapting the logical network described by networks, ports, and subnets into something that can be implemented by the L2 agent and IP address management system running on the hosts. The extension API, provided by service plugins, allows users to manage the following resources, among others:

  • Security groups
  • Quotas
  • Routers
  • Firewalls
  • Load balancers
  • Virtual private networks

Neutron's extensibility means that new features can be implemented in the form of extensions and plugins that extend the API without requiring major changes. This allows vendors to introduce features and functionality that would otherwise not be available with the base API.

The following diagram demonstrates at a high level how the Neutron API server interacts with the various plugins and agents responsible for constructing the virtual and physical network across the cloud:

The previous diagram demonstrates the interaction between the Neutron API service, Neutron plugins and drivers, and services such as the L2 and L3 agents. As network actions are performed by users via the API, the Neutron server publishes messages to the message queue that are consumed by agents. L2 agents build and maintain the virtual network infrastructure, while L3 agents are responsible for building and maintaining Neutron routers and associated functionality.

The Neutron API specifications can be found on the OpenStack wiki at https://wiki.openstack.org/wiki/Neutron/APIv2-specification. In the next few sections, we will look at some of the core elements of the API and the data models used to represent those elements.

Networks

A network is the central object of the Neutron v2.0 API data model and describes an isolated L2 segment. In a traditional infrastructure, machines are connected to switch ports that are often grouped together into virtual local area networks (VLANs) identified by unique IDs. Machines in the same network or VLAN can communicate with one another but cannot communicate with other networks in other VLANs without the use of a router. The following diagram demonstrates how networks are isolated from one another in a traditional infrastructure:

Neutron network objects have attributes that describe the network type and the physical interface used for traffic. The attributes also describe the segmentation ID used to differentiate traffic between other networks connected to virtual switches on the underlying host. The following diagram shows how a Neutron network describes various Layer 1 and Layer 2 attributes:

Traffic between instances on different hosts requires underlying connectivity between the hosts. This means that the hosts must reside on the same physical switching infrastructure so that VLAN-tagged traffic can pass between them. Traffic between hosts can also be encapsulated using L2-in-L3 technologies such as GRE or VXLAN. Neutron supports multiple L2 methods of segmenting traffic, including using 802.1q VLANs, VXLANs, GRE, and more, depending on the plugin and configured drivers and agents. Devices in the same network are in the same broadcast domain, even though they may reside on different hosts and attach to different virtual switches. Neutron network attributes are very important in defining how traffic between virtual machine instances should be forwarded between hosts.

Network attributes

The following table describes base attributes associated with network objects, and more details can be found at the Neutron API specifications wiki referenced earlier in this article:

Attribute

Type

Required

Default

Notes

id

uuid-str

N/A

Auto generated

The UUID for the network

name

string

no

None

The human-readable name for the network

admin_state_up

boolean

no

True

The administrative state of the network

status

string

N/A

Null

Indicates whether the network is currently operational

subnets

list

no

Empty list

The subnets associated with the network

shared

boolean

no

False

Specifies whether the network can be accessed by any tenant

tenant_id

uuid-str

no

N/A

The owner of the network

Networks are typically associated with tenants or projects and are usable by any user that is a member of the same tenant or project. Networks can also be shared with all other projects or a subnet of projects using Neutron's role-based access control (RBAC) functionality.

Neutron RBAC first became available in the Liberty release of OpenStack. For more information on using the RBAC features, check out my blog at the following URL:

https://developer.rackspace.com/blog/A-First-Look-at-RBAC-in-the-Liberty....

Provider attributes

One of the earliest extensions to the Neutron API is known as the provider extension. The provider network extension maps virtual networks to physical networks by adding additional network attributes that describe the network type, segmentation ID, and physical interface. The following table shows various provider attributes and their associated values:

Attribute

Type

Required

Options

Default

Notes

provider:network_type

string

yes

vlan,flat,local,

vxlan,gre

Based on the configuration

 

provider:segmentation_id

int

optional

Depends on the network type

Based on the configuration

The segmentation ID range varies among L2 technologies

provider:physical_network

string

optional

Provider label

Based on the configuration

This specifies the physical interface used for traffic (flat or VLAN-only)

All networks have provider attributes. However, because provider attributes specify particular network configuration settings and mappings, only users with the admin role can specify them when creating networks. Users without the admin role can still create networks, but the Neutron server, not the user, will determine the type of network created and any corresponding interface or segmentation ID.

Additional attributes

The external-net extension adds an attribute to networks that is used to determine whether or not the network can be used as the external, or gateway, network for a Neutron router. When set to true, the network becomes eligible for use as a floating IP pool when attached to routers.

Using the Neutron router-gateway-set command, routers can be attached to external networks. The following table shows the external network attribute and its associated values:

Attribute

Type

Required

Default

Notes

router:external

Boolean

no

false

When true, the network is eligible for use as a floating IP pool when attached to a router

Subnets

In the Neutron data model, a subnet is an IPv4 or IPv6 address block from which IP addresses can be assigned to virtual machine instances and other network resources. Each subnet must have a subnet mask represented by a classless inter-domain routing (CIDR) address and must be associated with a network, as shown here:

In the preceding diagram, three isolated VLAN networks each have a corresponding subnet. Instances and other devices cannot be attached to networks without an associated subnet. Instances connected to a network can communicate among one another but are unable to connect to other networks or subnets without the use of a router. The following diagram shows how a Neutron subnet describes various Layer 3 attributes in the OSI model:

When creating subnets, users can specify IP allocation pools that limit which addresses in the subnet are available for allocation. Users can also define a custom gateway address, a list of DNS servers, and individual host routes that can be pushed to virtual machine instances using DHCP.

The following table describes attributes associated with subnet objects:

Attribute

Type

Required

Default

Notes

id

uuid-str

n/a

Auto Generated

The UUID for the subnet

network_id

uuid-str

Yes

N/A

The UUID of the associated network

name

string

no

None

The human-readable name for the subnet

ip_version

int

Yes

4

IP version 4 or 6

cidr

string

Yes

N/A

The CIDR address representing the IP address range for the subnet

gateway_ip

string or null

no

First address in CIDR

The default gateway used by devices in the subnet

dns_nameservers

list(str)

no

None

The DNS name servers used by hosts in the subnet

allocation_pools

list(dict)

no

Every address in the CIDR (excluding the gateway)

The subranges of the CIDR available for dynamic allocation.

tenant_id

uuid-str

no

N/A

The owner of the subnet

enable_dhcp

boolean

no

True

This indicates whether or not DHCP is enabled for the subnet

host_routes

list(dict)

no

N/A

Additional static routes

Ports

In the Neutron data model, a port represents a switch port on a logical switch that spans the entire cloud and contains information about the connected device. Virtual machine interfaces (VMIFs) and other network objects, such as router and DHCP server interfaces, are mapped to Neutron ports. The ports define both the MAC address and the IP address to be assigned to the device associated with them. Each port must be associated with a Neutron network.

The following diagram shows how a port describes various Layer 2 attributes in the OSI model:

The following table describes attributes associated with port objects:

Attribute

Type

Required

Default

Notes

id

uuid-str

n/a

Auto generated

The UUID for the subnet

network_id

uuid-str

Yes

N/A

The UUID of the associated network

name

string

no

None

The human-readable name for the subnet

admin_state_up

Boolean

no

True

The administrative state of the port

status

string

N/A

N/A

The current status of the port (for example, ACTIVE, BUILD, or DOWN)

mac_address

string

no

Auto generated

The MAC address of the port

fixed_ips

list(dict)

no

Auto allocated

The IP address(es) associated with the port

device_id

string

no

None

The instance ID or other resource associated with the port

device_owner

string

no

None

 

tenant_id

uuid-str

no

ID of tenant adding resource

The owner of the port

When Neutron is first installed, no ports exist in the database. As networks and subnets are created, ports may be created for each of the DHCP servers reflected by the logical switch model, seen here:

As instances are created, a single port is created for each network interface attached to the instance, as shown here:

A port can only be associated with a single network. Therefore, if an instance is connected to multiple networks, it will be associated with multiple ports. As instances and other cloud resources are created, the logical switch may scale to hundreds or thousands of ports over time, as shown in the following diagram:

There is no limit to the number of ports that can be created in Neutron. However, quotas exist that limit tenants to a small number of ports that can be created. As the number of Neutron ports scale out, the performance of the Neutron API server and the implementation of networking across the cloud may degrade over time. It's a good idea to keep quotas in place to ensure a high-performing cloud, but the defaults and subsequent quota increases should be kept reasonable.

The Neutron workflow

In the standard Neutron workflow, networks must be created first, followed by subnets and then ports. The following sections describe the workflows involved with booting and deleting instances.

Booting an instance

Before an instance can be created, it must be associated with a network that has a corresponding subnet or a precreated port that is associated with a network. The following process documents the steps involved in booting an instance and attaching it to a network:

  1. The user creates a network.
  2. The user creates a subnet and associates it with the network.
  3. The user boots a virtual machine instance and specifies the network.
  4. Nova interfaces with Neutron to create a port on the network.
  5. Neutron assigns a MAC address and IP address to the newly created port using attributes defined by the subnet.
  6. Nova builds the instance's libvirt XML file containing local network bridge and MAC address information and starts the instance.
  7. The instance sends a DHCP request during boot, at which point the DHCP server responds with the IP address corresponding to the MAC address of the instance.

If multiple network interfaces are attached to an instance, each network interface will be associated with a unique Neutron port and may send out DHCP requests to retrieve their respective network information.

How the logical model is implemented

Neutron agents are services that run on network and compute nodes and are responsible for taking information described by networks, subnets, and ports and using it to implement the virtual and physical network infrastructure.

In the Neutron database, the relationship between networks, subnets, and ports can be seen in the following diagram:

This information is then implemented on the compute node by way of virtual network interfaces, virtual switches or bridges, and IP addresses, as shown in the following diagram:

In the preceding example, the instance was connected to a network bridge on a compute node that provides connectivity from the instance to the physical network. For now, it's only necessary to know how the data model is implemented into something that is usable.

Deleting an instance

The following process documents the steps involved in deleting an instance:

  1. The user destroys virtual machine instance.
  2. Nova interfaces with Neutron to destroy the ports associated with the instances.
  3. Nova deletes local instance data.
  4. The allocated IP and MAC addresses are returned to the pool.

When instances are deleted, Neutron removes all virtual network connections from the respective compute node and removes corresponding port information from the database.

Summary

In this article, we looked at the basics of the Neutron API and its data model made up of networks, subnets, and ports. These objects were used to describe in a logical way how the virtual network is architected and implemented across the cloud.

Resources for Article:


Further resources on this subject:


You've been reading an excerpt of:

OpenStack Networking Essentials

Explore Title
comments powered by Disqus