Jump to: navigation, search

Difference between revisions of "Neutron/APIv2-specification"

m (High-level flow)
 
(34 intermediate revisions by 11 users not shown)
Line 1: Line 1:
__NOTOC__
+
 
= Quantum v2 API =
+
= Neutron v2 API =
 +
This page is a draft spec and may not reflect the actual implementation.
 +
 
 +
Refer to http://developer.openstack.org/api-ref-networking-v2.html for the latest.
 +
 
 +
__TOC__
  
 
== Overview ==
 
== Overview ==
 +
Neutron is a project to provide virtual networking services between devices managed by the [[OpenStack]] compute service.  This document presents and discusses version 2.0 of the Neutron API. For more information on the Neutron project, and additional documentation, please visit http://wiki.openstack.org/Neutron, and docs.openstack.org. We welcome feedback, comments, and bug reports at https://bugs.launchpad.net/neutron.
  
Quantum is a project to provide virtual networking services between devices managed by the [[OpenStack]] compute service.  
+
The v2.0 API represents a combination of the [http://docs.openstack.org/api/openstack-network/1.0/content/ Quantum v1.1 API] with some of the most essential IPAM capabilities from the [http://melange.readthedocs.org/en/latest/apidoc.html Melange API] .  These IPAM capabilities focus on being able to associate IP address blocks and other network configuration required by a network device (e.g., default gateway, dns-servers) with a Neutron Network, and then being able to allocate an IP address out of such a block and associate it with a device that is attached to the network via a Neutron Port.
This document presents and discusses version 2.0 of the Quantum API. For more information on the Quantum project, and additional documentation, please visit http://wiki.openstack.org/Quantum, and docs.openstack.org.
 
We welcome feedback, comments, and bug reports at bugs.launchpad.net/Quantum.
 
  
The v2.0 API represents a combination of the [http://docs.openstack.org/api/openstack-network/1.0/content/ Quantum v1.1 API] with some of the most essential IPAM capabilities from the [http://melange.readthedocs.org/en/latest/apidoc.html Melange API] These IPAM capabilities focus on being able to associate IP address blocks and other network configuration required by a network device (e.g., default gateway, dns-servers) with a Quantum Network, and then being able to allocate an IP address out of such a block and associate it with a device that is attached to the network via a Quantum Port.
+
The v2.0 API does this by introducing a new entity, called a Subnet.  Subnets can represent the binding of either a IPv4 or IPv6 address block to a previously created Quantum network, and each Neutron Network commonly has one or more subnetsWhen a port is created on the network, by default it will be allocated an available fixed IP address out of one the designated subnets for each IP version.  When the Port is destroyed, the allocated addresses return to the pool of available IPs on the subnet. Users of the Neutron API can either choose a specific IP address from the block, or let Neutron choose the first available IP address.
  
The v2.0 API does this by introducing a new enity, called a Subnet.  Subnets can represent either a v4 or v6 address block, and each Quantum Network commonly has one or more subnets.  When a port is created on the network, by default it will be allocated an available fixed IP address out of one the designated subnets for each IP version.  When the Port is destroyed, the allocated addresses return to the pool of available IPs on the subnet. Users of the Quantum API can either choose a specific IP address from the block, or let Quantum choose the first available IP address.
+
''Please note that version 1.x of the Neutron API has been removed from the source code tree. In order to use v1.x API, an earlier release of Neutron should be installed.''
 
 
''Please note that version 1.x of the Quantum API has been removed from the source code tree. In order to use v1.x API, an earlier release of Quantum should be installed.''
 
  
 
=== High-level flow ===
 
=== High-level flow ===
 
 
* Tenant creates a network (e.g., "net1")
 
* Tenant creates a network (e.g., "net1")
* Tenant associates a subnet with that network (e.g., "10.0.0.0/24")  
+
* Tenant creates a subnet (e.g., "10.0.0.0/24"), which implicitly associates the address space with that network. This association creates a binding of the address space to the previously created network. While it is common to say, that a subnet is represented by an IPv4 or IPv6 address range, the address range alone is not a subnet. Rather it is the binding of the address space to the network, which creates the subnet.
 
* Tenant boots a VM, specifying a single NIC connected to "net1" (e.g.: nova boot --image <image_name> --nic net-id=<id_of_net1> <server_name>)
 
* Tenant boots a VM, specifying a single NIC connected to "net1" (e.g.: nova boot --image <image_name> --nic net-id=<id_of_net1> <server_name>)
* Nova contacts Quantum and creates a port1 on net1.
+
* Nova contacts Neutron and creates a port1 on net1.
* Quantum assigns an Ip to port1 is assigned IP. (The IP is chosen by Quantum)
+
* Neutron assigns an IP to port1 is assigned IP. (The IP is chosen by Neutron)
 
* Tenant destroys VM.
 
* Tenant destroys VM.
* Nova contacts Quantum and destroys port1. Allocated IP is returned to the pool of available IP address.
+
* Nova contacts Neutron and destroys port1. Allocated IP is returned to the pool of available IP address.
  
 
=== The Plugin ===
 
=== The Plugin ===
 
+
While the Neutron API represents the interface of the virtual network service to users and other services, these network services are implemented by a component called "Plugin". Plugins may adopt different techniques and technologies for providing isolated virtual networks to tenant, as well as providing other services such as IP address management. Users should not be concerned about the particular plugin employed as far as the API discussed in this document is concerned, as every plugin will implement all the operations included in the Neutron v2 API.
While the Quantum API represents the interface of the virtual network service to users and other services, these network services are implemented by a component called "Plugin". Plugin may adopt different techniques and technologies for providing isolated virtual networks to tenant, as well as providing other services such as IP address management. User should not be concerned about the particular plugin employed as far as the API discussed in this document is concerned, as every plugin will implement all the operations included in the Quantum v2 API.
 
  
 
However, some plugins might expose additional capabilities through API extensions, discussed later in this document. For more information about the extensions exposed by a particular plugin, please refer to the plugin documentation.
 
However, some plugins might expose additional capabilities through API extensions, discussed later in this document. For more information about the extensions exposed by a particular plugin, please refer to the plugin documentation.
  
 
== Concepts ==
 
== Concepts ==
 +
The Neutron v2 API manages three kind of entities:
  
The Quantum v2 API manages three kind of entities:
+
* '''Network''', representing isolated virtual Layer-2 domains; a network can also be regarded as a virtual (or logical) switch;
* '''Network''', representing isolated virtual Layer-2 domains; a network can als regarded as a virtual (or logical) switch;
 
 
* '''Subnet''', representing IPv4 or IPv6 address blocks  from which IPs to be assigned to VMs on a given network are selected.
 
* '''Subnet''', representing IPv4 or IPv6 address blocks  from which IPs to be assigned to VMs on a given network are selected.
 
* '''Port''', representing virtual (or logical) switch ports on a given network.
 
* '''Port''', representing virtual (or logical) switch ports on a given network.
Line 40: Line 40:
  
 
=== Network ===
 
=== Network ===
 +
A network is a virtual isolated layer-2 broadcast domain which is typically reserved to the tenant who created it, unless the network has been explicitly configured to be shared. Tenants can create multiple networks, until they reach the thresholds specified by per-tenant Quotas (see next chapter for more details).  The network is the principal entity for the Neutron API. Ports and subnets must always be associated with a network. The following table describes the attributes of network objects. For each attribute, the CRUD column should be read as follows:
  
A network is a virtual isolated layer-2 broadcast domain which is typically reserved to the tenant who created it, unless the network has been explicitly configured to be shared.
 
Tenants can create multiple networks, until they reach the thresholds specified by per-tenant Quotas (see next chapter for more details).
 
The network is the principal entity for the Quantum API. Ports and subnets must always be associated with a network.
 
The following table describes the attributes of network objects. For each attribute, the CRUD column should be read as follows:
 
 
* C - the attribute can be used in '''create''' operations;
 
* C - the attribute can be used in '''create''' operations;
 
* R - the attribute is returned in the response for '''show''' or '''list''' operations;
 
* R - the attribute is returned in the response for '''show''' or '''list''' operations;
Line 51: Line 48:
  
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Attribute  
+
|<style="font-weight:bold;">|Attribute  
| Type  
+
|<style="font-weight:bold;">|Type  
| Required  
+
|<style="font-weight:bold;">|Required  
| CRUD  
+
|<style="font-weight:bold;">|CRUD  
| Default  Value  
+
|<style="font-weight:bold;">|Default  Value  
| Validation Constraints  
+
|<style="font-weight:bold;">|Validation Constraints  
 
|-
 
|-
 
| id  
 
| id  
 
| uuid-str  
 
| uuid-str  
| N/A  
+
| N/A  
| R
+
| CR
| generated
+
| Generated
| N/A
+
| UUID_PATTERN
 
|-
 
|-
 
| name  
 
| name  
| String  
+
| String  
| No  
+
| No  
| CRU  
+
| CRU  
| None  
+
| None  
| N/A  
+
| N/A  
 
|-
 
|-
 
| admin_state_up  
 
| admin_state_up  
| Bool  
+
| Bool  
| No  
+
| No  
 
| CRU  
 
| CRU  
| True  
+
| True  
| { True | False }  
+
| <nowiki>{ True | False }</nowiki>
 
|-
 
|-
 
| status  
 
| status  
| String  
+
| String  
| N/A  
+
| N/A  
| R  
+
| R  
| N/A  
+
| N/A  
| N/A  
+
| N/A  
 
|-
 
|-
 
| subnets  
 
| subnets  
| list(uuid-str)  
+
| list(uuid-str)  
| No  
+
| No  
| R  
+
| R  
| Empty List  
+
| Empty List  
| N/A  
+
| N/A  
 
|-
 
|-
| permissions
+
| shared
|   octal(3)
+
| Bool
| No  
+
| No  
| CR**
+
| CRU
| rw- --- ---
+
| False
| 3-octal digit string or permission string in the rwxrwxrwx form***
+
| <nowiki>{ True | False }</nowiki>
 
|-
 
|-
 
| tenant_id  
 
| tenant_id  
| uuid-str  
+
| uuid-str  
| No*  
+
| No*  
| CR  
+
| CR  
| N/A  
+
| N/A  
| UUID_PATTERN
+
| N/A
 
|}
 
|}
  
 
=== Subnet ===
 
=== Subnet ===
 +
A subnet represents an IP address block that can be used for assigning 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 represent an IP address block that can be used for assigning IP address to virtual instances. Each subnet must have a CIDR and must be associated with a network.
+
A subnet can also optionally have a gateway, a list of DNS name servers, and host routes. All this information will then be pushed to instances whose interfaces are associated with the subnet.
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. All this information will then be pushed to instances whose interfaces are associated with the subnet.
 
 
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| attribute
+
|<style="font-weight:bold;">|Attribute
| Type  
+
|<style="font-weight:bold;">|Type  
| Required  
+
|<style="font-weight:bold;">|Required  
| CRUD  
+
|<style="font-weight:bold;">|CRUD  
| Default  
+
|<style="font-weight:bold;">|Default  
| Validation Constraints  
+
|<style="font-weight:bold;">|Validation Constraints  
 
|-
 
|-
 
| id  
 
| id  
 
| uuid-str  
 
| uuid-str  
| N/A  
+
| N/A  
| R
+
| CR
| generated
+
| Generated
| N/A  
+
| UUID_PATTERN
 +
|-
 +
| name
 +
| String
 +
| No
 +
| CRU
 +
| None
 +
| N/A  
 
|-
 
|-
 
| network_id  
 
| network_id  
 
| uuid-str  
 
| uuid-str  
| Yes  
+
| Yes  
 
| CR  
 
| CR  
| N/A
+
| Generated
 +
| Existing network identifier.
 
|-
 
|-
 
| ip_version  
 
| ip_version  
| int
+
| int  
| Yes  
+
| Yes  
| CR  
+
| CR  
| 4  
+
| 4  
| { 4 | 6 }  
+
| <nowiki>{ 4 | 6 }</nowiki>
 
|-
 
|-
 
| cidr  
 
| cidr  
 
| string  
 
