diff --git a/docs/shared_ips.raml b/docs/shared_ips.raml new file mode 100644 index 0000000..4bee956 --- /dev/null +++ b/docs/shared_ips.raml @@ -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 diff --git a/docs/shared_ips_nova.raml b/docs/shared_ips_nova.raml new file mode 100644 index 0000000..eb69cac --- /dev/null +++ b/docs/shared_ips_nova.raml @@ -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