openstack/api-site
Code Issues Proposed changes

Add GET /v2.1/tenant_id/os-floating-ips/id method

Browse Source 
this method is enabled by nova api but not in the doc
so add it.

(df) Update the floating IP samples
(df) Clarify the other floating IP methods
(df) Make language for server actions, including floating IP actions,
consistent

Change-Id: I3b97964bb999063f97a17e26a3d755bef133ef32
Partial-Bug: #1515222
This commit is contained in:
jichenjc 2015-11-22 12:32:11 +08:00 committed by Diane Fleming
parent 4b10246f39
commit 5bd81e6008
16 changed files with 300 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
api-ref/src/docbkx/ch_compute-v2.1.xml
View File

@ -239,6 +239,7 @@
<wadl:method href="#addFixedIp"/>
</wadl:resource>
<wadl:resource href="../wadls/compute-api/src/v2.1/wadl/os-server-actions-v2.1.wadl#action">
<wadl:method href="#addFloatingIp"/>
<wadl:method href="#attach"/>
<wadl:method href="#confirmResize"/>
<wadl:method href="#createImage"/>
@ -266,6 +267,7 @@
<wadl:method href="#removeFixedIp"/>
</wadl:resource>
<wadl:resource href="../wadls/compute-api/src/v2.1/wadl/os-server-actions-v2.1.wadl#action">
<wadl:method href="removeFloatingIp"/>
<wadl:method href="#rescue"/>
<wadl:method href="#resize"/>
</wadl:resource>
@ -624,9 +626,40 @@
<section xml:id="os-floating-ips-v2.1">
<title>Floating IPs (os-floating-ips)</title>
<para>
Assigns and allocates floating IP addresses to instances
that run in an OpenStack cloud.
Lists floating IP addresses that are associated with a project. Also,
creates (allocates) a floating IP address for a project, shows
floating IP address details, and deletes (deallocates) a floating IP
address from a project.
</para>
<para>
A pool of floating IP addresses, configured by the cloud
administrator, is available in OpenStack Compute. The project quota
defines the maximum number of floating IP addresses that you can
allocate to the project. After you <link
xlink:href="http://developer.openstack.org/api-ref-compute-v2.1.html#createFloatingIP">allocate a floating IP address</link>
for a project, you can:
</para>
<itemizedlist>
<listitem>
<para>
<link xlink:href="http://developer.openstack.org/api-ref-compute-v2.1.html#addFloatingIp">Add (associate) the floating
IP address</link> with an instance in the project. Only one
floating IP address can be associated with an instance at a time.
</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://developer.openstack.org/api-ref-compute-v2.1.html#removeFloatingIp">Remove (disassociate) the
floating IP address</link> from an instance in the project.
</para>
</listitem>
<listitem>
<para>
Delete, or deallocate, a floating IP from the project, which
automatically deletes any associations for that IP address.
</para>
</listitem>
</itemizedlist>
<wadl:resources
href="../wadls/compute-api/src/v2.1/wadl/os-floating-ips-v2.1.wadl"
xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
@ -635,7 +668,8 @@
<title>Floating IPs bulk (os-floating-ips-bulk)</title>
<para>
Bulk-creates, deletes, and lists floating IPs. Default pool name is
<code>nova</code>. To view available pools, use the <code>os-floating-ip-pools</code> extension.
<code>nova</code>. To view available pools, use the <code>os-
floating-ip-pools</code> extension.
</para>
<wadl:resources
href="../wadls/compute-api/src/v2.1/wadl/os-floating-ips-bulk-v2.1.wadl"

9
api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-floating-ips/floating-ip-get-resp.json Normal file
View File

@ -0,0 +1,9 @@
{
"floating_ip": {
"instance_id": null,
"ip": "172.24.4.3",
"fixed_ip": null,
"id": "b310fff3-c467-4950-9b00-038afebd151c",
"pool": "public"
}
}

2
api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-floating-ips/floating-ips-create-req.json
View File

@ -1,3 +1,3 @@
{
"pool": "nova"
"pool": "public"
}

8
api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-floating-ips/floating-ips-create-resp.json
View File

@ -1,9 +1,9 @@
{
"floating_ip": {
"fixed_ip": null,
"id": 1,
"instance_id": null,
"ip": "10.10.10.1",
"pool": "nova"
"ip": "172.24.4.4",
"fixed_ip": null,
"id": "c9c04158-3ed4-449c-953a-aa21fb47cde7",
"pool": "public"
}
}

