Revision as of 23:04, 5 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")
• 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 value of attribute can be updated;
• D - the value of the attribute can be removed;

Subnet

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

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.

• The tenant_id attribute is mandatory if Quantum 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

Authentication and authorization

Quantum uses the Keystone identity service (openstack.keystone.org) as the default authentication service. 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.

Request and Response types

TBD Once we sort out XML support for Quantum.

Filtering and Column Selection

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

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

will return only id and name for each network.

Synchronous vs Asynchronous Plugin Behavior

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

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, Quantum API will emulate the atomic behavior, thus ensuring users might expect the same behavior regardless of the particular plugin running in the backend.

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 Quantum API, please refer to create operations discussed in the next chapter.

Quotas

[tbd] Yong to contribute

Notifications

[tbd] Yong to contribute

Extensions

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

Users submitting requests to the Quantum 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

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",
  "permissions": "rw-------"}, 
 {"status": "ACTIVE",
  "subnets": [],
  "name": "network-2",
  "admin_state_up": true,
  "tenant_id": "c1210485b2424d48804aad5d39c61b8f",
  "id": "7db8c5a4-6eb0-478d-856b-7cfda2b25e13",
  "permissions": "rw-------"}, 
 {"status": "ACTIVE",
  "subnets": ["e12f0c45-46e3-446a-b207-9474b27687a6"],
  "name": "network_3",
  "admin_state_up": true,
  "tenant_id": "ed680f49ff714162ab3612d7876ffce5",
  "id": "afc75773-640e-403c-9fff-62ba98db1f19",
  "permissions": "rw-r--r--"}]
}

This operation does not require a request body, unless the Quantum server is running without Keystone integration. In this case the request will look like the following:

PUT EXAMPLE HERE

Show Network

Normal Response Code: 200

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

Create Network

Normal Response Code: 200

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

Bulk version

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:

<PUT example here>

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

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

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

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