| string  
| Yes
+
| Yes  
| CR  
+
| CR  
| N/A  
+
| N/A  
| valid cidr in the form <network_address>/<prefix>  
+
| Valid CIDR in the form <network_address>/<prefix>  
 
|-
 
|-
 
| gateway_ip  
 
| gateway_ip  
| string  
+
| string or null
 
| No  
 
| No  
 
| CRUD  
 
| CRUD  
| first address in ''cidr''  
+
| First address in ''CIDR''  
| Valid IP address  
+
| Valid IP address or null
 
|-
 
|-
 
| dns_nameservers  
 
| dns_nameservers  
| list(str)  
+
| list(str)  
| No  
+
| No  
 
| CRU  
 
| CRU  
| None  
+
| None  
| No constraint
+
| Configurable maximum amount of nameservers per subnet. The default is 5.
 
|-
 
|-
 
| allocation_pools  
 
| allocation_pools  
| list(dict)  
+
| list(dict)  
| No  
+
| No  
 
| CR  
 
| CR  
| Every address in ''cidr'', excluding ''gateway_ip'' if configured  
+
| Every address in CIDR, excluding ''gateway IP'' if configured  
| star/end of range must be valid ip
+
| Start/end of range must be valid IP
 
|-
 
|-
 
| host_routes  
 
| host_routes  
 
| list(dict)  
 
| list(dict)  
| No  
+
| No  
 
| CRU  
 
| CRU  
| default route to gateway_ip  
+
| Default route to gateway_ip  
| ''TBD''  
+
| {'destination': <CIDR>, "nexthop": <valid IP address>}. Configurable maximum amount of routes per subnet. The default is 20.
 +
|-
 +
| enable_dhcp
 +
| Bool
 +
| No
 +
| CRU
 +
| True
 +
| <nowiki>{ True | False }</nowiki>
 
|-
 
|-
 
| tenant_id  
 
| tenant_id  
| uuid-str  
+
| uuid-str  
| No*  
+
| No*  
| CR  
+
| CR  
| N/A  
+
| N/A  
| UUID_PATTERN
+
| N/A
 
|}
 
|}
  
 
=== Port ===
 
=== Port ===
 
+
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.
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.
 
 
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Attribute  
+
|<style="font-weight:bold;">|Attribute  
| Type  
+
|<style="font-weight:bold;">|Type  
| Required  
+
|<style="font-weight:bold;">|Required  
 +
|<style="font-weight:bold;">|CRUD
 +
|<style="font-weight:bold;">|Default
 +
|<style="font-weight:bold;">|Validation Constraints
 +
|-
 +
| id
 +
| uuid-str
 +
| N/A
 +
| CR
 +
| Generated
 +
| UUID_PATTERN
 +
|-
 +
| name
 +
| String
 +
| No
 
| CRU  
 
| CRU  
| Default
+
| None
| Validation Constraints
+
| N/A
 
|-
 
|-
| id
+
| network_id
| uuid-str  
+
| uuid-str  
| N/A
+
| Yes
| R
+
| CR
| generated
+
| N/A  
N/A  
+
| Existing network identifier.
 
|-
 
|-
| network_id
+
| admin_state_up  
|  uuid-str
+
| bool  
|  Yes
+
| No  
|  CR
 
|  N/A
 
|  existing network identifier
 
|-
 
admin_state_up  
 
| bool  
 
| No  
 
 
| CRU  
 
| CRU  
| True  
+
| True  
| { True | False }  
+
| <nowiki>{ True | False }</nowiki>
 
|-
 
|-
| status  
+
| status  
| string  
+
| string  
| N/A  
+
| N/A  
 
| R  
 
| R  
| N/A  
+
| N/A  
| N/A  
+
| N/A  
 
|-
 
|-
| mac_address  
+
| mac_address  
| string  
+
| string  
| No  
+
| No  
| CR  
+
| CR  
| generated
+
| Generated
| valid MAC in 6-octet form separated by colons  
+
| Valid MAC in 6-octet form separated by colons.
 
|-
 
|-
| fixed_ips  
+
| fixed_ips  
| list(dict)  
+
| list(dict)  
| No  
+
| No  
| CRU  
+
| CRU  
| automatically allocated from pool  
+
| Automatically allocated from pool.
| Valid IP address and existing subnet identifier  
+
| Valid IP address and existing subnet identifier.
 
|-
 
|-
| host_routes
+
| device_id
| list(dict)
+
| str
| No  
+
| No  
| CR
+
| CRUD
| Empty list
+
| None
| ''TBD''
+
| No constraint
 
|-
 
|-
| device_id
+
| device_owner
 
| str  
 
| str  
| No  
+
| No  
| CRUD  
+
| CRUD  
| None  
+
| None  
| No constraint  
+
| No constraint  
 
|-
 
|-
| tenant_id  
+
| tenant_id  
| uuid-str  
+
| uuid-str  
| No*  
+
| No*  
| CR  
+
| CR  
| N/A  
+
| N/A  
| UUID_PATTERN
+
| N/A
 
|}
 
|}
  
* The ''tenant_id'' attribute is mandatory if Quantum is not running with the Keystone Identity service
+
<nowiki>*</nowiki> The ''tenant_id'' attribute is mandatory if Neutron is not running with the Keystone Identity service
* * The Quantum API currently ignores ''group'' permissions, and ''executable'' bits. Write access to ''world'', even if granted by the user, is currently ignored by the Quantum API. The full permission mask has been provided for compatibility with future implementations.
 
* ** Quantum API also allows the symbolic string ''private'' and ''public'' for the permissions string. Private corresponds to 0600 or rw- --- ---, whereas Public corresponds to 0644 or rw-r--r--.
 
  
 
== General API information ==
 
== General API information ==
 +
=== Authentication and authorization ===
 +
Neutron uses the Keystone identity service (http://keystone.openstack.org) as the default authentication service.  When keystone is enabled Users submitting requests to the Neutron service must provide an authentication token in '''X-Auth-Token''' request header. The aforementioned token should have been obtained by authenticating with the keystone endpoint. For more information concerning authentication with Keystone, please refer to the Keystone documentation. When keystone is enabled, it is not mandatory to specify tenant_id for resources in '''create''' requests, as the tenant identifier will be derived from the Authentication token. Please note that the default authorization settings only allow administrative users to create resources on behalf of a different tenant.
 +
 +
Neutron uses information received from Keystone to authorize user requests. Neutron handles two kind of authorization policies:
 +
* Operation-based: policy specifying access criteria for specific operations, possibly with fine-grained control over specific attributes
 +
* Resource-based: whether access to specific resource might be granted or not according to the permissions configured for the resource (currently available only for the '''network''' resource)
 +
 +
The actual authorization policies enforced in Neutron might vary from deployment to deployment.
 +
 +
=== Request and Response types ===
 +
The [[OpenStack]] Neutron API supports the JSON data format. The format for both the request and the response can be specified either using the Accept header or adding the .json extension to the request URI.
 +
 +
'''Example: Request/Response with Headers: JSON'''
 +
 +
Request:
 +
 +
 +
<pre><nowiki>
 +
POST /v1.0/tenants/tenantX/networks HTTP/1.1
 +
Host 127.0.0.1:9696
 +
Content-Type application/json
 +
Accept application/json
 +
Content-Length 57
  
=== Authentication and authorization ===
+
{
 +
"network":
 +
    {
 +
      "name": "net-name",
 +
      "admin_state_up": true
 +
    }
 +
}
 +
</nowiki></pre>
  
Quantum uses the Keystone identity service (openstack.keystone.org) as the default authentication service.
+
Response:
When keystone is enabled Users submitting requests to the Quantum service must provide an authentication token in '''X-Auth-Token''' request header.
 
The aforementioned token should have been obtained by authenticating with the keystone endpoint. For more information concerning authentication with Keystone, please refer to the Keystone documentation.
 
When keystone is enabled, it is not mandatory to specify tenant_id for resources in '''create''' requests, as the tenant identifier will be derived from the Authentication token. Please note that the default authorization settings only allow administrative users to create resources on behalf of a different tenant.
 
  
Quantum uses information received from Keystone to authorize user requests. Quantum handles two kind of authorization policies:
 
* Operation-based: policy specify access criteria for specific operations, possibly with fine-grained control over specific attributes;
 
* Resource-based: where access to specific resource might be granted or not according to the permissions configured for the resource (currently available only for the '''network''' resource)
 
  
The actual authorization policies enforced in Quantum might vary from deployment to deployment.
+
<pre><nowiki>
 +
HTTP/1.1 200 Accepted
 +
Content-Type application/json
 +
Content-Length 204
  
=== Request and Response types ===
+
{
 +
"network":
 +
    {
 +
    "status": "ACTIVE",
 +
    "subnets": [],
 +
    "name": "net-name",
 +
    "admin_state_up": true,
 +
    "tenant_id": "388a70781bae4ca895f17b7f6293eb70",
 +
    "shared": false, "id": "2a4017ef-31ff-496a-9294-e96ecc3bc9c9"
 +
    }
 +
}
 +
</nowiki></pre>
  
''TBD'' Once we sort out XML support for Quantum.
+
'''''NOTE: We have still to finalize a decision concerning XML support.''''' [https://blueprints.launchpad.net/neutron/+spec/quantum-v2-api-xml Quantum v2 API XML blueprint]
  
 
=== Filtering  and Column Selection ===
 
=== Filtering  and Column Selection ===
 
+
The Neutron API supports filtering based on all top level attributes of a resource. Filters are applicable to all '''list''' requests. For instance:
The Quantum API supports filtering based on all top level attributes of a resource.
 
Filters are applicable to all '''list''' requests. For instance:
 
  
  
Line 297: Line 343:
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
will return all the networks whose name is foobar. When multiple filters are specified, the Neutron API will return only objects that satisfy all the filters, this applying an AND condition among filters. Neutron does not offer a mechanisms for ORing filters. To this aim, the user can submit a distinct request for each filters, and then build a set on the client-side from received responses.
  
will return all the networks whose name is foobar.
+
By default, Neutron returns all attributes for any Show or List call.  The Neutron API has a mechanism to limit the set of attributes returned (e.g., return just 'id'). Attributes returned from the Neutron API can be controller using the '''fields''' query parameter. For example the following request:
When multiple filters are specified, the Quantum API will return only objects that satisfy all the filters, this applying an AND condition among filters.
 
Quantum does not offer a mechanisms for ORing filters. To this aim, the user can submit a distinct request for each filters, and then build a set on the client-side from received responses.
 
 
 
By default, Quantum returns all attributes for any Show or List call.  The Quantum API has a mechanism to limit the set of attributes returned (e.g., return just 'id').  
 
Attributes returned from the Quantum API can be controller using the '''fields''' query parameter. For example the following request:
 
  
  
Line 309: Line 351:
 
GET /v2.0/networks.json?fields=id&fields=name
 
GET /v2.0/networks.json?fields=id&fields=name
 
</nowiki></pre>
 
</nowiki></pre>
 
  
 
will return only '''id''' and '''name''' for each network.
 
will return only '''id''' and '''name''' for each network.
  
 
=== Synchronous vs Asynchronous Plugin Behavior ===
 
=== Synchronous vs Asynchronous Plugin Behavior ===
 +
The Neutron API presents a logical model of network connectivity consisting of networks, ports, and subnets. It is up to the Neutron plugin to communicate with the underlying infrastructure to ensure packet forwarding is consistent with the logical model. A plugin might perform these operations asynchronously. This means that when an API client modifies the logical model using an HTTP POST, PUT, or DELETE, the API call may return prior to the plugin performing any modifications to underlying virtual and/or physical switching devices. The only guarantee an API client has is that all subsequent API calls will properly reflect the changed logical model. As a concrete example, consider the case where a client uses an HTTP PUT to set the attachment for a port. There is no guarantee that packets sent by the interface named in the attachment will be forwarded immediately once the HTTP call returns. However, there is a guarantee that a subsequent HTTP GET to view the attachment on that port would return the new attachment value. The "status" attribute, available for '''network''' and '''port''' resources might be used to understand whether the Neutron plugin has successfully completed the configuration of the interested resource.
  
The Quantum API presents a logical model of network connectivity consisting of networks, ports, and subnets. It is up to the Quantum plugin to communicate with the underlying infrastructure to ensure packet forwarding is consistent with the logical model.
 
A plugin might perform these operations asynchronously. This means that when an API client modifies the logical model using an HTTP POST, PUT, or DELETE, the API call may return prior to the plugin performing any modifications to underlying virtual and/or physical switching devices. The only guarantee an API client has is that all subsequent API calls will properly reflect the changed logical model.
 
As a concrete example, consider the case where a client uses an HTTP PUT to set the attachment for a port. There is no guarantee that packets sent by the interface named in the attachment will be forwarded immediately once the HTTP call returns. However, there is a guarantee that a subsequent HTTP GET to view the attachment on that port would return the new attachment value.
 
The "status" attribute, available for '''network''' and '''port''' resources might be used to understand whether the Quantum plugin has successfully completed the configuration of the interested resource.
 
 
=== Bulk Create Operations ===
 
=== Bulk Create Operations ===
 +
The Neutron API allow for creating several objects of the same type in the same API request. Bulk create operations use exactly the same API as singleton create operations, with the only difference being that a list of objects, rather than a single object, is specified in the request body.
  
The Quantum API allow for creating several objects of the same type in the same API request. Bulk create operations use exactly the same API as singleton create operations, with the only difference being that a list of objects, rather than a single object, is specified in the request body.
+
Bulk operations are always performed atomically, meaning that either all or none of the objects in the request body are created. Should the particular plugin does not support atomic operations, Neutron API will emulate the atomic behavior, thus ensuring users might expect the same behavior regardless of the particular plugin running in the backend.
  
Bulk operations are always performed atomically, meaning that either all or none of the objects in the request body are created. Should the particular plugin does not support atomic operations, Quantum API will emulate the atomic behavior, thus ensuring users might expect the same behavior regardless of the particular plugin running in the backend.
+
Neutron might be deployed without support for bulk operations. In that case a '''400 Bad Request''' error will be returned when the client attempts a bulk create operation.
  
Quantum might be deployed without support for bulk operations. In that case a '''400 Bad Request''' error will be returned when the client attempts a bulk create operation.
+
For more details concerning how to submit bulk requests to the Neutron API, please refer to create operations discussed in the next chapter.
 
 
For more details concerning how to submit bulk requests to the Quantum API, please refer to create operations discussed in the next chapter.
 
  
 
=== Quotas ===
 
=== Quotas ===
 
 
[tbd]  Yong to contribute
 
[tbd]  Yong to contribute
  
Line 337: Line 373:
  
 
=== Extensions ===
 
=== Extensions ===
 +
The Neutron API is extensible. Extensions serve several purposes:
  
The Quantum API is extensible. Extensions serve several purposes:
 
 
* They allow the introduction of new features in the API without requiring a version change;
 
* They allow the introduction of new features in the API without requiring a version change;
 
* They allow the introduction of vendor specific niche functionality
 
* They allow the introduction of vendor specific niche functionality
 
* They act as a proving ground for experimental functionalities which might be included in a future version of the API.
 
* They act as a proving ground for experimental functionalities which might be included in a future version of the API.
Applications can programmatically determine what extensions are available by performing a GET on the v2.0/extensions URI.  
+
 
Extensions may also be queried individually by their unique alias by performing a GET on the /v2.0/extensions/alias_name. This provides the simplest method of checking if an extension is available as an unavailable extension will issue an itemNotFound (404) response.
+
Applications can programmatically determine what extensions are available by performing a GET on the v2.0/extensions URI. Extensions may also be queried individually by their unique alias by performing a GET on the /v2.0/extensions/alias_name. This provides the simplest method of checking if an extension is available as an unavailable extension will issue an itemNotFound (404) response. Existing core API resources can be extended with new actions or extra attributes. Also, new resources can also be added as extensions. Extensions usually have tags that prevent clash with other extensions defining attributes and/or resources with the same name, and with core resources and attributes. As an extension might not be supported by all plugin, availability of an extension will vary with deployments and the specific plugin in use.
Existing core API resources can be extended with new actions or extra attributes. Also, new resources can also be added as extensions. Extensions usually have tags that prevent clash with other extensions defining attributes and/or resources with the same name, and with core resources and attributes. As an extension might not be supported by all plugin, availability of an extension will vary with deployments and the specific plugin in use.
 
  
 
=== Faults ===
 
=== Faults ===
 
+
If a failure occurs while processing a request, the Neutron API returns an error response. Neutron uses only standard HTTP error codes. 4xx errors are indicative of problems in the particular request being sent from the client.
If a failure occurs while processing a request, the Quantum API returns an error response.
 
Quantum uses only standard HTTP error codes. 4xx errors are indicative of problems in the particular request being sent from the client.
 
 
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Error  
+
| Error  
 
|-
 
|-
|rowspan="4" | 400 Bad Request  
+
|<style="text-align:center" |4>|400 Bad Request  
 
|-
 
|-
 
|-
 
|-
 
|-
 
|-
 
|-
 
|-
|rowspan="2" | 404 Not Found  
+
|<style="text-align:center" |2>|404 Not Found  
 
|-
 
|-
 
|-
 
|-
|rowspan="3" | 409 Conflict  
+
|<style="text-align:center" |3>|409 Conflict  
 
|-
 
|-
 
|-
 
|-
 
|-
 
|-
|rowspan="2" | 422 Uprocessable Entity
+
|<style="text-align:center" |2>|400 Bad Request
 
|-
 
|-
 
|-
 
|-
| 500 Internal server error  
+
| 500 Internal server error  
 
|-
 
|-
| 503 [[ServiceUnavailable]]  
+
| 503 [[ServiceUnavailable]]  
 
|}
 
|}
  