9
api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-floating-ips/floating-ips-get-resp.json
View File

@ -1,9 +0,0 @@
{
"floating_ip": {
"fixed_ip": null,
"id": 1,
"instance_id": null,
"ip": "10.10.10.1",
"pool": "nova"
}
}

3
api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-floating-ips/floating-ips-list-empty-resp.json
View File

@ -1,3 +0,0 @@
{
"floating_ips": []
}

16
api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-floating-ips/floating-ips-list-resp.json
View File

@ -1,18 +1,18 @@
{
"floating_ips": [
{
"fixed_ip": null,
"id": 1,
"instance_id": null,
"ip": "10.10.10.1",
"pool": "nova"
"ip": "172.24.4.3",
"fixed_ip": null,
"id": "b310fff3-c467-4950-9b00-038afebd151c",
"pool": "public"
},
{
"fixed_ip": null,
"id": 2,
"instance_id": null,
"ip": "10.10.10.2",
"pool": "nova"
"ip": "172.24.4.4",
"fixed_ip": null,
"id": "c9c04158-3ed4-449c-953a-aa21fb47cde7",
"pool": "public"
}
]
}

5
api-ref/src/wadls/compute-api/src/v2.1/api_samples/servers/server-action-addFloatingIp-req.json Normal file
View File

@ -0,0 +1,5 @@
{
"addFloatingIp": {
"address": "172.24.4.4"
}
}

5
api-ref/src/wadls/compute-api/src/v2.1/api_samples/servers/server-action-removeFloatingIp-req.json Normal file
View File

@ -0,0 +1,5 @@
{
"removeFloatingIp": {
"address": "172.24.4.4"
}
}

28
api-ref/src/wadls/compute-api/src/v2.1/common.ent
View File

@ -518,6 +518,18 @@
</para>
</wadl:doc>
</param>'>
<!ENTITY addFloatingIpActionRequestParameter '
<param xmlns="http://wadl.dev.java.net/2009/02"
name="addFloatingIp" style="plain" required="true"
type="xsd:string">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xmlns:wadl="http://wadl.dev.java.net/2009/02"
xml:lang="EN">
<para>
The action.
</para>
</wadl:doc>
</param>'>
<!ENTITY attachActionRequestParameter '
<param xmlns="http://wadl.dev.java.net/2009/02"
name="attach" style="plain" required="true"
@ -693,6 +705,18 @@
</para>
</wadl:doc>
</param>'>
<!ENTITY removeFloatingIpActionRequestParameter '
<param xmlns="http://wadl.dev.java.net/2009/02"
name="removeFloatingIp" style="plain" required="true"
type="xsd:string">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xmlns:wadl="http://wadl.dev.java.net/2009/02"
xml:lang="EN">
<para>
The action.
</para>
</wadl:doc>
</param>'>
<!ENTITY os-migrateLiveActionRequestParameter '
<param xmlns="http://wadl.dev.java.net/2009/02"
name="host" style="plain" required="true"
@ -1628,8 +1652,8 @@
<para>The IP address.</para>
</wadl:doc>
</param>'>
<!ENTITY floatingIpIdRequestParameter '
<param name="id" style="template" type="csapi:UUID"
<!ENTITY floating-ip-idRequestParameter '
<param name="floating_ip_id" style="template" type="csapi:UUID"
xmlns="http://wadl.dev.java.net/2009/02">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN"

2
api-ref/src/wadls/compute-api/src/v2.1/wadl/os-console-output-v2.1.wadl
View File

@ -29,7 +29,7 @@
</resources>
<method name="POST" id="getConsoleOutput">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
title="Get console output for a server (os-getConsoleOutput action)">
title="Get console output (os-getConsoleOutput action)">
<para role="shortdesc">
Gets console output for a server instance.
</para>

4
api-ref/src/wadls/compute-api/src/v2.1/wadl/os-consoles-v2.1.wadl
View File

@ -39,7 +39,7 @@
<!---methods -->
<method name="POST" id="createConsole">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
title="Create console for server">
title="Create console">
<para role="shortdesc">
Creates a console for a server instance.
</para>
@ -52,7 +52,7 @@
</method>
<method name="GET" id="listConsoles">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
title="Lists consoles for server">
title="Lists consoles">
<para role="shortdesc">
Lists all consoles for a server instance.
</para>

124
api-ref/src/wadls/compute-api/src/v2.1/wadl/os-floating-ips-v2.1.wadl
View File

