Jump to: navigation, search

Difference between revisions of "Neutron/APIv2-specification"

Line 17: Line 17:
  
 
* 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") (may be combined with step above)
+
* Tenant associates a subnet with that network (e.g., "10.0.0.0/24")  
−
* Tenant boots a VM, specifying a single NIC connected to "net1".
+
** As subnets may be specified in the "create network" request, this step and the one above can be merged
−
* Nova contacts Quantum and creates a port1 on net1.  port1 is assigned IP (e.g., 10.0.0.2).
+
* 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.   
 +
* Quantum assigns an Ip to port1 is assigned IP. (The IP is chosen by Quantum)
 
* Tenant destroys VM.
 
* Tenant destroys VM.
−
* Nova contacts Quantum and destroys port1. IP (e.g., 10.0.0.2) is returned to pool.
+
* Nova contacts Quantum and destroys port1. Allocated IP is returned to the pool of available IP address.
  
−
The API supports many more options and some alternative flows (e.g., user requesting an IP), but the above flow is a good place to start.
+
=== The Plugin ===
 +
 
 +
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.
  
−
More advanced capabilities, including Security Groups, L3-forwarding between different Quantum Networks, Floating IPs, etc. will be implemented as API extensions in Folsom.
+
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.
  
−
=== The Plugin ===
+
== Concepts ==
  
−
A brief discussion of what a plugin is. Maybe just provide list of available plugins.
+
The Quantum v2 API manages three kind of entities:
 +