Users submitting requests to the Quantum API might also receive the following errors:
+
Users submitting requests to the Neutron API might also receive the following errors:
 +
 
 
* 401 Unauthorized - if invalid credentials are provided
 
* 401 Unauthorized - if invalid credentials are provided
 
* 403 Forbidden - If the user cannot access a specific resource or perform the requested operation.
 
* 403 Forbidden - If the user cannot access a specific resource or perform the requested operation.
  
 
== API Operations ==
 
== API Operations ==
 
 
=== List Networks ===
 
=== List Networks ===
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Verb  
+
|<style="font-weight: bold;">|Verb  
| URI  
+
|<style="font-weight: bold;">|URI  
 
|-
 
|-
| GET  
+
| GET  
| /networks  
+
| /networks  
 
|}
 
|}
 +
 +
This operation returns the list of all the network the tenants has access to. This includes networks owned by tenant and shared networks. By default, network objects will be returned with all their attributes. Users can control which attribute should be returned by using the ''field'' query parameter.  Responses can be filtered by specifying search criteria on the query string. Only exact match supported at the moment.
  
 
Normal Response Code: 200
 
Normal Response Code: 200
Line 397: Line 430:
  
 
Request
 
Request
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
 
GET /v2.0/networks
 
GET /v2.0/networks
 
 
Accept: application/json
 
Accept: application/json
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response
  
Response
 
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 412: Line 445:
 
   {
 
   {
 
     "status": "ACTIVE",
 
     "status": "ACTIVE",
     "subnets": [],  
+
     "subnets": [],
 
     "name": "network_1",
 
     "name": "network_1",
 
     "admin_state_up": true,
 
     "admin_state_up": true,
     "tenant_id": "c1210485b2424d48804aad5d39c61b8f",  
+
     "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
 
     "id": "3a06dfc7-d239-4aad-9a57-21cd171c72e5",
 
     "id": "3a06dfc7-d239-4aad-9a57-21cd171c72e5",
     "permissions": "rw-------"
+
     "shared": false
   },  
+
   },
 
   {
 
   {
 
     "status": "ACTIVE",
 
     "status": "ACTIVE",
Line 426: Line 459:
 
     "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
 
     "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
 
     "id": "7db8c5a4-6eb0-478d-856b-7cfda2b25e13",
 
     "id": "7db8c5a4-6eb0-478d-856b-7cfda2b25e13",
     "permissions": "rw-------"
+
     "shared": false
   },  
+
   },
 
   {
 
   {
 
     "status": "ACTIVE",
 
     "status": "ACTIVE",
Line 435: Line 468:
 
     "tenant_id": "ed680f49ff714162ab3612d7876ffce5",
 
     "tenant_id": "ed680f49ff714162ab3612d7876ffce5",
 
     "id": "afc75773-640e-403c-9fff-62ba98db1f19",
 
     "id": "afc75773-640e-403c-9fff-62ba98db1f19",
     "permissions": "rw-r--r--"
+
     "shared": true
 
   }
 
   }
 
  ]
 
  ]
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
 
This operation does not require a request body, unless the Quantum server is running without Keystone integration.
 
  
 
=== Show Network ===
 
=== Show Network ===
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Verb  
+
|<style="font-weight: bold;">|Verb  
| URI  
+
|<style="font-weight: bold;">|URI  
 
|-
 
|-
| GET  
+
| GET  
| /networks/'''<network_id>'''  
+
| /networks/'''<network_id>'''  
 
|}
 
|}
 +
 +
This operation returns the complete list of attributes for the network whose identifier is specified in the request URI, assuming the network exists and the user making the request is authorized to access it. The set of attributes which is actually returned by the API can be controller through the ''field'' query parameter.
  
 
Normal Response Code: 200
 
Normal Response Code: 200
Line 460: Line 492:
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
 
GET /v2.0/networks/afc75773-640e-403c-9fff-62ba98db1f19
 
GET /v2.0/networks/afc75773-640e-403c-9fff-62ba98db1f19
 
 
Accept: application/json
 
Accept: application/json
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response:
  
Response:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 478: Line 510:
 
     "name": "network_3",
 
     "name": "network_3",
 
     "admin_state_up": true,
 
     "admin_state_up": true,
     "tenant_id": "ed680f49ff714162ab3612d7876ffce5",  
+
    "shared": false,
 +
     "tenant_id": "ed680f49ff714162ab3612d7876ffce5",
 
     "id": "afc75773-640e-403c-9fff-62ba98db1f19"
 
     "id": "afc75773-640e-403c-9fff-62ba98db1f19"
 
   }
 
   }
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
 
  
 
=== Create Network ===
 
=== Create Network ===
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Verb  
+
|<style="font-weight: bold;">|Verb  
| URI  
+
|<style="font-weight: bold;">|URI  
 
|-
 
|-
| POST  
+
| POST  
| /networks  
+
| /networks  
 
|}
 
|}
 +
 +
This operation will create a new Neutron network. The identifier of the newly created network is returned in the response. The ''shared'' attribute can be used to create a ''public'' network, i.e.: a network which is shared with all other tenants. However, the current model of the Neutron API allows only for either completely private or completely open networks. More sophisticated mechanisms for specifying ACLs on networks will come in future releases of the API.
 +
 +
Moreover, control of the '''shared''' attribute could be reserved to particular users only, such as administrators. In this case, regular users trying to create a shared network will receive a '''403 - Forbidden''' error.
  
 
Normal Response Code: 200
 
Normal Response Code: 200
Line 502: Line 537:
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
POST v2.0/networks.json  
+
POST v2.0/networks.json
 
 
 
Content-Type: application/json
 
Content-Type: application/json
 
Accept: application/json
 
Accept: application/json
Line 512: Line 547:
 
  "network":
 
  "network":
 
   {
 
   {
     "name": "sample_network",  
+
     "name": "sample_network",
 
     "admin_state_up": false
 
     "admin_state_up": false
 
   }
 
   }
Line 518: Line 553:
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response:
  
Response:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 527: Line 562:
  
 
{
 
{
   "network":  
+
   "network":
 
     {
 
     {
 
       "status": "ACTIVE",
 
       "status": "ACTIVE",
       "subnets": [],  
+
       "subnets": [],
       "name": "sample_network",  
+
       "name": "sample_network",
       "admin_state_up": false,  
+
       "admin_state_up": false,
       "tenant_id": "c1210485b2424d48804aad5d39c61b8f",  
+
      "shared": false,
 +
       "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
 
       "id": "fc68ea2c-b60b-4b4f-bd82-94ec81110766"
 
       "id": "fc68ea2c-b60b-4b4f-bd82-94ec81110766"
 
     }
 
     }
 
}
 
}
 
 
</nowiki></pre>
 