@ -17,27 +17,29 @@
<resource id="tenant_id" path="{tenant_id}">
&tenantIdRequestParameter;
<resource id="os-floating-ips" path="os-floating-ips">
<method href="#ListFloatingIPs"/>
<method href="#AllocateFloatingIP"/>
<resource path="{id}">
&floatingIpIdRequestParameter;
<method href="#DeallocateFloatingIP"/>
<method href="#listFloatingIPs"/>
<method href="#createFloatingIP"/>
<resource id="floating-ip-id" path="{floating-ip-id}">
&floating-ip-idRequestParameter;
<method href="#showFloatingIP"/>
<method href="#deleteFloatingIP"/>
</resource>
</resource>
</resource>
</resource>
</resources>
<method name="GET" id="ListFloatingIPs">
<method name="GET" id="listFloatingIPs">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
title="List floating IPs">
<para role="shortdesc">Lists floating IP addresses
associated with the tenant or account.
title="List floating IP addresses">
<para role="shortdesc">
Lists floating IP addresses associated with the tenant or
account.
</para>
<para>
Policy defaults enable only users with the administrative role
or the owner of the server to perform this operation. Cloud
providers can change these permissions through the
<code>policy.json</code> file.
Policy defaults enable only users with the administrative role
or the owner of the server to perform this operation. Cloud
providers can change these permissions through the
<code>policy.json</code> file.
</para>
</wadl:doc>
<response status="200">
@ -51,15 +53,24 @@
</representation>
</response>
</method>
<method name="POST" id="AllocateFloatingIP">
<method name="POST" id="createFloatingIP">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
title="Allocate floating IP">
<para role="shortdesc">Allocates a new floating IP address
to a tenant or account.</para>
title="Create (allocate) floating IP address">
<para role="shortdesc">
Creates, or allocates, a floating IP address for the current
project. By default, the floating IP address is allocated from
the public pool.
</para>
<para>
Policy defaults enable only users with the administrative role
or the owner of the server to perform this operation. Cloud providers can change
these permissions through the <code>policy.json</code> file.
If more than one floating IP address pool is available, use
the <code>pool</code> parameter to specify from which pool to
allocate the IP address.
</para>
<para>
Policy defaults enable only users with the administrative role
or the owner of the server to perform this operation. Cloud
providers can change these permissions through the
<code>policy.json</code> file.
</para>
</wadl:doc>
<request>
@ -67,20 +78,26 @@
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN">
<xsdxt:code
href="../api_samples/os-floating-ips/floating-ips-create-req.json"
/>
href="../api_samples/os-floating-ips/floating-ips-create-req.json"/>
</wadl:doc>
<param name="pool" style="plain">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN">
<para>
Pool from which to allocate IP address. If you
omit this parameter, default pool is used.
Pool from which to allocate the IP address. If you
omit this parameter, the call allocates the
floating IP address from the public pool.
</para>
<para>
Policy defaults enable only users with the administrative role
or the owner of the server to perform this operation. Cloud providers can change
these permissions through the <code>policy.json</code> file.
If no floating IP addresses are available, the
call returns the <code>400</code> response code
with an informational message.
</para>
<para>
Policy defaults enable only users with the administrative role
or the owner of the server to perform this operation. Cloud
providers can change these permissions through the
<code>policy.json</code> file.
</para>
</wadl:doc>
</param>
@ -96,29 +113,50 @@
</wadl:doc>
</representation>
</response>
<response status="400">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN"><p xmlns="http://www.w3.org/1999/xhtml"
>If there are no floating IPs available, the
extension returns an error code 400 with a message
indicating that no more floating IPs are
available.</p></wadl:doc>
<response status="400"/>
</method>
<method name="GET" id="showFloatingIP">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
title="Show floating IP address details">
<para role="shortdesc">
Shows details for a floating IP address, by ID, that is
associated with the tenant or account.
</para>
<para>
Policy defaults enable only users with the administrative role
or the owner of the server to perform this operation. Cloud
providers can change these permissions through the
<code>policy.json</code> file.
</para>
</wadl:doc>
<response status="200">
<representation mediaType="application/json">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN">
<xsdxt:code
href="../api_samples/os-floating-ips/floating-ip-get-resp.json"
/>
</wadl:doc>
</representation>
</response>
</method>
<method name="DELETE" id="DeallocateFloatingIP">
<method name="DELETE" id="deleteFloatingIP">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
title="Deallocate floating IP">
<para role="shortdesc">Deallocates a floating IP address.
title="Delete (deallocate) floating IP address">
<para role="shortdesc">
Deletes, or deallocates, a floating IP address from the
current project and returns it to the pool from which it was
allocated.
</para>
<para>
You can use this call to deallocate and delete only manually-allocated
floating IP addresses. You must manually deallocate
auto-allocated floating IP addresses before you can delete them.
If the IP address is still associated with a running instance,
it is automatically disassociated from that instance.
</para>
<para>
Policy defaults enable only users with the administrative role
or the owner of the server to perform this operation. Cloud providers can change
these permissions through the <code>policy.json</code> file.
Policy defaults enable only users with the administrative role
or the owner of the server to perform this operation. Cloud
providers can change these permissions through the
<code>policy.json</code> file.
</para>
</wadl:doc>
<response status="202"/>

