The Neutron project provides virtual networking services among devices that are managed by the OpenStack compute service.
The Networking API v2.0 combines the Quantum API v1.1 with some essential Internet Protocol Address Management (IPAM) capabilities from the Melange API.
These IPAM capabilities enable you to:
Associate IP address blocks and other network configuration settings required by a network device, such as a default gateway and dns-servers settings, with an OpenStack Networking network.
Allocate an IP address from a block and associate it with a device that is attached to the network through an OpenStack Networking port.
To do this, the Networking API v2.0 introduces the subnet entity. A subnet can represent either an IP version 4 or version 6 address block. Each OpenStack Networking network commonly has one or more subnets. When you create a port on the network, an available fixed IP address is allocated to it from one the designated subnets for each IP version. When you delete the port, the allocated addresses return to the pool of available IPs on the subnet. Networking API v2.0 users can choose a specific IP address from the block or let OpenStack Networking choose the first available IP address.
![[Note]](../common/images/admon/note.png) | Note |
|---|---|
The Quantum API v1. |
| Term | Description | |||
| CRUD | Create, read, update, and delete (CRUD) are the basic functions of persistent storage in computer programming. | |||
| entity | Any piece of hardware or software that can connect to the network services provided by OpenStack Networking. An entity can use OpenStack Networking services by implementing a VIF. | |||
| IPAM | Internet Protocol Address Management (IPAM) is a means of planning, tracking, and managing the Internet Protocol (IP) address space that is used in a network. | |||
| layer-2 network | A virtual Ethernet network that is managed by the OpenStack Networking service. Currently, OpenStack Networking manages only Ethernet networks. | |||
| network | An isolated virtual layer-2 broadcast domain that is typically reserved for the tenant who created it unless the network is configured to be shared. Tenants can create multiple networks until they reach the thresholds specified by per-tenant quotas. | |||
| plug-in | A software component that implements Networking API v2.0. | |||
| port | A virtual switch port on a logical network switch. Virtual instances attach their interfaces into ports. The logical port also defines the MAC address and the IP addresses to be assigned to the interfaces plugged into them. When IP addresses are associated to a port, this also implies the port is associated with a subnet, as the IP address was taken from the allocation pool for a specific subnet. | |||
| subnet | An IP address block that can be used to assign IP addresses to virtual instances. Each subnet must have a CIDR and must be associated with a network. IPs can be either selected from the whole subnet CIDR or from allocation pools that can be specified by the user. | |||
| VM | A virtual machine (VM) is a completely isolated guest operating system installation within a normal host operating system. | |||
Use the Networking API v2.0 to manage the following entities:
Network. An isolated virtual layer-2 domain. A network can also be a virtual, or logical, switch. See the section called “Network”.
Subnet. An IP version 4 or version 6 address block from which IP addresses that are assigned to VMs on a specified network are selected. See the section called “Subnet”.
Port. A virtual, or logical, switch port on a specified network. See the section called “Port”.
These entities have auto-generated unique identifiers and support basic create, read, update, and delete (CRUD) functions with the POST, GET, PUT, and DELETE verbs.
A network is an isolated virtual layer-2 broadcast domain that is typically reserved for the tenant who created it unless you configure the network to be shared. Tenants can create multiple networks until the thresholds per-tenant quota is reached.
In the Networking API v2.0, the network is the main entity. Ports and subnets are always associated with a network.
The following table describes the attributes for network objects:
| Attribute | Type | Required | CRUD[a] | Default Value | Validation Constraints | Notes | |||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | uuid-str | N/A | R | generated | N/A | UUID for the network. | |||||||||||||||||||||||||||||||||||||||||||
| name | String | No | CRU | None | N/A | Human-readable name for the network. Might not be unique. | |||||||||||||||||||||||||||||||||||||||||||
| admin_state_up | Bool | No | CRU | true | {true|false} | The administrative state of network. If false (down), the network does not forward packets. | |||||||||||||||||||||||||||||||||||||||||||
| status | String | N/A | R | N/A | N/A | Indicates whether network is currently operational. Possible values include:
Plug-ins might define additional values. |
|||||||||||||||||||||||||||||||||||||||||||
| subnets | list(uuid-str) | No | R | Empty List | N/A | subnets associated with this network. | |||||||||||||||||||||||||||||||||||||||||||
| shared | Bool | No | CRU | False | { True | False } | Specifies whether the network resource can be accessed by any tenant or not. | |||||||||||||||||||||||||||||||||||||||||||
| tenant_id | uuid-str | No[b] | CR | N/A | No constraint | Owner of network. Only admin users can specify a tenant_id other than its own. | |||||||||||||||||||||||||||||||||||||||||||
[a]
[b] If OpenStack Networking is not
running with the Keystone Identity
service, the
| |||||||||||||||||||||||||||||||||||||||||||||||||
A subnet represents an IP address block that can be used to assign IP addresses to virtual instances. Each subnet must have a CIDR and must be associated with a network. IPs can be either selected from the whole subnet CIDR or from allocation pools that can be specified by the user.
A subnet can also optionally have a gateway, a list of dns name servers, and host routes. This information is pushed to instances whose interfaces are associated with the subnet.
| Attribute | Type | Required | CRUD[a] | Default Value | Validation Constraints | Notes | |||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | uuid-str | N/A | R | generated | N/A | UUID representing the subnet | |||||||||||||||||||||||||||||||||||||||||||
| network_id | uuid-str | Yes | CR | N/A | network this subnet is associated with. | ||||||||||||||||||||||||||||||||||||||||||||
| name | String | No | CRU | None | N/A | Human-readable name for the subnet. Might not be unique. | |||||||||||||||||||||||||||||||||||||||||||
| ip_version | int | Yes | CR | 4 | { 4 | 6 } | IP version | |||||||||||||||||||||||||||||||||||||||||||
| cidr | string | Yes | CR | N/A | valid cidr in the form <network_address>/<prefix> | cidr representing IP range for this subnet, based on IP version | |||||||||||||||||||||||||||||||||||||||||||
| gateway_ip | string | No | CRUD | first address in cidr | Valid IP address or null | default gateway used by devices in this subnet | |||||||||||||||||||||||||||||||||||||||||||
| dns_nameservers | list(str) | No | CRU | Empty list | No constraint | DNS name servers used by hosts in this subnet. | |||||||||||||||||||||||||||||||||||||||||||
| allocation_pools | list(dict) | No | CR | Every address in cidr, excluding gateway_ip if configured | star/end of range must be valid ip | Sub-ranges of cidr available for dynamic allocation to ports [ { "start": "10.0.0.2", "end": "10.0.0.254"} ] | |||||||||||||||||||||||||||||||||||||||||||
| host_routes | list(dict) | No | CRU | Empty List | [] | Routes that should be used by devices with IPs from this subnet (not including local subnet route). | |||||||||||||||||||||||||||||||||||||||||||
| enable_dhcp | Bool | No | CRU | True | { True | False } | Specifies whether DHCP is enabled for this subnet or not. | |||||||||||||||||||||||||||||||||||||||||||
| tenant_id | uuid-str | No[b] | CR | N/A | No constraint | Owner of network. Only admin users can specify a tenant_id other than its own. | |||||||||||||||||||||||||||||||||||||||||||
[a]
[b] If OpenStack Networking is not
running with the Keystone Identity
service, the
| |||||||||||||||||||||||||||||||||||||||||||||||||
A port represents a virtual switch port on a logical network switch. Virtual instances attach their interfaces into ports. The logical port also defines the MAC address and the IP address(es) to be assigned to the interfaces plugged into them. When IP addresses are associated to a port, this also implies the port is associated with a subnet, as the IP address was taken from the allocation pool for a specific subnet.
| Attribute | Type | Required | CRUD[a] | Default Value | Validation Constraints | Notes | |||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | uuid-str | N/A | R | generated | N/A | UUID for the port. | |||||||||||||||||||||||||||||||||||||||||||
| network_id | uuid-str | Yes | CR | N/A | existing network identifier | Network that this port is associated with. | |||||||||||||||||||||||||||||||||||||||||||
| name | String | No | CRU | None | N/A | Human-readable name for the port. Might not be unique. | |||||||||||||||||||||||||||||||||||||||||||
| admin_state_up | bool | No | CRU | true | {true|false} | Administrative state of port. If false (down), port does not forward packets. | |||||||||||||||||||||||||||||||||||||||||||
| status | string | N/A | R | N/A | N/A | Indicates whether network is currently operational. Possible values include:
Plug-ins might define additional values. |
|||||||||||||||||||||||||||||||||||||||||||
| mac_address | string | No | CR | generated | valid MAC in 6-octet form separated by colons | Mac address to use on this port. | |||||||||||||||||||||||||||||||||||||||||||
| fixed_ips | list(dict) | No | CRU | automatically allocated from pool | Valid IP address and existing subnet identifier | Specifies IP addresses for the port thus associating the port itself with the subnets where the IP addresses are picked from | |||||||||||||||||||||||||||||||||||||||||||
| device_id | str | No | CRUD | None | No constraint | identifies the device (e.g., virtual server) using this port. | |||||||||||||||||||||||||||||||||||||||||||
| device_owner | str | No | CRUD | None | No constraint | Identifies the entity (e.g.: dhcp agent) using this port. | |||||||||||||||||||||||||||||||||||||||||||
| tenant_id | uuid-str | No[b] | CR | N/A | No constraint | Owner of network. Only admin users can specify a tenant_id other than its own. | |||||||||||||||||||||||||||||||||||||||||||
| security_groups | list(dict) | No | CRUD | None | Existing security group IDs | Specifies the IDs of any security groups associated with a port. | |||||||||||||||||||||||||||||||||||||||||||
[a]
[b] If OpenStack Networking is not
running with the Keystone Identity
service, the
| |||||||||||||||||||||||||||||||||||||||||||||||||
The high-level task flow for OpenStack Networking involves creating a network, associating a subnet with that network, and booting a VM that is attached to the network. Clean-up includes deleting the VM, deleting any ports associated with the network, and deleting the networks. OpenStack Networking deletes any subnets associated with the deleted network.
To use OpenStack Networking - high-level task flow
Create a network
The tenant creates a network.
For example, the tenant creates the
net1network. Its ID is net1_id.Associate a subnet with the network
The tenant associates a subnet with that network.
For example, the tenant associates the
10.0.0.0/24subnet with thenet1network.Boot a VM and attach it to the network
The tenant boots a virtual machine (VM) and specifies a single NIC that connects to the network.
The following examples use the nova client to boot a VM.
In the first example, Nova contacts OpenStack Networking to create the NIC and attach it to the
net1network, with the ID net1_id:$ nova boot <server_name> --image <image> --flavor <flavor> --nic net-id=<net1_id>
In a second example, you first create the
port1, port and then you boot the VM with a specified port. OpenStack Networking creates a NIC and attaches it to theport1port, with the ID port1_id:$ nova boot <server_name> --image <image> --flavor <flavor> --nic port-id=<port1_id>
OpenStack Networking chooses and assigns an IP address to the
port1port.For more information about the nova boot command, enter:
$ nova help boot
Delete the VM
The tenant deletes the VM.
Nova contacts OpenStack Networking and deletes the
port1port.The allocated IP address is returned to the pool of available IP addresses.
Delete any ports
If the tenant created any ports and associated them with the network, the tenant deletes the ports.
Delete the network
The tenant deletes the network. This operation deletes an OpenStack Networking network and its associated subnets provided that no port is currently configured on the network.
Virtual networking services are implemented through a plug-in. A plug-in can use different techniques and technologies to provide isolated virtual networks to tenants. A plug-in also provides other services, such as IP address management. Because each plug-in implements all the operations included in Networking API v2.0, do not be concerned about which plug-in is used.
However, some plug-ins might expose additional capabilities through API extensions, which this document discusses. For more information about the extensions exposed by a particular plug-in, see the plug-in documentation.