</nowiki></pre>
 
  
 
==== Bulk version ====
 
==== Bulk version ====
 
+
The bulk version of operation allows for creating several networks with a single request. The behavior of the bulk create operation is always atomic: either all networks in the request body are created, or none of them is created. To this aim, a list of networks must be supplied in the request body, as follows:
This operation allows for creating several networks with a single request.
 
To this aim, a list of networks must be supplied in the request body, as follows:
 
  
 
'''JSON Request and Response sample''':
 
'''JSON Request and Response sample''':
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
POST v2.0/networks.json  
+
POST v2.0/networks.json
  
 
Content-Type: application/json
 
Content-Type: application/json
Line 559: Line 592:
 
"networks": [
 
"networks": [
 
   {
 
   {
     "name": "sample_network_1",  
+
     "name": "sample_network_1",
 
     "admin_state_up": false
 
     "admin_state_up": false
 
   },
 
   },
 
   {
 
   {
     "name": "sample_network_2",  
+
     "name": "sample_network_2",
 
     "admin_state_up": false
 
     "admin_state_up": false
 
   }]
 
   }]
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
 
 
The behavior of the bulk create operation is always atomic: either all networks in the request body are created, or none of them is created.
 
 
==== Note about 'public' networks (permissions 0644) ====
 
 
The '''permissions''' attribute can be used to create a 'public' network, i.e.: a network which is share with all other tenants.
 
This attribute allows for specifying filesystem-like permissions on Quantum resources.
 
However, the Quantum API currently only supports the option to create networks shared with every other tenant. To this aim the '''permissions''' attribute should be set to ''0644'' or ''rw- r-- r--''.
 
 
Moreover, control of the '''permissions''' attribute could reserved to particular users only, such as administrators. In this case, regular users trying to create a network with permission setting different from the default value will receive a '''403 - Forbidden''' error.
 
  
 
=== Update Network ===
 
=== Update Network ===
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Verb  
+
|<style="font-weight: bold;">|Verb  
| URI  
+
|<style="font-weight: bold;">|URI  
 
|-
 
|-
| PUT  
+
| PUT  
| /networks/''<network-id>''  
+
| /networks/''<network-id>''  
 
|}
 
|}
  
The update network operation allow users for updating some attributes of a network object, such as name and admin_state_up.
+
The update network operation allow users for updating some attributes of a network object, such as name and admin_state_up. Attributes such as tenant_id cannot be updated. If an attempt is made to update such attributes a 422 'Unprocesable Entity' error will be returned.
Attributes such as tenant_id cannot be updated. If an attempt is made to update such attributes a 422 'Unprocesable Entity' error will be returned.
 
  
''Note'': Update operations in Quantum adopt patch semantics. This implies that the Quantum API does not require the user to send the whole resource to be updated, but just the attributes that the user wishes to update, as reported in the example below.  
+
Users authorized to control the ''shared'' attribute are also allowed to change it. While sharing a previously private network is always possible, the opposite is not always true. If the user attempts to turn private a shared network with subnets and/or ports belonging to tenants different from the network owner, a ''409 Conflict'' error will be returned.
 +
 
 +
''Note'': Update operations in Neutron adopt patch semantics. This implies that the Neutron API does not require the user to send the whole resource to be updated, but just the attributes that the user wishes to update, as reported in the example below.
  
 
Normal Response Code: 200 Ok
 
Normal Response Code: 200 Ok
  
Error Response Codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity
+
Error Response Codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
  
 
'''JSON Request and Response sample''':
 
'''JSON Request and Response sample''':
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
PUT /v2.0/networks/fc68ea2c-b60b-4b4f-bd82-94ec81110766.json  
+
PUT /v2.0/networks/fc68ea2c-b60b-4b4f-bd82-94ec81110766.json
  
 
Content-Type: application/json
 
Content-Type: application/json
Line 610: Line 633:
  
 
{
 
{
   "network":  
+
   "network":
 
     {
 
     {
 
       "name": "updated_name"
 
       "name": "updated_name"
 
     }
 
     }
 
}
 
}
 
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response:
  
Response:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 627: Line 649:
  
 
{
 
{
   "network":  
+
   "network":
 
     {"status": "ACTIVE",
 
     {"status": "ACTIVE",
 
     "subnets": [],
 
     "subnets": [],
     "name": "updated_name",  
+
     "name": "updated_name",
 
     "admin_state_up": false,
 
     "admin_state_up": false,
       "tenant_id": "c1210485b2424d48804aad5d39c61b8f",  
+
    "shared": false,
 +
       "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
 
       "id": "fc68ea2c-b60b-4b4f-bd82-94ec81110766"}}
 
       "id": "fc68ea2c-b60b-4b4f-bd82-94ec81110766"}}
 
</nowiki></pre>
 
</nowiki></pre>
 
  
 
=== Delete Network ===
 
=== Delete Network ===
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Verb  
+
|<style="font-weight: bold;">|Verb  
| URI  
+
|<style="font-weight: bold;">|URI  
 
|-
 
|-
| DELETE  
+
| DELETE  
| /networks/'''<network_id>'''  
+
| /networks/'''<network_id>'''  
 
|}
 
|}
 +
 
'''JSON Request and Response sample''':
 
'''JSON Request and Response sample''':
  
This operation will remove a Quantum network, and all its associated subnets, provided that no port is currently configured on the network.\\
+
This operation will remove a Neutron network, and all its associated subnets, provided that no port is currently configured on the network. If ports are still configured on the network being removed, a 409 error will be returned.
If ports are still configured on the network being removed, a 409 error will be returned.
 
  
 
Normal Response Code: 204
 
Normal Response Code: 204
Line 656: Line 677:
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 661: Line 683:
  
 
Content-Type: application/json
 
Content-Type: application/json
Accept: application/json  
+
Accept: application/json
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response:
  
Response:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
 
status: 204
 
status: 204
 
</nowiki></pre>
 
</nowiki></pre>
 
  
 
=== List Subnets ===
 
=== List Subnets ===
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Verb  
+
|<style="font-weight: bold;">|Verb  
| URI  
+
|<style="font-weight: bold;">|URI  
 
|-
 
|-
| GET  
+
| GET  
| /subnets  
+
| /subnets  
 
|}
 
|}
  
Normal Response Code: 200 Ok
+
This operation will return a list of subnets objects the tenant has access to. Default policy settings will return exclusively subnets owned by the tenant submitting the request, unless the request is submitted by an user with administrative rigths. Users can control which attributes should be returned using the ''fields'' query parameter as discussed in the previous chapter. Moreover, results can be filtered using query string parameters as discussed in the previous chapter.
  
Error Response Codes: 400 Bad Request, 401 Unauthorized
+
This operation does not require a reques body.
  
This operation will return a list of subnets objects the tenant has access to. Default policy settings will return exclusively subnets owned by the tenant submitting the request, unless the request is submitted by an user with administrative rigths.
+
Normal Response Code: 200 Ok
Users can control which attributes should be returned using the ''fields'' query parameter as discussed in the previous chapter.
 
Moreover, results can be filtered using query string parameters as discussed in the previous chapter.
 
  
This operation does not require a reques body.
+
Error Response Codes: 401 Unauthorized
  
 
'''JSON Request and Response sample''':
 
'''JSON Request and Response sample''':
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 702: Line 721:
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response:
  
Response:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 715: Line 734:
 
     "name": "",
 
     "name": "",
 
     "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
 
     "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
     "tenant_id": "c1210485b2424d48804aad5d39c61b8f",  
+
     "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
 
     "allocation_pools": [{"start": "10.10.0.2", "end": "10.10.0.254"}],
 
     "allocation_pools": [{"start": "10.10.0.2", "end": "10.10.0.254"}],
 
     "gateway_ip": "10.10.0.1",
 
     "gateway_ip": "10.10.0.1",
 
     "ip_version": 4,
 
     "ip_version": 4,
 
     "cidr": "10.10.0.0/24",
 
     "cidr": "10.10.0.0/24",
     "id": "4156c7a5-e8c4-4aff-a6e1-8f3c7bc83861"
+
     "id": "4156c7a5-e8c4-4aff-a6e1-8f3c7bc83861",
     },  
+
    "enable_dhcp": true
 +
     },
 
     {
 
     {
       "name": "",  
+
       "name": "",
 
       "network_id": "afc75773-640e-403c-9fff-62ba98db1f19",
 
       "network_id": "afc75773-640e-403c-9fff-62ba98db1f19",
 
       "tenant_id": "ed680f49ff714162ab3612d7876ffce5",
 
       "tenant_id": "ed680f49ff714162ab3612d7876ffce5",
 
       "allocation_pools": [{"start": "10.0.0.2", "end": "10.0.0.254"}],
 
       "allocation_pools": [{"start": "10.0.0.2", "end": "10.0.0.254"}],
       "gateway_ip": "10.0.0.1",  
+
       "gateway_ip": "10.0.0.1",
 
       "ip_version": 4,
 
       "ip_version": 4,
 
       "cidr": "10.0.0.0/24",
 
       "cidr": "10.0.0.0/24",
      "id": "e12f0c45-46e3-446a-b207-9474b27687a6"
+
      "id": "e12f0c45-46e3-446a-b207-9474b27687a6",
 +
      "enable_dhcp": true
 
     }]
 
     }]
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
 
  
 
=== Show Subnet ===
 
=== Show Subnet ===
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Verb  
+
|<style="font-weight: bold;">|Verb  
| URI  
+
|<style="font-weight: bold;">|URI  
 
|-
 
|-
| GET  
+
| GET  
| /subnets/''<subnet-id>''  
+
| /subnets/''<subnet-id>''  
 
|}
 
|}
 +
 +
This operation returns data about the subnet specified in the request URI. Users can control which attributes should be returned using the ''fields'' query parameter as discussed in the previous chapter. If the user submitting the request is not authorized to access the requested subnet, or if the requested subnet does not exist, a 404 error will be returned.
 +
 +
This operation does not require a request body.
  
 
Normal Response Code: 200 Ok
 
Normal Response Code: 200 Ok
  
 
Error Response Codes: 400 Bad Request, 401 Unauthorized, 404 Not Found
 
Error Response Codes: 400 Bad Request, 401 Unauthorized, 404 Not Found
 
This operation returns data about the subnet specified in the request URI.
 
Users can control which attributes should be returned using the ''fields'' query parameter as discussed in the previous chapter.
 
 
This operation does not require a request body.
 
  
 
'''JSON Request and Response sample''':
 
'''JSON Request and Response sample''':
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 764: Line 784:
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response:
  
Response:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 773: Line 793:
  
 
{
 
{
   "subnet":  
+
   "subnet":
 
     {
 
     {
 
     "name": "",
 
     "name": "",
Line 781: Line 801:
 
     "gateway_ip": "10.10.0.1",
 
     "gateway_ip": "10.10.0.1",
 
     "ip_version": 4,
 
     "ip_version": 4,
     "cidr": "10.10.0.0/24",  
+
     "cidr": "10.10.0.0/24",
     "id": "4156c7a5-e8c4-4aff-a6e1-8f3c7bc83861"
+
     "id": "4156c7a5-e8c4-4aff-a6e1-8f3c7bc83861",
 +
    "enable_dhcp": false,
 
     }
 
     }
 
}
 
}
 
 
</nowiki></pre>
 
</nowiki></pre>
 
  
 
=== Create Subnet ===
 
=== Create Subnet ===
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Verb  
+
|<style="font-weight: bold;">|Verb  
| URI  
+
|<style="font-weight: bold;">|URI  
 
|-
 
|-
| POST  
+
| POST  
| /subnets  
+
| /subnets  
 
|}
 
|}
 +
 +
This operation creates a new subnet on a specific network. The identifier of the network, '''network_id''' is mandatory. The user must also specify the '''cidr''' for the subnet, in the form ''<network_address>/<prefix>''. The remaining parameters are optional.
 +
 +