10
api-ref/src/wadls/compute-api/src/v2.1/wadl/os-multinic-v2.1.wadl
View File

@ -32,10 +32,12 @@
<!-- OS Multinic -->
<!--*******************************************************-->
<method name="POST" id="addFixedIp">
<wadl:doc xml:lang="EN" title="Add fixed IP to server (addFixedIp action)"
<wadl:doc xml:lang="EN" title="Add (associate) fixed IP (addFixedIp action)"
xmlns="http://docbook.org/ns/docbook">
<para role="shortdesc">
Adds a fixed IP address to a network on a server instance.
Adds a fixed IP address to a server instance, which associates
that address with the server. The fixed IP address is
retrieved from the network that you specify in the request.
</para>
<para>
Specify the <code>addFixedIp</code> action and the network ID
@ -60,10 +62,10 @@
<response status="202"/>
</method>
<method name="POST" id="removeFixedIp">
<wadl:doc xml:lang="EN" title="Remove fixed IP from server (removeFixedIp action)"
<wadl:doc xml:lang="EN" title="Remove (disassociate) fixed IP (removeFixedIp action)"
xmlns="http://docbook.org/ns/docbook">
<para role="shortdesc">
Removes a fixed IP address from a server.
Removes, or disassociates, a fixed IP address from a server.
</para>
<para>
Specify the <code>removeFixedIp</code> action in the request body.

8
api-ref/src/wadls/compute-api/src/v2.1/wadl/os-remote-consoles-v2.1.wadl
View File

@ -36,7 +36,7 @@
<!-- OS Remote consoles -->
<!--*******************************************************-->
<method name="POST" id="getRDPConsole">
<wadl:doc xml:lang="EN" title="Get RDP console for a server (os-getRDPConsole action)"
<wadl:doc xml:lang="EN" title="Get RDP console (os-getRDPConsole action)"
xmlns="http://docbook.org/ns/docbook">
<para role="shortdesc">
Gets a <link
@ -67,7 +67,7 @@
</response>
</method>
<method name="POST" id="getSerialConsole">
<wadl:doc xml:lang="EN" title="Get serial console for a server (os-getSerialConsole action)"
<wadl:doc xml:lang="EN" title="Get serial console (os-getSerialConsole action)"
xmlns="http://docbook.org/ns/docbook">
<para role="shortdesc">
Gets a serial console for a server.
@ -97,7 +97,7 @@
</method>
<method name="POST" id="getSPICEConsole">
<wadl:doc xml:lang="EN"
title="Get SPICE console for a server (os-getSPICEConsole action)"
title="Get SPICE console (os-getSPICEConsole action)"
xmlns="http://docbook.org/ns/docbook">
<para role="shortdesc">
Gets a SPICE console for a server.
@ -127,7 +127,7 @@
</response>
</method>
<method name="POST" id="getVNCConsole">
<wadl:doc xml:lang="EN" title="Get VNC console for a server (os-getVNCConsole action)"
<wadl:doc xml:lang="EN" title="Get VNC console (os-getVNCConsole action)"
xmlns="http://docbook.org/ns/docbook">
<para role="shortdesc">
Gets a VNC console for a server.

113
api-ref/src/wadls/compute-api/src/v2.1/wadl/os-server-actions-v2.1.wadl
View File

