Merge pull request #381 from asadoughi/shared_ips_docs
Shared IPs API RAML specs
This commit is contained in:
Jason Meridth
195
docs/shared_ips.raml
Normal file
195
docs/shared_ips.raml
Normal file
@@ -0,0 +1,195 @@
|
||||
#%RAML 0.8
|
||||
title: Neutron Shared IPs API
|
||||
version: v2.0
|
||||
baseUri: https://{neutronUri}/{version}/
|
||||
mediaType: application/json
|
||||
traits:
|
||||
- secured:
|
||||
headers:
|
||||
X-Auth-Token:
|
||||
description: Token for request's tenant
|
||||
required: true
|
||||
type: string
|
||||
/ip_addresses:
|
||||
displayName: Neutron IP Addresses
|
||||
description: A collection of IP addresses
|
||||
is: [ secured ]
|
||||
get:
|
||||
description: List all IPs for a given tenant
|
||||
queryParameters: # This is not a complete list of query parameters, just the ones relevant to Shared IP.
|
||||
device_id:
|
||||
description: filters IP addresses by their ports' device_id
|
||||
type: string
|
||||
service:
|
||||
description: filters IP addresses by their service
|
||||
type: string
|
||||
responses:
|
||||
200:
|
||||
description: ok
|
||||
body:
|
||||
application/json:
|
||||
example: |
|
||||
{"ip_addresses": [{
|
||||
"id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
|
||||
"network_id": "6870304a-7212-443f-bd0c-089c886b44df",
|
||||
"address": "192.168.10.1",
|
||||
"port_ids": ['2f693cca-7383-45da-8bae-d26b6c2d6718'],
|
||||
"subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
|
||||
"used_by_tenant_id": "2345678",
|
||||
"version": "4",
|
||||
"address_type": "fixed"}]}
|
||||
post:
|
||||
description: |
|
||||
Neutron creates an IP address on a specified network (network_id) with a specified IP version (version).
|
||||
A list of device_ids may be optionally specified to create the IP address and added to their respective ports.
|
||||
A list of port_ids may be optionally specified to create the IP address and added to the specified ports.
|
||||
At least one of device_ids or port_ids must be specified.
|
||||
Defaults all ports' service to "none".
|
||||
body:
|
||||
application/json:
|
||||
example: |
|
||||
{
|
||||
"ip_address": {
|
||||
"network_id": "fda61e0b-a410-49e8-ad3a-64c595618c7e",
|
||||
"version": 4,
|
||||
"port_ids": ["6200d533-a42b-4c04-82a1-cc14dbdbf2de"]}
|
||||
}
|
||||
responses:
|
||||
201:
|
||||
description: created
|
||||
body:
|
||||
application/json:
|
||||
example: |
|
||||
{
|
||||
"ip_address": {
|
||||
"id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
|
||||
"network_id": "fda61e0b-a410-49e8-ad3a-64c595618c7e",
|
||||
"address": "192.168.10.1",
|
||||
"port_ids": ["6200d533-a42b-4c04-82a1-cc14dbdbf2de"],
|
||||
"subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
|
||||
"used_by_tenant_id": "2345678",
|
||||
"version": "4",
|
||||
"address_type": "fixed"}
|
||||
}
|
||||
400:
|
||||
description: |
|
||||
bad input
|
||||
* IP version not 4 nor 6
|
||||
* Ambiguous ports: multiple ports associated with a single device_id (devices with multiple ports must use the port_ids field)
|
||||
401:
|
||||
description: |
|
||||
unauthorized
|
||||
* Cannot create IP address on other tenant's network (can create IP address on provider network)
|
||||
404:
|
||||
description: |
|
||||
Not found
|
||||
* Network not found.
|
||||
* Subnet with desired IP version not found.
|
||||
* Ports not found.
|
||||
/{ipAddressId}:
|
||||
description: A specific IP address, a member of the IP addresses collection
|
||||
get:
|
||||
description: shows a specific IP address
|
||||
responses:
|
||||
200:
|
||||
description: ok
|
||||
body:
|
||||
application/json:
|
||||
example: |
|
||||
{"ip_address": {
|
||||
"id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
|
||||
"network_id": "6870304a-7212-443f-bd0c-089c886b44df",
|
||||
"address": "192.168.10.1",
|
||||
"port_ids": ['2f693cca-7383-45da-8bae-d26b6c2d6718'],
|
||||
"subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
|
||||
"used_by_tenant_id": "2345678",
|
||||
"version": "4",
|
||||
"address_type": "fixed"}
|
||||
404:
|
||||
description: not found, e.g. another tenant's IP address
|
||||
put:
|
||||
description: |
|
||||
update an IP address, e.g. to change ports. This will eliminate any previous associations to ports.
|
||||
body:
|
||||
application/json:
|
||||
example: |
|
||||
{"ip_address": {
|
||||
"port_ids": ['275b0516-206f-4421-8e42-1d3d1e4e9fb2', '66811c0a-fdbd-49d4-b1dd-f0f15a329744']}
|
||||
responses:
|
||||
200:
|
||||
description: updated
|
||||
404:
|
||||
description: |
|
||||
not found
|
||||
* attempting to update another tenant's IP address
|
||||
* ports not found
|
||||
delete:
|
||||
description: delete an IP address
|
||||
responses:
|
||||
204:
|
||||
description: deleted
|
||||
400:
|
||||
description: |
|
||||
bad request
|
||||
* attempting to delete an IP with a `service != "none"` port (tenant should disassociate on nova-side first)
|
||||
* attempting to delete a provider network's IP address
|
||||
404:
|
||||
description: |
|
||||
not found
|
||||
* attempting to delete another tenant's IP address
|
||||
/ports/:
|
||||
description: |
|
||||
Collection of ports for a given IP address.
|
||||
This URI will be hidden to tenants.
|
||||
get:
|
||||
description: |
|
||||
List the ports associated with an IP address
|
||||
queryParameters:
|
||||
device_id:
|
||||
description: filter ports for a specific ip_address_id by their device_id
|
||||
type: string
|
||||
responses:
|
||||
200:
|
||||
description: ok
|
||||
body:
|
||||
application/json:
|
||||
example: |
|
||||
{"ports": [{"id": "dce3dca6-2cba-4e00-95e9-748587f94620", "service": "compute"}]}
|
||||
404:
|
||||
description: not found
|
||||
post:
|
||||
responses:
|
||||
501:
|
||||
description: not implemented
|
||||
/{portId}:
|
||||
get:
|
||||
description: Shows a specific IP address service
|
||||
body:
|
||||
application/json:
|
||||
example: |
|
||||
{"port": {"id": "dce3dca6-2cba-4e00-95e9-748587f94620", "service": "compute"}}
|
||||
put:
|
||||
description: |
|
||||
Internal call from nova to neutron to update an IP address's service to either "none" or "compute"
|
||||
body:
|
||||
application/json:
|
||||
example: |
|
||||
{"port": {"service": "compute"}}
|
||||
responses:
|
||||
200:
|
||||
description: updated
|
||||
400:
|
||||
description: |
|
||||
bad input
|
||||
* where another port for this given IP is active
|
||||
* service string too long (max 256, for example)
|
||||
401:
|
||||
description: |
|
||||
unauthorized, e.g. only nova can make this PUT
|
||||
404:
|
||||
description: |
|
||||
not found, e.g.where this port_id=portId does not exist or belongs to other tenant
|
||||
delete:
|
||||
responses:
|
||||
501:
|
||||
description: not implemented
|
||||
91
docs/shared_ips_nova.raml
Normal file
91
docs/shared_ips_nova.raml
Normal file
@@ -0,0 +1,91 @@
|
||||
#%RAML 0.8
|
||||
title: Nova extensions for Neutron Shared IPs API
|
||||
version: v2.0
|
||||
baseUri: https://{novaUri}/{version}/
|
||||
mediaType: application/json
|
||||
traits:
|
||||
- secured:
|
||||
headers:
|
||||
X-Auth-Token:
|
||||
description: Token for request's tenant
|
||||
required: true
|
||||
type: string
|
||||
/servers/{serverId}/ip_associations:
|
||||
displayName: Nova IP Associations
|
||||
description: A collection of IP associations
|
||||
is: [ secured ]
|
||||
get:
|
||||
description: |
|
||||
List all IPs associated to this instance
|
||||
Invokes and parses (with tenant_id as header): GET http://{neutronUri}/{neutronVersion}/ip_addresses?device_id={serverId}&service=compute
|
||||
responses:
|
||||
200:
|
||||
description: ok
|
||||
body:
|
||||
application/json:
|
||||
example: |
|
||||
{"ip_associations": [{"id": "1", "address": "10.1.1.1"}, {"id": "2", "address": "10.1.1.2"}]}
|
||||
404:
|
||||
description: server not found
|
||||
/{ipAddressId}:
|
||||
description: |
|
||||
A specific IP association, a member of the IP association collection
|
||||
This id is the same as neutron's ip_address's id
|
||||
get:
|
||||
description: |
|
||||
Shows an IP association
|
||||
Invokes and parses (with tenant_id as header):
|
||||
* GET http://{neutronUri}/{neutronVersion}/ip_addresses/{ipAddressId}
|
||||
responses:
|
||||
200:
|
||||
description: ok
|
||||
body:
|
||||
application/json:
|
||||
example: |
|
||||
{"ip_association": {"id": "1", "address": "10.1.1.1"}}
|
||||
404:
|
||||
description: IP association not found
|
||||
put:
|
||||
description: |
|
||||
Create IP address association (idempotent PUT)
|
||||
Invokes and parses:
|
||||
* GET http://{neutronUri}/{neutronVersion}/ip_addresses/{ipAddressId}/ports?device_id={serverId} (with tenant_id as header)
|
||||
* PUT http://{neutronUri}/{neutronVersion}/ip_addresses/{ipAddressId}/ports/{portId} with {"service": "compute"}
|
||||
body:
|
||||
application/json:
|
||||
example: |
|
||||
{"ip_association": {}}
|
||||
responses:
|
||||
201:
|
||||
description: created
|
||||
400:
|
||||
description: |
|
||||
Bad input
|
||||
* ip_address_id association already exists
|
||||
* ambiguous request: more than one port is related to device_id/ip_address_id
|
||||
404:
|
||||
description: |
|
||||
not found
|
||||
* server not found
|
||||
* ip_address_id is not found, e.g. neutron call returns 404
|
||||
500:
|
||||
description: |
|
||||
something went horribly wrong, e.g. neutron call returns 5xx
|
||||
delete:
|
||||
description: |
|
||||
Delete IP address association
|
||||
Invokes and parses:
|
||||
* GET http://{neutronUri}/{neutronVersion}/ip_addresses/{ipAddressId}/ports?device_id={serverId} (with tenant_id as header)
|
||||
* PUT http://{neutronUri}/{neutronVersion}/ip_addresses/{ipAddressId}/ports/{portId} with {"service": "none"}
|
||||
responses:
|
||||
204:
|
||||
description: successfully deleted
|
||||
404:
|
||||
description: |
|
||||
not found
|
||||
* server not found
|
||||
* ip_address_id is not found, e.g. neutron call returns 404
|
||||
post:
|
||||
responses:
|
||||
501:
|
||||
description: not implemented
|
||||
Reference in New Issue
Block a user