By default, Neutron creates IP v4 subnets. In order to create an IP v6 subnet, users must specify the value ''6'' for the '''ip_version''' attribute in the request body. Please note that Neutron does not make any attempt to derive the correct IP version from the provided CIDR. If the parameter for the gateway address, '''gateway_ip''' is not specified, then Neutron will allocate an address from the subnet's cidr for the subnet's gateway. In order to specify a subnet without a gateway, users should specify the value ''null'' for the '''gateway_ip''' attribute in the request body.  If allocation pools (attribute '''allocation_pools''') are not specified, Neutron will automatically allocate pools for covering all IP addresses in the CIDR, excluding the address reserved for the subnet gateway. Otherwise users can explicitly specify allocation pools as shown in the example below.
 +
 +
Finally, a subnet by default will leverage DHCP for distributing addresses to VMs. If a different strategy is used, such as, for instance, file system IP configuration injection, the ''enable_dhcp'' attribute should be explicitly set to False in a ''create_subnet'' request.
  
 
Normal Response Code: 201 Created
 
Normal Response Code: 201 Created
  
 
Error Response Codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
 
Error Response Codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
 
This operation creates a new subnet on a specific network. The identifier of the network, '''network_id''' is mandatory.
 
The user must also specify the '''cidr''' for the subnet, in the form ''<network_address>/<prefix>''.
 
The remaining parameters are optional.
 
 
By default, Quantum creates IP v4 subnets. In order to create an IP v6 subnet, users must specify the value ''6'' for the '''ip_version''' attribute in the request body. Please note that Quantum does not make any attempt to derive the correct IP version from the provided CIDR.
 
If the parameter for the gateway address, '''gateway_ip''' is not specified, then Quantum will allocate an address from the subnet's cidr for the subnet's gateway. In order to specify a subnet without a gateway, users should specify the value ''none'' for the '''gateway_ip''' attribute in the request body.
 
If allocation pools (attribute '''allocation_pools''') are not specified, Quantum will automatically allocate pools for covering all IP addresses in the CIDR, excluding the address reserved for the subnet gateway. Otherwise users can explicitly specify allocation pools as shown in the example below.
 
  
 
'''JSON Request and Response sample''':
 
'''JSON Request and Response sample''':
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 832: Line 849:
 
Response:
 
Response:
 
{{{
 
{{{
status: 201,  
+
status: 201,
 
content-length: 306,
 
content-length: 306,
 
content-type: application/json
 
content-type: application/json
Line 845: Line 862:
 
     "ip_version": 4,
 
     "ip_version": 4,
 
     "cidr": "10.0.3.0/24",
 
     "cidr": "10.0.3.0/24",
     "id": "9436e561-47bf-436a-b1f1-fe23a926e031"}
+
     "id": "9436e561-47bf-436a-b1f1-fe23a926e031",
 +
    "enable_dhcp": true}
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
 
  
 
==== Bulk version ====
 
==== Bulk version ====
 +
This operation allows for creating several subnets with a single request. To this aim, a list of subnets must be supplied in the request body. The behavior of the operation is always atomic, meaning that either all subnets are created, or none is created.
  
This operation allows for creating several subnet with a single request.
+
Request:
To this aim, a list of subnets must be supplied in the request body.
 
  
Request:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 863: Line 879:
  
 
{
 
{
   "subnets": [  
+
   "subnets": [
 
     {
 
     {
 
       "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
 
       "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
Line 877: Line 893:
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
 
 
The behavior of the operation is always atomic, meaning that either all subnets are created, or none is created.
 
  
 
=== Update Subnet ===
 
=== Update Subnet ===
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Verb  
+
|<style="font-weight: bold;">|Verb  
| URI  
+
|<style="font-weight: bold;">|URI  
 
|-
 
|-
| PUT  
+
| PUT  
| /subnets/''<subnet-id>''  
+
| /subnets/''<subnet-id>''  
 
|}
 
|}
  
Normal Response Code: 200 Ok
+
This operation updates information concerning a subnet. Some attributes, such as IP version ('''ip_version'''), CIDR ('''cidr'''), and IP allocation pools (''''allocation_pools''') cannot be updated. Attempting to update these attributes will result in a 400 Bad Request error.
  
Error Response Codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity
+
After updating ''host_routes'' and ''dns_nameservers'' attributes, there is no guarantee about when these changes will be reflected on running VM instances. The only responsibility of the Neutron API is to update the data model with the new information. When these information are then propagated on running VMs depends on the mechanism used for providing them with IP configuration. In case of DHCP, this will happen as soon as the VMs send a new DHCP request, and therefore it is likely to happen either when the DHCP lease expires or when the VM is rebooted.
  
This operation updates information concerning a subnet. Some attributes, such as IP version ('''ip_version'''), CIDR ('''cidr'''), and IP allocation pools (''''allocation_pools''') cannot be updated.
+
''Note'': Update operations in Neutron adopt patch semantics. This implies that the Neutron API does not require the user to send the whole resource to be updated, but just the attributes that the user wishes to update, as reported in the example below
Attempting to update these attributes will result in a 422 Unprocessable Entity error.
 
  
''Note'': Update operations in Quantum adopt patch semantics. This implies that the Quantum API does not require the user to send the whole resource to be updated, but just the attributes that the user wishes to update, as reported in the example below
+
Normal Response Code: 200 Ok
 +
 
 +
Error Response Codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 400 Bad Request
  
 
'''JSON Request and Response sample''':
 
'''JSON Request and Response sample''':
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 911: Line 925:
  
 
{
 
{
   "subnet":  
+
   "subnet":
 
     {
 
     {
 
       "gateway_ip": "10.0.3.254",
 
       "gateway_ip": "10.0.3.254",
Line 917: Line 931:
 
     }
 
     }
 
}
 
}
 
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response:
  
Response:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 938: Line 951:
 
     "ip_version": 4,
 
     "ip_version": 4,
 
     "cidr": "10.0.3.0/24",
 
     "cidr": "10.0.3.0/24",
 +
    "enable_dhcp": true,
 
     "id": "9436e561-47bf-436a-b1f1-fe23a926e031"
 
     "id": "9436e561-47bf-436a-b1f1-fe23a926e031"
 
   }
 
   }
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
 
  
 
=== Delete Subnet ===
 
=== Delete Subnet ===
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Verb  
+
|<style="font-weight: bold;">|Verb  
| URI  
+
|<style="font-weight: bold;">|URI  
 
|-
 
|-
| DELETE  
+
| DELETE  
| /subnets/''<subnetid>''  
+
| /subnets/''<subnetid>''  
 
|}
 
|}
  
This operation remove a subnet from a Quantum network. The operation will fail if IPs from the subnet being removed are still allocated.
+
This operation remove a subnet from a Neutron network. The operation will fail if IPs from the subnet being removed are still allocated.
  
 
Normal Response Code: 204
 
Normal Response Code: 204
Line 963: Line 975:
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 970: Line 983:
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response:
  
Response:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
Line 977: Line 990:
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
=== List Ports ===
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
|<style="font-weight: bold;">|Verb
 +
|<style="font-weight: bold;">|URI
 +
|-
 +
| GET
 +
| /ports
 +
|}
 +
 +
This operation will return a list of ports objects the tenant has access to. Default policy settings will return exclusively subnets owned by the tenant submitting the request, unless the request is submitted by an user with administrative rigths. Users can control which attributes should be returned using the ''fields'' query parameter as discussed in the previous chapter. Moreover, results can be filtered using query string parameters as discussed in the previous chapter.
 +
 +
This operation does not require a reques body.
 +
 +
Normal Response code: 200
  
=== List Ports ===
+
Error Response Code: 401 Unauthorized
  
 
'''JSON Request and Response sample''':
 
'''JSON Request and Response sample''':
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
 +
GET /v2.0/ports.json HTTP/1.1
 +
accept: application/json
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response:
  
Response:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
 +
Status: 200
 +
Content-Type: application/json
 +
Content-Length: 805
 +
 +
{
 +
    "ports": [
 +
        {
 +
            "admin_state_up": true,
 +
            "device_id": "257614cc-e178-4c92-9c61-3b28d40eca44",
 +
            "device_owner": "",
 +
            "fixed_ips": [
 +
                {
 +
                    "ip_address": "192.168.111.3",
 +
                    "subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
 +
                }
 +
            ],
 +
            "id": "24e6637e-c521-45fc-8b8b-d7331aa3c99f",
 +
            "mac_address": "fa:16:3e:0f:3f:b5",
 +
            "name": "",
 +
            "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
 +
            "status": "ACTIVE",
 +
            "tenant_id": "cf1a5775e766426cb1968766d0191908"
 +
        },
 +
        {
 +
            "admin_state_up": true,
 +
            "device_id": "d266f9de-fe2c-4705-93b3-9da71168c93b",
 +
            "device_owner": "",
 +
            "fixed_ips": [
 +
                {
 +
                    "ip_address": "192.168.111.2",
 +
                    "subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
 +
                }
 +
            ],
 +
            "id": "e54dfd9b-ce6e-47f7-af47-1609cfd1cdb0",
 +
            "mac_address": "fa:16:3e:f5:41:7f",
 +
            "name": "",
 +
            "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
 +
            "status": "ACTIVE",
 +
            "tenant_id": "cf1a5775e766426cb1968766d0191908"
 +
        }
 +
    ]
 +
}
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
=== Show Port ===
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
|<style="font-weight: bold;">|Verb
 +
|<style="font-weight: bold;">|URI
 +
|-
 +
| GET
 +
| /ports/''port-id''
 +
|}
 +
 +
This operation will return information regarding the port specified in the request URI. If the port does not exist or the user submitting the request is not authorized to access it, a 404 error is returned.
 +
 +
Normal Response code: 200
  
=== Show Port ===
+
Error Response Code: 400 Bad Request, 401 Unauthorized, 404 Not Found
  
 
'''JSON Request and Response sample''':
 
'''JSON Request and Response sample''':
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
 +
GET /v2.0/ports/ebe69f1e-bc26-4db5-bed0-c0afb4afe3db.json
 +
accept: application/json
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response:
  
Response:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
 +
Status: 200
 +
Content-Type: application/json
 +
Content-Length: 410
 +
 +
{
 +
    "port": {
 +
        "admin_state_up": true,
 +
        "device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
 +
        "device_owner": "",
 +
        "fixed_ips": [
 +
            {
 +
                "ip_address": "192.168.111.4",
 +
                "subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
 +
            }
 +
        ],
 +
        "id": "ebe69f1e-bc26-4db5-bed0-c0afb4afe3db",
 +
        "mac_address": "fa:16:3e:a6:50:c1",
 +
        "name": "port1",
 +
        "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
 +
        "status": "ACTIVE",
 +
        "tenant_id": "cf1a5775e766426cb1968766d0191908"
 +
    }
 +
}
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
=== Create Port ===
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
|<style="font-weight: bold;">|Verb
 +
|<style="font-weight: bold;">|URI
 +
|-
 +
| POST
 +
| /ports
 +
|}
  
=== Create Port ===
+
This operation creates a new Neutron port. The network where the port shall be created ('''network_id''' parameter) in the request body, must be specified. Optionally, user can also specify the following parameters:
 +
 
 +
* A symbolic name for the port
 +
* MAC address
 +
* Administrative state (True: Up, False: Down)
 +
* Fixed IPs
 +
** Specifying just a subnet id, Neutron allocates the first available IP from that subnet to the port
 +
** Specifying both a subnet id and an IP address, Neutron will try to allocate the specified address to the port
 +
* Identifier of the device attached to the port (e.g.: VM identifier)
 +
* Identifier of the owner of the device attached to the port (e.g.: DHCP agent identifier)
 +
 
 +
Normal Response code: 201
 +
 
 +
Error Response Code: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict
  
 
'''JSON Request and Response sample''':
 
'''JSON Request and Response sample''':
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
 +
POST /v2.0/ports.json HTTP/1.1
 +
Content-Length: 158
 +
content-type: application/json
 +
accept: application/json
 +
 +
{
 +
    "port": {
 +
        "admin_state_up": true,
 +
        "device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
 +
        "name": "port1",
 +
        "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12"
 +
    }
 +
}
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response:
  
Response:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
 +
Status: 201
 +
Content-Type: application/json; charset=UTF-8
 +
Content-Length: 410
 +
 +
{
 +
    "port": {
 +
        "admin_state_up": true,
 +
        "device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
 +
        "device_owner": "",
 +
        "fixed_ips": [
 +
            {
 +
                "ip_address": "192.168.111.4",
 +
                "subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
 +
            }
 +
        ],
 +
        "id": "ebe69f1e-bc26-4db5-bed0-c0afb4afe3db",
 +
        "mac_address": "fa:16:3e:a6:50:c1",
 +
        "name": "port1",
 +
        "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
 +
        "status": "ACTIVE",
 +
        "tenant_id": "cf1a5775e766426cb1968766d0191908"
 +
    }
 +
}
 
</nowiki></pre>
 
</nowiki></pre>
 
  
 
==== Bulk version ====
 
==== Bulk version ====
 +
This operation allows for creating several ports with a single request. To this aim, a list of ports must be supplied in the request body. The Neutron API always guarantees the atomic completion of the bulk operation.
  
'''JSON Request and Response sample''':
+
Bulk Request example:
  
Request:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
 +
{
 +
    "ports": [
 +
        {
 +
        "admin_state_up": true,
 +
        "device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
 +
        "name": "port1",
 +
        "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12"
 +
        },
 +
        {
 +
        "admin_state_up": true,
 +
        "device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
 +
        "name": "port2",
 +
        "network_id": "2cd34a97-e087-75fb-9904-dd12937009ea"
 +
        }
 +
    ]
 +
}
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
=== Update Port ===
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
|<style="font-weight: bold;">|Verb
 +
|<style="font-weight: bold;">|URI
 +
|-
 +
| UPDATE
 +
| /ports/''<port-id>''
 +
|}
  