@ -21,6 +21,7 @@
<resource id="server_id" path="{server_id}">
&serverIdRequestParameter;
<resource id="action" path="action">
<method href="#addFloatingIp"/>
<method href="#attach"/>
<method href="#confirmResize"/>
<method href="#createImage"/>
@ -28,6 +29,7 @@
<method href="#stop"/>
<method href="#reboot"/>
<method href="#rebuild"/>
<method href="#removeFloatingIp"/>
<method href="#rescue"/>
<method href="#resize"/>
<method href="#revertResize"/>
@ -41,6 +43,71 @@
<!-- *******************************************************-->
<!-- Server Actions -->
<!--********************************************************-->
<method name="POST" id="addFloatingIp">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN" title="Add (associate) floating IP (addFloatingIp action)">
<para role="shortdesc">
Adds a floating IP address to a server, which associates that
address with the server.
</para>
<para>
A pool of floating IP addresses, configured by the cloud
administrator, is available in OpenStack Compute. The project
quota defines the maximum number of floating IP addresses that
you can allocate to the project. After you <link
xlink:href="#createFloatingIP">create (allocate) a floating IP
address</link> for a project, you can associate that address
with the server. Specify the <code>addFloatingIp</code> action
in the request body.
</para>
<para>
If an instance is connected to multiple networks, you can
associate a floating IP address with a specific fixed IP
address by using the optional <code>fixed_address</code>
parameter.
</para>
<para>Preconditions</para>
<itemizedlist>
<listitem><para>The server must exist.</para></listitem>
<listitem><para>You can only add a floating IP address to the server
when its status is <code>available</code>.</para></listitem>
</itemizedlist>
</wadl:doc>
<request>
<representation mediaType="application/json">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<xsdxt:code href="../api_samples/servers/server-action-addFloatingIp-req.json"/>
</wadl:doc>
&addFloatingIpActionRequestParameter;
<param xmlns="http://wadl.dev.java.net/2009/02"
name="address" style="plain" type="xsd:string"
required="true">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xmlns:wadl="http://wadl.dev.java.net/2009/02"
xml:lang="EN"><para>The floating IP address.</para>
</wadl:doc>
</param>
<param xmlns="http://wadl.dev.java.net/2009/02"
name="fixed_address" style="plain" type="xsd:string"
required="false">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xmlns:wadl="http://wadl.dev.java.net/2009/02"
xml:lang="EN">
<para>
The fixed IP address with which you want to
associate the floating IP address.
</para>
</wadl:doc>
</param>
</representation>
</request>
<response status="202"/>
<response status="409">
<representation mediaType="application/json"/>
</response>
&commonFaults;
&getFaults; &postPutFaults; &buildFaults; &inProgressFault;
</method>
<method name="POST" id="attach">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN" title="Attach volume (attach action)">
<para role="shortdesc">
@ -120,7 +187,7 @@
&commonFaults;
&getFaults; &postPutFaults; &buildFaults; &inProgressFault;
</method>
<method name="POST" id="confirmResize">
<method name="POST" id="confirmResize">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
title="Confirm resized server (confirmResize action)">
<para role="shortdesc">
@ -381,7 +448,49 @@
</representation>
</response>
&commonFaults;
&getFaults; &postPutFaults; &buildFaults; &inProgressFault; </method>
&getFaults; &postPutFaults; &buildFaults; &inProgressFault;
</method>
<method name="POST" id="removeFloatingIp">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN" title="Remove (disassociate) floating IP (removeFloatingIp action)">
<para role="shortdesc">
Removes, or disassociates, a floating IP address from a server.
</para>
<para>
The IP address is returned to the pool of IP addresses that is
available for all projects. When you remove a floating IP
address and that IP address is still associated with a running
instance, it is automatically disassociated from that
instance.
</para>
<para>
Specify the <code>removeFloatingIp</code> action in the request
body.
</para>
</wadl:doc>
<request>
<representation mediaType="application/json">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<xsdxt:code href="../api_samples/servers/server-action-removeFloatingIp-req.json"/>
</wadl:doc>
&removeFloatingIpActionRequestParameter;
<param xmlns="http://wadl.dev.java.net/2009/02"
name="address" style="plain" type="xsd:string"
required="true">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xmlns:wadl="http://wadl.dev.java.net/2009/02"
xml:lang="EN"><para>The floating IP address.</para>
</wadl:doc>
</param>
</representation>
</request>
<response status="202"/>
<response status="409">
<representation mediaType="application/json"/>
</response>
&commonFaults;
&getFaults; &postPutFaults; &buildFaults; &inProgressFault;
</method>
<method name="POST" id="rescue">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
title="Rescue server (rescue action)">