* '''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.
 +
* '''Port''', representing virtual (or logical) switch ports on a given network.
  
−
== Concepts ==
+
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.
−
All entities support the basic CRUD operations with POST/GET/PUT/DELETE operations on an entity + UUID URL (e.g., /v2.0/networks/98bd8391-199f-4440-824d-8659e4906786) as well as search operations with filtering using a GET on the base entity URL (e.g., /v2.0/networks ).
 
  
 
=== Network ===
 
=== Network ===
−
/v2.0/networks
+
 
 +
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;
 +
* R - the attribute is returned in the response for '''show''' or '''list''' operations;
 +
* U - the attribute can be used in '''update''' operations;
 +
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
−
| attribute
+
| Attribute
 
| Type  
 
| Type  
 
| Required  
 
| Required  
−
| CRUD
+
| CRU
−
| Default  
+
| Default Value
 +
|  Validation Constraints
 
|-
 
|-
 
| id  
 
| id  
 
| uuid-str  
 
| uuid-str  
−
| -
+
| N/A
−
| R  
+
| R  
 
| generated  
 
| generated  
 +
|  UUID_PATTERN
 
|-
 
|-
 
| name  
 
| name  
−
| str
+
| String
−
| Y
+
| No
−
| CRU  
+
| CRU  
−
| -
+
|
 +
|  None
 +
|  N/A
 
|-
 
|-
 
| admin_state_up  
 
| admin_state_up  
−
| bool
+
| Bool
−
| N
+
| No
 
| CRU  
 
| CRU  
−
| True  
+
| True  
 +
|  { True | False }
 
|-
 
|-
 
| status  
 
| status  
−
| str
+
| String
−
| -
+
| N/A
−
| R  
+
| R  
 
| -  
 
| -  
 
|-
 
|-
 
| tenant_id  
 
| tenant_id  
−
| str (uuid?)  
+
| str (uuid?)  
 
| N  
 
| N  
 
| CR (U?)  
 
| CR (U?)  
Line 78: Line 97:
 
| CRU  
 
| CRU  
 
| []  
 
| []  
 +
|-
 +
| permissions
 
|}
 
|}
  
Line 382: Line 403:
 
* supports filtering based on all top level attributes of an API entity.  For example, GET /v2.0/networks?name=foobar
 
* supports filtering based on all top level attributes of an API entity.  For example, GET /v2.0/networks?name=foobar
 
* by default, returns all attributes for any Show or List call.  Has mechanism to limit the set of attributes returned (e.g., return just 'id').  Also has "verbose" mechanism to 'explode' UUID references within a returned object.  For example, doing a GET on network, and having a GET on a network return the fully populated data for all associated subnets.
 
* by default, returns all attributes for any Show or List call.  Has mechanism to limit the set of attributes returned (e.g., return just 'id').  Also has "verbose" mechanism to 'explode' UUID references within a returned object.  For example, doing a GET on network, and having a GET on a network return the fully populated data for all associated subnets.
−
 
−
== Notable Non-IPAM Changes from v1.1 ==
 
−
* ports are flattened to be a top level resource.  Goal was to be able to search over ports without knowing net-id, and have searches return results from multiple networks (e.g., all ports associated with a device)
 
−
* bulk create operations for networks, ports, and subnets  (idea is to more efficiently handle creating many items?)
 
−
* tenant-id is not longer represented in the URL.  This is more inline with other openstack services.
 
−
* no notion of an attachment and attachment-id.  Instead, service integrating with Quantum (e.g., Nova) must be aware of port-ids, and communicate the binding between a port-id and a vswitch/pswitch port to Quantum.  This simplifies the API, and the Nova / Quantum integration.
 
−
 
−
== Open Questions ==
 
−
(not a complete list, please add)
 
−
 
−
* Does each subnet + port need a tenant-id, or does it inherit the tenant-id of the network?  How does this interact with the Authz need to delegate control of a port?
 
−
* With bulk create, how are errors handled if there is a failure in adding one of the items?
 
−
* How to best represent fixed IPs on a port?  How to best view the allocated IPs on a subnet?  Should ports have a reference to the subnet so you can easily get all ports with IPs on the subnet?  Or should subnet have attribute or sub-url for all allocated ports?
 
−
** How about modifying the fixed_ips_v* fields of Port to be addresses + prefix length or, better, (IP address, subnet ID) pairs? In that case, only one fixed_ips field is necessary, since each subnet indicates the IP version, and we can have a list mixing IPv4 and IPv6 addresses: [{"address": "192.168.1.1", "subnet_id": "fabdaafb-a723-4e59-8b0a-3d28239df66a"}, {"address":  "fe80::ca2a:14ff:fe43:...", "subnet_id": "..."}].
 
−
* Is there no way of detaching a interface from a port or moving it between networks now?  (Or could this still be achieved on the nova side of things?)
 
−
* It would be nice if, as well as the this API documentation, there was a description of how you bind an interface (or tunnel endpoint, or whatever else) to a port.  It's nicer to have it written out than having to reason it out of the [[QuantumManager]] and friends.
 
−
* How do we specify some kind of limit on the 'list' attributes?  I suspect we would not want to allow someone specifying a thousand DNS servers for a subnet.  Should all list attributes have a MAX_LEN specified?
 
−
* Do we need port to have hosts information, the subnet's hosts are not enough?
 

Revision as of 11:15, 4 August 2012

Quantum v2 API

Overview

Quantum 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 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 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 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 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 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

  • Tenant creates a network (e.g., "net1")
  • Tenant associates a subnet with that network (e.g., "10.0.0.0/24")
    • As subnets may be specified in the "create network" request, this step and the one above can be merged
  • 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.
  • Quantum assigns an Ip to port1 is assigned IP. (The IP is chosen by Quantum)
  • Tenant destroys VM.
  • Nova contacts Quantum and destroys port1. Allocated IP is returned to the pool of available IP address.

The Plugin

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.

Concepts

The Quantum v2 API manages three kind of entities:

  • 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.
  • 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 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;
  • R - the attribute is returned in the response for show or list operations;
  • U - the attribute can be used in update operations;
Attribute Type Required CRU Default Value Validation Constraints
id uuid-str N/A R generated UUID_PATTERN
name String No CRU None N/A
admin_state_up Bool No CRU True False }
status String N/A R -
tenant_id str (uuid?) N CR (U?) keystone-tenant
subnets list(uuid) N CRU []
permissions

Subnet

/v2.0/subnets

attribute Type Required CRUD Default
id uuid-str - R generated
network_id uuid-str Y CR -
ip_version int (4,6) Y CR -
cidr str Y CR -
gateway_ip str N CRUD .1 of cidr
dns_nameservers list[str]] N CRU config-option?
allocation_pools list(dict) N CRU start + 1 to end - 1
host_routes list(dict) N CRU default route to gateway_ip

Port

/v2.0/ports

attribute Type Required CRUD Default
id uuid-str - R generated
network_id uuid-str Y CR -
admin_state_up bool N CRU True
status str - R -
mac_address str N CR generated
fixed_ips list(dict) N CR (U?) allocated
host_routes list(dict) N CR (U?) inherit from subnet
device_id str N CRUD ""

params="{\"network\": {\"tenant_id\": \"default\", \"name\": \"net1\", \"admin_state_up\": true}}"

General API information

Authentication

Authorization

Action-Based policies

ciao

Resource-Based policies

ciao

Request and Response types

Synchronous vs Asynchronous Plugin Behavior

MAC allocation policy

xxx

IP Adress Management

yyy

Bulk Create Operations

yeah I start with bulk

Quotas

[tbd] This is for Yong

Notifications

[tbd] This is for Yong

Extensions

Faults

API Operations

List Network

Show Network

Create Network

Bulk version

Note about 'public' networks (permissions 0644)

sono proprio stronzo

Update Network

Delete Network

List Subnets

Show Subnet

Create Subnet

Bulk version

Update Subnet

Delete Subnet

List Ports

Show Port

Create Port

Bulk version

Update Port

Delete Port

API usage samples

Find a bunch of common uses cases and then post request and response formats

Basic JSON example

Create a network, a subnet on that network, and a port on that network. Remember that the port is likely to be created by Nova on behalf of a tenant.

POST /v2.0/networks

Request: 


{
  "network": {  
      "name" : "net1"
      "tenant_id": a4fc5328-c270-4891-845a-e61c9153d261
      "admin_state_up": true
   }
}

Response: 


{
   "network": {
      "status": "ACTIVE", 
      "subnets": [], 
      "name": "net1",
      "admin_state_up": true, 
      "tenant_id": "a4fc5328-c270-4891-845a-e61c9153d261", 
      "id": "c4863456-2c40-44f2-ab9f-63f978a8a4f3"
    }
}

POST /v2.0/subnets

Request: 


{
  "subnet": {
      "network_id": "98bd8391-199f-4440-824d-8659e4906786",
      "ip_version": 4,
      "cidr": "10.0.0.0/24",
   }
}

Response: 


{
 "subnet": {
    "id": "e76a23fe-b028-47b8-a765-858b65c0f857",
    "network_id": "98bd8391-199f-4440-824d-8659e4906786",
    "ip_version": 4,
    "cidr": "10.0.0.0/24",
    "gateway_ip": "10.0.0.1",
    "dns_nameservers": ["8.8.8.8"],
    "allocation_pools": [ { "start" : "10.0.0.2", "end": "10.0.0.254"}],
    "host_routes": [],
 }
}

POST /v2.0/ports 


{
  "port": { 
    "network_id": "98bd8391-199f-4440-824d-8659e4906786",
    "device_id": "32aeb491-4e78-4c24-8ab8-363daa65aa4d"
  }
}

Response: 


{
  "port": { 
    "id": "b08a3807-5d3b-4ab8-95ce-3ed5aa28bdf6",
    "network_id": "98bd8391-199f-4440-824d-8659e4906786",
    "admin_state_up": True,
    "status": "ACTIVE",
    "mac_address": "ca:fe:de:ad:be:ef",
    "fixed_ips": [ "10.0.0.2" ],
    "host_routes":  [ { "destination": "0.0.0.0/0", "nexthop" : "10.0.0.1" },
                           { "destination": "10.0.0.0/24", "nexthop": Null }],
    "device_id": "32aeb491-4e78-4c24-8ab8-363daa65aa4d",
  } 
}

Other capabilities

  • supports filtering based on all top level attributes of an API entity. For example, GET /v2.0/networks?name=foobar
  • by default, returns all attributes for any Show or List call. Has mechanism to limit the set of attributes returned (e.g., return just 'id'). Also has "verbose" mechanism to 'explode' UUID references within a returned object. For example, doing a GET on network, and having a GET on a network return the fully populated data for all associated subnets.
Retrieved from "https://wiki.openstack.org/w/index.php?title=Neutron/APIv2-specification&oldid=11879"