Difference between revisions of "QuantumV2APIIntro"
| Line 8: | Line 8: | ||
You're encouraged to to through the code once you read this overview. | You're encouraged to to through the code once you read this overview. | ||
| − | == Summary == | + | == Summary == |
| − | The v2.0 API represents a combination of the [ | + | 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 enity, called a Subnet. Subnets can represent either a v4 or v6 address block, and each Quantum Network 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 of one of the subnets for each IP version. When the Port is destroyed, the allocated addresses return to the pool of available IPs on the subnet. | ||
| + | |||
| + | Basic high-level flow: | ||
| + | * tenant creates a network (e.g., "net1") | ||
| + | * tenant associate a subnet with that network (e.g., "10.0.0.0/24") (may be combined with step above) | ||
| + | * tenant boots a VM, specifying a single NIC connected to "net1". | ||
| + | * Nova contacts Quantum and creates a port1 on net1. port1 is assigned IP (e.g., 10.0.0.2). | ||
| + | * tenant destroys VM. | ||
| + | * Nova contacts Quantum and destroys port1. IP (e.g., 10.0.0.2) is returned to pool. | ||
| + | |||
| + | 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. | ||
| + | |||
| + | == Entities == | ||
| + | |||
| + | === Network === | ||
| + | |||
| + | Note: current code uses underscores, but may change to dashes. | ||
| + | |||
| + | {| border="1" cellpadding="2" cellspacing="0" | ||
| + | | attribute | ||
| + | | Type | ||
| + | | Required | ||
| + | | CRUD | ||
| + | | Default | ||
| + | | Explanation/Notes | ||
| + | |- | ||
| + | | id | ||
| + | | uuid-str | ||
| + | | - | ||
| + | | R | ||
| + | | - | ||
| + | | UUID representing the network | ||
| + | |- | ||
| + | | name | ||
| + | | str | ||
| + | | Y | ||
| + | | CRU | ||
| + | | - | ||
| + | |- | ||
| + | | admin_state_up | ||
| + | | bool | ||
| + | | N | ||
| + | | CRU | ||
| + | | True | ||
| + | |- | ||
| + | | op_status | ||
| + | | str | ||
| + | | - | ||
| + | | R | ||
| + | | - | ||
| + | |- | ||
| + | | tenant_id | ||
| + | | str (uuid?) | ||
| + | | N | ||
| + | | CR (?) | ||
| + | | keystone-tenant | ||
| + | | owner of network. only admin user can specify a tenant_id other than its own. | ||
| + | |- | ||
| + | | subnets | ||
| + | | list(uuid) | ||
| + | | N | ||
| + | | CRUD | ||
| + | | [] | ||
| + | | subnets associated with this network. Plan to allow fully specified subnets as part of network create | ||
Revision as of 19:22, 4 June 2012
= Quantum Developer v2 API Intro =
The goal of this document is to quickly get a Quantum developer who is already familiar with how things worked with the v1.0 and v1.1 API up to speed on the v2.0 API. Full API specification (i.e., http://docs.openstack.org/api/openstack-network/1.0/content/index.html) will be coming as well, but this document is an attempt to jumpstart developers who have Folsom-2 work that requires using v2.0 API.
The v2.0 API code is available for review here: https://review.openstack.org/#/c/8039/
You're encouraged to to through the code once you read this overview.
== Summary ==
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 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 of one of the subnets for each IP version. When the Port is destroyed, the allocated addresses return to the pool of available IPs on the subnet.
Basic high-level flow:
- tenant creates a network (e.g., "net1")
- tenant associate a subnet with that network (e.g., "10.0.0.0/24") (may be combined with step above)
- tenant boots a VM, specifying a single NIC connected to "net1".
- Nova contacts Quantum and creates a port1 on net1. port1 is assigned IP (e.g., 10.0.0.2).
- tenant destroys VM.
- Nova contacts Quantum and destroys port1. IP (e.g., 10.0.0.2) is returned to pool.
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.
Entities
Network
Note: current code uses underscores, but may change to dashes.
| attribute | Type | Required | CRUD | Default | Explanation/Notes |
| id | uuid-str | - | R | - | UUID representing the network |
| name | str | Y | CRU | - | |
| admin_state_up | bool | N | CRU | True | |
| op_status | str | - | R | - | |
| tenant_id | str (uuid?) | N | CR (?) | keystone-tenant | owner of network. only admin user can specify a tenant_id other than its own. |
| subnets | list(uuid) | N | CRUD | [] | subnets associated with this network. Plan to allow fully specified subnets as part of network create |