Response:
+
This operation can be used for updating information on a port, such as the symbolic name and the associated IPs. When IPs for a port are updated, the previously associated IPs are removed, returned to the respective subnets allocation pools, and replaced by the IPs specified in the body for the Update request. In other words, the behavior of this operation is to replace the '''fixed_ip''' attribute when it is specified in the request body. If the new IP addresses are invalid (e.g.: already in use), the operation fail and the existing IP addresses are not disassociated from the port.
  
<pre><nowiki>
+
Please note that the only responsibility of the API is to update the data model with the new IP association information. The way in which IP addresses are actually updated on running VMs depends on the particular mechanism used to propagate IP configuration. In case of DHCP, this would happen either when the DHCP lease expires, or when the VM is rebooted.
</nowiki></pre>
 
  
 +
Normal Response code: 200
  
=== Update Port ===
+
Error Response Code: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict
  
 
'''JSON Request and Response sample''':
 
'''JSON Request and Response sample''':
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
 +
PUT /v2.0/ports/1d8591f4-7b62-428e-857d-e82a15e5a7f1.json HTTP/1.1
 +
Content-Length: 63
 +
content-type: application/json
 +
accept: application/json
 +
 +
{
 +
    "port": {
 +
        "device_id": "37b4f622-5e17-4dca-bf67-7338c5b7dd63"
 +
    }
 +
}
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response:
  
Response:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
 +
Status: 200
 +
Content-Type: application/json;
 +
Content-Length: 410
 +
 +
{
 +
    "port": {
 +
        "admin_state_up": true,
 +
        "device_id": "37b4f622-5e17-4dca-bf67-7338c5b7dd63",
 +
        "fixed_ips": [
 +
            {
 +
                "ip_address": "192.168.111.4",
 +
                "subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
 +
            }
 +
        ],
 +
        "id": "1d8591f4-7b62-428e-857d-e82a15e5a7f1",
 +
        "mac_address": "fa:16:3e:70:d2:8c",
 +
        "name": "port2",
 +
        "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
 +
        "status": "ACTIVE",
 +
        "tenant_id": "cf1a5775e766426cb1968766d0191908"
 +
    }
 +
}
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
=== Delete Port ===
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
|<style="font-weight: bold;">|Verb
 +
|<style="font-weight: bold;">|URI
 +
|-
 +
| DELETE
 +
| /ports/''<port-id>''
 +
|}
 +
 +
This operation removes a port from a Neutron network. If IP addresses are associated with the port, they are returned to the respective subnets allocation pools.
 +
 +
Normal Response code: 204
  
=== Delete Port ===
+
Error Response Code: 401 Unauthorized, 403 Forbidden, 404 Not Found
  
 
'''JSON Request and Response sample''':
 
'''JSON Request and Response sample''':
  
 
Request:
 
Request:
 +
  
 
<pre><nowiki>
 
<pre><nowiki>
 +
DELETE /v2.0/ports/ebe69f1e-bc26-4db5-bed0-c0afb4afe3db.json
 +
accept: application/json
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
Response:
  
Response:
 
  
 
<pre><nowiki>
 
<pre><nowiki>
 +
status: 204
 
</nowiki></pre>
 
</nowiki></pre>
 
 
== API usage samples ==
 
 
'''TODO''': ''Find a bunch of common uses cases and then post request and response formats''
 

Latest revision as of 05:28, 11 September 2014

Neutron v2 API

This page is a draft spec and may not reflect the actual implementation.

Refer to http://developer.openstack.org/api-ref-networking-v2.html for the latest.

Overview

Neutron is a project to provide virtual networking services between devices managed by the OpenStack compute service. This document presents and discusses version 2.0 of the Neutron API. For more information on the Neutron project, and additional documentation, please visit http://wiki.openstack.org/Neutron, and docs.openstack.org. We welcome feedback, comments, and bug reports at https://bugs.launchpad.net/neutron.

The v2.0 API represents a combination of the Quantum v1.1 API with some of the most essential IPAM capabilities from the Melange API . These IPAM capabilities focus on being able to associate IP address blocks and other network configuration required by a network device (e.g., default gateway, dns-servers) with a Neutron Network, and then being able to allocate an IP address out of such a block and associate it with a device that is attached to the network via a Neutron Port.

The v2.0 API does this by introducing a new entity, called a Subnet. Subnets can represent the binding of either a IPv4 or IPv6 address block to a previously created Quantum network, and each Neutron Network commonly has one or more subnets. When a port is created on the network, by default it will be allocated an available fixed IP address out of one the designated subnets for each IP version. When the Port is destroyed, the allocated addresses return to the pool of available IPs on the subnet. Users of the Neutron API can either choose a specific IP address from the block, or let Neutron choose the first available IP address.

Please note that version 1.x of the Neutron API has been removed from the source code tree. In order to use v1.x API, an earlier release of Neutron should be installed.

High-level flow

  • Tenant creates a network (e.g., "net1")
  • Tenant creates a subnet (e.g., "10.0.0.0/24"), which implicitly associates the address space with that network. This association creates a binding of the address space to the previously created network. While it is common to say, that a subnet is represented by an IPv4 or IPv6 address range, the address range alone is not a subnet. Rather it is the binding of the address space to the network, which creates the subnet.
  • Tenant boots a VM, specifying a single NIC connected to "net1" (e.g.: nova boot --image <image_name> --nic net-id=<id_of_net1> <server_name>)
  • Nova contacts Neutron and creates a port1 on net1.
  • Neutron assigns an IP to port1 is assigned IP. (The IP is chosen by Neutron)
  • Tenant destroys VM.
  • Nova contacts Neutron and destroys port1. Allocated IP is returned to the pool of available IP address.

The Plugin

While the Neutron API represents the interface of the virtual network service to users and other services, these network services are implemented by a component called "Plugin". Plugins may adopt different techniques and technologies for providing isolated virtual networks to tenant, as well as providing other services such as IP address management. Users should not be concerned about the particular plugin employed as far as the API discussed in this document is concerned, as every plugin will implement all the operations included in the Neutron v2 API.

However, some plugins might expose additional capabilities through API extensions, discussed later in this document. For more information about the extensions exposed by a particular plugin, please refer to the plugin documentation.

Concepts

The Neutron v2 API manages three kind of entities:

  • Network, representing isolated virtual Layer-2 domains; a network can also be regarded as a virtual (or logical) switch;
  • Subnet, representing IPv4 or IPv6 address blocks from which IPs to be assigned to VMs on a given network are selected.
  • Port, representing virtual (or logical) switch ports on a given network.

All entities, discussed in detail in the rest of this chapter, support the basic CRUD operations with POST/GET/PUT/DELETE verbs, and have an auto-generated unique identifier.

Network

A network is a virtual isolated layer-2 broadcast domain which is typically reserved to the tenant who created it, unless the network has been explicitly configured to be shared. Tenants can create multiple networks, until they reach the thresholds specified by per-tenant Quotas (see next chapter for more details). The network is the principal entity for the Neutron API. Ports and subnets must always be associated with a network. The following table describes the attributes of network objects. For each attribute, the CRUD column should be read as follows:

  • C - the attribute can be used in create operations;
  • R - the attribute is returned in the response for show or list operations;
  • U - the value of attribute can be updated;
  • D - the value of the attribute can be removed;
Attribute Type Required CRUD Default Value Validation Constraints
id uuid-str N/A CR Generated UUID_PATTERN
name String No CRU None N/A
admin_state_up Bool No CRU True { True | False }
status String N/A R N/A N/A
subnets list(uuid-str) No R Empty List N/A
shared Bool No CRU False { True | False }
tenant_id uuid-str No* CR N/A N/A

Subnet

A subnet represents an IP address block that can be used for assigning 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. All this information will then be pushed to instances whose interfaces are associated with the subnet.

Attribute Type Required CRUD Default Validation Constraints
id uuid-str N/A CR Generated UUID_PATTERN
name String No CRU None N/A
network_id uuid-str Yes CR Generated Existing network identifier.
ip_version int Yes CR 4 { 4 | 6 }
cidr string Yes CR N/A Valid CIDR in the form <network_address>/<prefix>
gateway_ip string or null No CRUD First address in CIDR Valid IP address or null
dns_nameservers list(str) No CRU None Configurable maximum amount of nameservers per subnet. The default is 5.
allocation_pools list(dict) No CR Every address in CIDR, excluding gateway IP if configured Start/end of range must be valid IP
host_routes list(dict) No CRU Default route to gateway_ip {'destination': <CIDR>, "nexthop": <valid IP address>}. Configurable maximum amount of routes per subnet. The default is 20.
enable_dhcp Bool No CRU True { True | False }
tenant_id uuid-str No* CR N/A N/A

Port

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 Default Validation Constraints
id uuid-str N/A CR Generated UUID_PATTERN
name String No CRU None N/A
network_id uuid-str Yes CR N/A Existing network identifier.
admin_state_up bool No CRU True { True | False }
status string N/A R N/A N/A
mac_address string No CR Generated Valid MAC in 6-octet form separated by colons.
fixed_ips list(dict) No CRU Automatically allocated from pool. Valid IP address and existing subnet identifier.
device_id str No CRUD None No constraint
device_owner str No CRUD None No constraint
tenant_id uuid-str No* CR N/A N/A

* The tenant_id attribute is mandatory if Neutron is not running with the Keystone Identity service

General API information

Authentication and authorization

Neutron uses the Keystone identity service (http://keystone.openstack.org) as the default authentication service. When keystone is enabled Users submitting requests to the Neutron service must provide an authentication token in X-Auth-Token request header. The aforementioned token should have been obtained by authenticating with the keystone endpoint. For more information concerning authentication with Keystone, please refer to the Keystone documentation. When keystone is enabled, it is not mandatory to specify tenant_id for resources in create requests, as the tenant identifier will be derived from the Authentication token. Please note that the default authorization settings only allow administrative users to create resources on behalf of a different tenant.

Neutron uses information received from Keystone to authorize user requests. Neutron handles two kind of authorization policies:

  • Operation-based: policy specifying access criteria for specific operations, possibly with fine-grained control over specific attributes
  • Resource-based: whether access to specific resource might be granted or not according to the permissions configured for the resource (currently available only for the network resource)

The actual authorization policies enforced in Neutron might vary from deployment to deployment.

Request and Response types

The OpenStack Neutron API supports the JSON data format. The format for both the request and the response can be specified either using the Accept header or adding the .json extension to the request URI.

Example: Request/Response with Headers: JSON

Request:


POST /v1.0/tenants/tenantX/networks HTTP/1.1
Host 127.0.0.1:9696
Content-Type application/json
Accept application/json
Content-Length 57

{
 "network":
    {
      "name": "net-name",
      "admin_state_up": true
    }
}

Response:


HTTP/1.1 200 Accepted
Content-Type application/json
Content-Length 204

{
 "network":
    {
     "status": "ACTIVE",
     "subnets": [],
     "name": "net-name",
     "admin_state_up": true,
     "tenant_id": "388a70781bae4ca895f17b7f6293eb70",
     "shared": false, "id": "2a4017ef-31ff-496a-9294-e96ecc3bc9c9"
    }
}

NOTE: We have still to finalize a decision concerning XML support. Quantum v2 API XML blueprint

Filtering and Column Selection

The Neutron API supports filtering based on all top level attributes of a resource. Filters are applicable to all list requests. For instance:


GET /v2.0/networks?name=foobar

will return all the networks whose name is foobar. When multiple filters are specified, the Neutron API will return only objects that satisfy all the filters, this applying an AND condition among filters. Neutron does not offer a mechanisms for ORing filters. To this aim, the user can submit a distinct request for each filters, and then build a set on the client-side from received responses.

By default, Neutron returns all attributes for any Show or List call. The Neutron API has a mechanism to limit the set of attributes returned (e.g., return just 'id'). Attributes returned from the Neutron API can be controller using the fields query parameter. For example the following request:


GET /v2.0/networks.json?fields=id&fields=name

will return only id and name for each network.

Synchronous vs Asynchronous Plugin Behavior

The Neutron API presents a logical model of network connectivity consisting of networks, ports, and subnets. It is up to the Neutron plugin to communicate with the underlying infrastructure to ensure packet forwarding is consistent with the logical model. A plugin might perform these operations asynchronously. This means that when an API client modifies the logical model using an HTTP POST, PUT, or DELETE, the API call may return prior to the plugin performing any modifications to underlying virtual and/or physical switching devices. The only guarantee an API client has is that all subsequent API calls will properly reflect the changed logical model. As a concrete example, consider the case where a client uses an HTTP PUT to set the attachment for a port. There is no guarantee that packets sent by the interface named in the attachment will be forwarded immediately once the HTTP call returns. However, there is a guarantee that a subsequent HTTP GET to view the attachment on that port would return the new attachment value. The "status" attribute, available for network and port resources might be used to understand whether the Neutron plugin has successfully completed the configuration of the interested resource.

Bulk Create Operations

The Neutron API allow for creating several objects of the same type in the same API request. Bulk create operations use exactly the same API as singleton create operations, with the only difference being that a list of objects, rather than a single object, is specified in the request body.

Bulk operations are always performed atomically, meaning that either all or none of the objects in the request body are created. Should the particular plugin does not support atomic operations, Neutron API will emulate the atomic behavior, thus ensuring users might expect the same behavior regardless of the particular plugin running in the backend.

Neutron might be deployed without support for bulk operations. In that case a 400 Bad Request error will be returned when the client attempts a bulk create operation.

For more details concerning how to submit bulk requests to the Neutron API, please refer to create operations discussed in the next chapter.

Quotas

[tbd] Yong to contribute

Notifications

[tbd] Yong to contribute

Extensions

The Neutron API is extensible. Extensions serve several purposes:

  • They allow the introduction of new features in the API without requiring a version change;
  • They allow the introduction of vendor specific niche functionality
  • They act as a proving ground for experimental functionalities which might be included in a future version of the API.

Applications can programmatically determine what extensions are available by performing a GET on the v2.0/extensions URI. Extensions may also be queried individually by their unique alias by performing a GET on the /v2.0/extensions/alias_name. This provides the simplest method of checking if an extension is available as an unavailable extension will issue an itemNotFound (404) response. Existing core API resources can be extended with new actions or extra attributes. Also, new resources can also be added as extensions. Extensions usually have tags that prevent clash with other extensions defining attributes and/or resources with the same name, and with core resources and attributes. As an extension might not be supported by all plugin, availability of an extension will vary with deployments and the specific plugin in use.

Faults

If a failure occurs while processing a request, the Neutron API returns an error response. Neutron uses only standard HTTP error codes. 4xx errors are indicative of problems in the particular request being sent from the client.

Error
4>|400 Bad Request
2>|404 Not Found
3>|409 Conflict
2>|400 Bad Request
500 Internal server error
503 ServiceUnavailable

Users submitting requests to the Neutron API might also receive the following errors:

  • 401 Unauthorized - if invalid credentials are provided
  • 403 Forbidden - If the user cannot access a specific resource or perform the requested operation.

API Operations

List Networks

Verb URI
GET /networks

This operation returns the list of all the network the tenants has access to. This includes networks owned by tenant and shared networks. By default, network objects will be returned with all their attributes. Users can control which attribute should be returned by using the field query parameter. Responses can be filtered by specifying search criteria on the query string. Only exact match supported at the moment.

Normal Response Code: 200

Error Response Codes: Unauthorized (401), Bad Request (400)

JSON Request and Response sample:

Request


GET /v2.0/networks
Accept: application/json

Response


{
  "networks": [
  {
    "status": "ACTIVE",
    "subnets": [],
    "name": "network_1",
    "admin_state_up": true,
    "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
    "id": "3a06dfc7-d239-4aad-9a57-21cd171c72e5",
    "shared": false
  },
  {
    "status": "ACTIVE",
    "subnets": [],
    "name": "network-2",
    "admin_state_up": true,
    "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
    "id": "7db8c5a4-6eb0-478d-856b-7cfda2b25e13",
    "shared": false
  },
  {
    "status": "ACTIVE",
    "subnets": ["e12f0c45-46e3-446a-b207-9474b27687a6"],
    "name": "network_3",
    "admin_state_up": true,
    "tenant_id": "ed680f49ff714162ab3612d7876ffce5",
    "id": "afc75773-640e-403c-9fff-62ba98db1f19",
    "shared": true
   }
 ]
}

Show Network

Verb URI
GET /networks/<network_id>

This operation returns the complete list of attributes for the network whose identifier is specified in the request URI, assuming the network exists and the user making the request is authorized to access it. The set of attributes which is actually returned by the API can be controller through the field query parameter.

Normal Response Code: 200

Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404)

JSON Request and Response sample:

Request:


GET /v2.0/networks/afc75773-640e-403c-9fff-62ba98db1f19
Accept: application/json

Response:


{
  "network":
  {
    "status": "ACTIVE",
    "subnets": ["e12f0c45-46e3-446a-b207-9474b27687a6"],
    "name": "network_3",
    "admin_state_up": true,
    "shared": false,
    "tenant_id": "ed680f49ff714162ab3612d7876ffce5",
    "id": "afc75773-640e-403c-9fff-62ba98db1f19"
  }
}

Create Network

Verb URI
POST /networks

This operation will create a new Neutron network. The identifier of the newly created network is returned in the response. The shared attribute can be used to create a public network, i.e.: a network which is shared with all other tenants. However, the current model of the Neutron API allows only for either completely private or completely open networks. More sophisticated mechanisms for specifying ACLs on networks will come in future releases of the API.

Moreover, control of the shared attribute could be reserved to particular users only, such as administrators. In this case, regular users trying to create a shared network will receive a 403 - Forbidden error.

Normal Response Code: 200

Error Response Codes: Unauthorized (401), Bad Request (400)

JSON Request and Response sample:

Request:


POST v2.0/networks.json
Content-Type: application/json
Accept: application/json

{
 "network":
  {
    "name": "sample_network",
    "admin_state_up": false
  }
}

Response:


'status': '201'
'content-length': '194'
'content-type': 'application/json;

{
  "network":
    {
      "status": "ACTIVE",
      "subnets": [],
      "name": "sample_network",
      "admin_state_up": false,
      "shared": false,
      "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
       "id": "fc68ea2c-b60b-4b4f-bd82-94ec81110766"
     }
}

Bulk version

The bulk version of operation allows for creating several networks with a single request. The behavior of the bulk create operation is always atomic: either all networks in the request body are created, or none of them is created. To this aim, a list of networks must be supplied in the request body, as follows:

JSON Request and Response sample:

Request:


POST v2.0/networks.json

Content-Type: application/json
Accept: application/json

{
"networks": [
   {
     "name": "sample_network_1",
     "admin_state_up": false
   },
   {
     "name": "sample_network_2",
     "admin_state_up": false
   }]
}

Update Network

Verb URI
PUT /networks/<network-id>

The update network operation allow users for updating some attributes of a network object, such as name and admin_state_up. Attributes such as tenant_id cannot be updated. If an attempt is made to update such attributes a 422 'Unprocesable Entity' error will be returned.

Users authorized to control the shared attribute are also allowed to change it. While sharing a previously private network is always possible, the opposite is not always true. If the user attempts to turn private a shared network with subnets and/or ports belonging to tenants different from the network owner, a 409 Conflict error will be returned.

Note: Update operations in Neutron adopt patch semantics. This implies that the Neutron API does not require the user to send the whole resource to be updated, but just the attributes that the user wishes to update, as reported in the example below.

Normal Response Code: 200 Ok

Error Response Codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found

JSON Request and Response sample:

Request:


PUT /v2.0/networks/fc68ea2c-b60b-4b4f-bd82-94ec81110766.json

Content-Type: application/json
Accept: application/json

{
  "network":
    {
      "name": "updated_name"
    }
}

Response:


status: 200
content-length: 192
content-type: application/json

{
  "network":
    {"status": "ACTIVE",
     "subnets": [],
     "name": "updated_name",
     "admin_state_up": false,
     "shared": false,
      "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
      "id": "fc68ea2c-b60b-4b4f-bd82-94ec81110766"}}

Delete Network

Verb URI
DELETE /networks/<network_id>

JSON Request and Response sample:

This operation will remove a Neutron network, and all its associated subnets, provided that no port is currently configured on the network. If ports are still configured on the network being removed, a 409 error will be returned.

Normal Response Code: 204

Error Response Codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Network in Use.

Request:


DELETE /v2.0/networks/fc68ea2c-b60b-4b4f-bd82-94ec81110766

Content-Type: application/json
Accept: application/json

Response:


status: 204

List Subnets

Verb URI
GET /subnets

This operation will return a list of subnets objects the tenant has access to. Default policy settings will return exclusively subnets owned by the tenant submitting the request, unless the request is submitted by an user with administrative rigths. Users can control which attributes should be returned using the fields query parameter as discussed in the previous chapter. Moreover, results can be filtered using query string parameters as discussed in the previous chapter.

This operation does not require a reques body.

Normal Response Code: 200 Ok

Error Response Codes: 401 Unauthorized

JSON Request and Response sample:

Request:


GET v2.0/subnets.json

Accept: application/json

Response:


status: 200
content-length: 607
content-type: application/json

{
  "subnets": [
   {
     "name": "",
     "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
     "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
     "allocation_pools": [{"start": "10.10.0.2", "end": "10.10.0.254"}],
     "gateway_ip": "10.10.0.1",
     "ip_version": 4,
     "cidr": "10.10.0.0/24",
     "id": "4156c7a5-e8c4-4aff-a6e1-8f3c7bc83861",
     "enable_dhcp": true
    },
    {
      "name": "",
      "network_id": "afc75773-640e-403c-9fff-62ba98db1f19",
      "tenant_id": "ed680f49ff714162ab3612d7876ffce5",
      "allocation_pools": [{"start": "10.0.0.2", "end": "10.0.0.254"}],
      "gateway_ip": "10.0.0.1",
      "ip_version": 4,
      "cidr": "10.0.0.0/24",
      "id": "e12f0c45-46e3-446a-b207-9474b27687a6",
      "enable_dhcp": true
     }]
}

Show Subnet

Verb URI
GET /subnets/<subnet-id>

This operation returns data about the subnet specified in the request URI. Users can control which attributes should be returned using the fields query parameter as discussed in the previous chapter. If the user submitting the request is not authorized to access the requested subnet, or if the requested subnet does not exist, a 404 error will be returned.

This operation does not require a request body.

Normal Response Code: 200 Ok

Error Response Codes: 400 Bad Request, 401 Unauthorized, 404 Not Found

JSON Request and Response sample:

Request:


GET /v2.0/subnets/4156c7a5-e8c4-4aff-a6e1-8f3c7bc83861

Accept: application/json

Response:


status: 200
content-length: 309
content-type: application/json

{
  "subnet":
    {
     "name": "",
     "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
     "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
     "allocation_pools": [{"start": "10.10.0.2", "end": "10.10.0.254"}],
     "gateway_ip": "10.10.0.1",
     "ip_version": 4,
     "cidr": "10.10.0.0/24",
     "id": "4156c7a5-e8c4-4aff-a6e1-8f3c7bc83861",
     "enable_dhcp": false,
    }
}

Create Subnet

Verb URI
POST /subnets

This operation creates a new subnet on a specific network. The identifier of the network, network_id is mandatory. The user must also specify the cidr for the subnet, in the form <network_address>/<prefix>. The remaining parameters are optional.

By default, Neutron creates IP v4 subnets. In order to create an IP v6 subnet, users must specify the value 6 for the ip_version attribute in the request body. Please note that Neutron does not make any attempt to derive the correct IP version from the provided CIDR. If the parameter for the gateway address, gateway_ip is not specified, then Neutron will allocate an address from the subnet's cidr for the subnet's gateway. In order to specify a subnet without a gateway, users should specify the value null for the gateway_ip attribute in the request body. If allocation pools (attribute allocation_pools) are not specified, Neutron will automatically allocate pools for covering all IP addresses in the CIDR, excluding the address reserved for the subnet gateway. Otherwise users can explicitly specify allocation pools as shown in the example below.

Finally, a subnet by default will leverage DHCP for distributing addresses to VMs. If a different strategy is used, such as, for instance, file system IP configuration injection, the enable_dhcp attribute should be explicitly set to False in a create_subnet request.

Normal Response Code: 201 Created

Error Response Codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found

JSON Request and Response sample:

Request:


POST /v2.0/subnets
Content-Type: application/json
Accept: application/json

{
  "subnet": {
    "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
    "ip_version": 4,
    "cidr": "10.0.3.0/24",
    "allocation_pools": [{"start": "10.0.3.20", "end": "10.0.3.150"}]
  }
}
}}

Response:
{{{
status: 201,
content-length: 306,
content-type: application/json

{
  "subnet": {
    "name": "",
    "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
    "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
    "allocation_pools": [{"start": "10.0.3.20", "end": "10.0.3.150"}],
    "gateway_ip": "10.0.3.1",
    "ip_version": 4,
    "cidr": "10.0.3.0/24",
    "id": "9436e561-47bf-436a-b1f1-fe23a926e031",
    "enable_dhcp": true}
}

Bulk version

This operation allows for creating several subnets with a single request. To this aim, a list of subnets must be supplied in the request body. The behavior of the operation is always atomic, meaning that either all subnets are created, or none is created.

Request:


POST /v2.0/subnets
Content-Type: application/json
Accept: application/json

{
  "subnets": [
    {
      "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
      "ip_version": 4,
       "cidr": "10.0.4.0/24",
    }
    {
      "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
      "ip_version": 4,
       "cidr": "10.0.5.0/24",
    }
   ]
}

Update Subnet

Verb URI
PUT /subnets/<subnet-id>

This operation updates information concerning a subnet. Some attributes, such as IP version (ip_version), CIDR (cidr), and IP allocation pools ('allocation_pools) cannot be updated. Attempting to update these attributes will result in a 400 Bad Request error.

After updating host_routes and dns_nameservers attributes, there is no guarantee about when these changes will be reflected on running VM instances. The only responsibility of the Neutron API is to update the data model with the new information. When these information are then propagated on running VMs depends on the mechanism used for providing them with IP configuration. In case of DHCP, this will happen as soon as the VMs send a new DHCP request, and therefore it is likely to happen either when the DHCP lease expires or when the VM is rebooted.

Note: Update operations in Neutron adopt patch semantics. This implies that the Neutron API does not require the user to send the whole resource to be updated, but just the attributes that the user wishes to update, as reported in the example below

Normal Response Code: 200 Ok

Error Response Codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 400 Bad Request

JSON Request and Response sample:

Request:


PUT /v2.0/subnets/9436e561-47bf-436a-b1f1-fe23a926e031

Content-Type: application/json
Accept: application/json

{
  "subnet":
    {
      "gateway_ip": "10.0.3.254",
      "name": "new_name"
    }
}

Response:


status: 200
content-length: 316
content-type: application/json

{
  "subnet":
   {
     "name": "new_name",
     "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
     "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
     "allocation_pools": [{"start": "10.0.3.20", "end": "10.0.3.150"}],
     "gateway_ip": "10.0.3.254",
     "ip_version": 4,
     "cidr": "10.0.3.0/24",
     "enable_dhcp": true,
     "id": "9436e561-47bf-436a-b1f1-fe23a926e031"
   }
}

Delete Subnet

Verb URI
DELETE /subnets/<subnetid>

This operation remove a subnet from a Neutron network. The operation will fail if IPs from the subnet being removed are still allocated.

Normal Response Code: 204

Error Response Codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict

JSON Request and Response sample:

Request:


DELETE /v2.0/subnets/9436e561-47bf-436a-b1f1-fe23a926e031

Accept: application/json

Response:


Status: 204

List Ports

Verb URI
GET /ports

This operation will return a list of ports objects the tenant has access to. Default policy settings will return exclusively subnets owned by the tenant submitting the request, unless the request is submitted by an user with administrative rigths. Users can control which attributes should be returned using the fields query parameter as discussed in the previous chapter. Moreover, results can be filtered using query string parameters as discussed in the previous chapter.

This operation does not require a reques body.

Normal Response code: 200

Error Response Code: 401 Unauthorized

JSON Request and Response sample:

Request:


GET /v2.0/ports.json HTTP/1.1
accept: application/json

Response:


Status: 200
Content-Type: application/json
Content-Length: 805

{
    "ports": [
        {
            "admin_state_up": true,
            "device_id": "257614cc-e178-4c92-9c61-3b28d40eca44",
            "device_owner": "",
            "fixed_ips": [
                {
                    "ip_address": "192.168.111.3",
                    "subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
                }
            ],
            "id": "24e6637e-c521-45fc-8b8b-d7331aa3c99f",
            "mac_address": "fa:16:3e:0f:3f:b5",
            "name": "",
            "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
            "status": "ACTIVE",
            "tenant_id": "cf1a5775e766426cb1968766d0191908"
        },
        {
            "admin_state_up": true,
            "device_id": "d266f9de-fe2c-4705-93b3-9da71168c93b",
            "device_owner": "",
            "fixed_ips": [
                {
                    "ip_address": "192.168.111.2",
                    "subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
                }
            ],
            "id": "e54dfd9b-ce6e-47f7-af47-1609cfd1cdb0",
            "mac_address": "fa:16:3e:f5:41:7f",
            "name": "",
            "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
            "status": "ACTIVE",
            "tenant_id": "cf1a5775e766426cb1968766d0191908"
        }
    ]
}

Show Port

Verb URI
GET /ports/port-id

This operation will return information regarding the port specified in the request URI. If the port does not exist or the user submitting the request is not authorized to access it, a 404 error is returned.

Normal Response code: 200

Error Response Code: 400 Bad Request, 401 Unauthorized, 404 Not Found

JSON Request and Response sample:

Request:


GET /v2.0/ports/ebe69f1e-bc26-4db5-bed0-c0afb4afe3db.json
accept: application/json

Response:


Status: 200
Content-Type: application/json
Content-Length: 410

{
    "port": {
        "admin_state_up": true,
        "device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
        "device_owner": "",
        "fixed_ips": [
            {
                "ip_address": "192.168.111.4",
                "subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
            }
        ],
        "id": "ebe69f1e-bc26-4db5-bed0-c0afb4afe3db",
        "mac_address": "fa:16:3e:a6:50:c1",
        "name": "port1",
        "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
        "status": "ACTIVE",
        "tenant_id": "cf1a5775e766426cb1968766d0191908"
    }
}

Create Port

Verb URI
POST /ports

This operation creates a new Neutron port. The network where the port shall be created (network_id parameter) in the request body, must be specified. Optionally, user can also specify the following parameters:

  • A symbolic name for the port
  • MAC address
  • Administrative state (True: Up, False: Down)
  • Fixed IPs
    • Specifying just a subnet id, Neutron allocates the first available IP from that subnet to the port
    • Specifying both a subnet id and an IP address, Neutron will try to allocate the specified address to the port
  • Identifier of the device attached to the port (e.g.: VM identifier)
  • Identifier of the owner of the device attached to the port (e.g.: DHCP agent identifier)

Normal Response code: 201

Error Response Code: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict

JSON Request and Response sample:

Request:


POST /v2.0/ports.json HTTP/1.1
Content-Length: 158
content-type: application/json
accept: application/json

{
    "port": {
        "admin_state_up": true,
        "device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
        "name": "port1",
        "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12"
    }
}

Response:


Status: 201
Content-Type: application/json; charset=UTF-8
Content-Length: 410

{
    "port": {
        "admin_state_up": true,
        "device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
        "device_owner": "",
        "fixed_ips": [
            {
                "ip_address": "192.168.111.4",
                "subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
            }
        ],
        "id": "ebe69f1e-bc26-4db5-bed0-c0afb4afe3db",
        "mac_address": "fa:16:3e:a6:50:c1",
        "name": "port1",
        "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
        "status": "ACTIVE",
        "tenant_id": "cf1a5775e766426cb1968766d0191908"
    }
}

Bulk version

This operation allows for creating several ports with a single request. To this aim, a list of ports must be supplied in the request body. The Neutron API always guarantees the atomic completion of the bulk operation.

Bulk Request example:


{
    "ports": [
        {
         "admin_state_up": true,
         "device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
         "name": "port1",
         "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12"
        },
        {
         "admin_state_up": true,
         "device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
         "name": "port2",
         "network_id": "2cd34a97-e087-75fb-9904-dd12937009ea"
        }
     ]
}

Update Port

Verb URI
UPDATE /ports/<port-id>

This operation can be used for updating information on a port, such as the symbolic name and the associated IPs. When IPs for a port are updated, the previously associated IPs are removed, returned to the respective subnets allocation pools, and replaced by the IPs specified in the body for the Update request. In other words, the behavior of this operation is to replace the fixed_ip attribute when it is specified in the request body. If the new IP addresses are invalid (e.g.: already in use), the operation fail and the existing IP addresses are not disassociated from the port.

Please note that the only responsibility of the API is to update the data model with the new IP association information. The way in which IP addresses are actually updated on running VMs depends on the particular mechanism used to propagate IP configuration. In case of DHCP, this would happen either when the DHCP lease expires, or when the VM is rebooted.

Normal Response code: 200

Error Response Code: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict

JSON Request and Response sample:

Request:


PUT /v2.0/ports/1d8591f4-7b62-428e-857d-e82a15e5a7f1.json HTTP/1.1
Content-Length: 63
content-type: application/json
accept: application/json

{
    "port": {
        "device_id": "37b4f622-5e17-4dca-bf67-7338c5b7dd63"
    }
}

Response:


Status: 200
Content-Type: application/json;
Content-Length: 410

{
    "port": {
        "admin_state_up": true,
        "device_id": "37b4f622-5e17-4dca-bf67-7338c5b7dd63",
        "fixed_ips": [
            {
                "ip_address": "192.168.111.4",
                "subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
            }
        ],
        "id": "1d8591f4-7b62-428e-857d-e82a15e5a7f1",
        "mac_address": "fa:16:3e:70:d2:8c",
        "name": "port2",
        "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
        "status": "ACTIVE",
        "tenant_id": "cf1a5775e766426cb1968766d0191908"
    }
}

Delete Port

Verb URI
DELETE /ports/<port-id>

This operation removes a port from a Neutron network. If IP addresses are associated with the port, they are returned to the respective subnets allocation pools.

Normal Response code: 204

Error Response Code: 401 Unauthorized, 403 Forbidden, 404 Not Found

JSON Request and Response sample:

Request:


DELETE /v2.0/ports/ebe69f1e-bc26-4db5-bed0-c0afb4afe3db.json
accept: application/json

Response:


status: 204