1397c31240
Closes-Bug: #1283712 Change-Id: Iea9a63251b7702a33fcdb54c71bfc638774d0418 author: diane fleming
991 lines
45 KiB
XML
991 lines
45 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book[
|
|
<!-- Some useful entities borrowed from HTML -->
|
|
<!ENTITY ndash "–">
|
|
<!ENTITY mdash "—">
|
|
<!ENTITY hellip "…">
|
|
<!ENTITY plusmn "±">
|
|
|
|
<!-- Useful for describing APIs -->
|
|
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
|
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
|
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
|
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
|
|
|
|
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
|
<imageobject>
|
|
<imagedata fileref="figures/Check_mark_23x20_02.svg"
|
|
format="SVG" scale="60"/>
|
|
</imageobject>
|
|
</inlinemediaobject>'>
|
|
|
|
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
|
<imageobject>
|
|
<imagedata fileref="figures/Arrow_east.svg"
|
|
format="SVG" scale="60"/>
|
|
</imageobject>
|
|
</inlinemediaobject>'>
|
|
<!ENTITY APIv2 'Networking API v2.0'>
|
|
]>
|
|
<section xml:id="router_ext" xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
|
|
<title>Layer-3 Networking Extension
|
|
(<literal>router</literal>)</title>
|
|
<para>The Layer-3 networking extension enables OpenStack
|
|
Networking API users to route packets between subnets, forward
|
|
packets from internal networks to external ones, and access
|
|
instances from external networks through <emphasis
|
|
role="italic"> Floating IPs</emphasis>.</para>
|
|
<para>This extension introduces the following resources: <itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">router</emphasis>, a
|
|
logical entity for forwarding packets across
|
|
internal subnets and NATting them on external
|
|
networks through an appropriate external
|
|
gateway.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">floatingip</emphasis>,
|
|
representing an external IP address mapped to a
|
|
OpenStack Networking port attached to an internal
|
|
network.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<section xml:id="router_ext_concepts">
|
|
<title>Concepts</title>
|
|
<para>The OpenStack Networking layer-3 extension is a resource
|
|
extension. It defines two new resources: <emphasis
|
|
role="bold">router</emphasis> and <emphasis
|
|
role="bold">floatingip</emphasis>.</para>
|
|
<para>A <emphasis role="bold">router </emphasis> is used to
|
|
interconnect subnets and forward traffic among them.
|
|
Another feature of the router is to NAT internal traffic
|
|
to external networks.</para>
|
|
<para>A router has an interface for each subnet it is
|
|
associated with. By default the IP address of such
|
|
interface is the subnet's gateway IP. Also, whenever a
|
|
router is associated with a subnet, a port for that router
|
|
interface will be added to the subnet's network.</para>
|
|
<para>A <emphasis role="bold">floating IP </emphasis> is an IP
|
|
address on an external network, which is associated with a
|
|
specific port, and optionally a specific IP address, on a
|
|
private OpenStack Networking network. Therefore a floating
|
|
IP allows access to an instance on a private network from
|
|
an external network. Floating IPs can only be defined on
|
|
networks for which the attribute <emphasis role="italic">
|
|
router:external</emphasis> (by the external network
|
|
extension) has been set to True.</para>
|
|
<?hard-pagebreak?>
|
|
<table rules="all">
|
|
<caption>Router Attributes</caption>
|
|
<col width="20%"/>
|
|
<col width="8%"/>
|
|
<col width="10%"/>
|
|
<col width="7%"/>
|
|
<col width="15%"/>
|
|
<col width="15%"/>
|
|
<col width="25%"/>
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Type</th>
|
|
<th>Required</th>
|
|
<th>CRUD<footnote xml:id="crud1">
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold"
|
|
>C</emphasis>. Use the attribute in
|
|
create operations.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold"
|
|
>R</emphasis>. This attribute is
|
|
returned in response to show and
|
|
list operations.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold"
|
|
>U</emphasis>. You can update the
|
|
value of this attribute.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold"
|
|
>D</emphasis>. You can delete the
|
|
value of this attribute.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</footnote></th>
|
|
<th>Default Value</th>
|
|
<th>Validation Constraints</th>
|
|
<th>Notes</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>id</td>
|
|
<td>uuid-str</td>
|
|
<td>N/A</td>
|
|
<td>R</td>
|
|
<td>generated</td>
|
|
<td>N/A</td>
|
|
<td>Unique identifier for the router.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>name</td>
|
|
<td>String</td>
|
|
<td>No</td>
|
|
<td>CRU</td>
|
|
<td>None</td>
|
|
<td>N/A</td>
|
|
<td>Human readable name for the router. Does not
|
|
have to be unique</td>
|
|
</tr>
|
|
<tr>
|
|
<td>admin_state_up</td>
|
|
<td>Bool</td>
|
|
<td>No</td>
|
|
<td>CRU</td>
|
|
<td>true</td>
|
|
<td>{true | false }</td>
|
|
<td>Administrative state of the router</td>
|
|
</tr>
|
|
<tr>
|
|
<td>status</td>
|
|
<td>String</td>
|
|
<td>N/A</td>
|
|
<td>R</td>
|
|
<td>N/A</td>
|
|
<td>N/A</td>
|
|
<td>Indicates whether a router is currently
|
|
operational or not</td>
|
|
</tr>
|
|
<tr>
|
|
<td>tenant_id</td>
|
|
<td>uuid-str</td>
|
|
<td>No</td>
|
|
<td>CR</td>
|
|
<td>Derived from Authentication token</td>
|
|
<td>N/A</td>
|
|
<td>Owner of the router. Only admin users can
|
|
specify a tenant identifier other than its own
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>external_gateway_info</td>
|
|
<td>dict</td>
|
|
<td>No</td>
|
|
<td>CRU</td>
|
|
<td>None</td>
|
|
<td>No constraint</td>
|
|
<td>Information on external gateway for the
|
|
router</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<table rules="all">
|
|
<caption>Floating IP Attributes</caption>
|
|
<col width="20%"/>
|
|
<col width="8%"/>
|
|
<col width="10%"/>
|
|
<col width="7%"/>
|
|
<col width="15%"/>
|
|
<col width="15%"/>
|
|
<col width="25%"/>
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Type</th>
|
|
<th>Required</th>
|
|
<th>CRUD</th>
|
|
<th>Default Value</th>
|
|
<th>Validation Constraints</th>
|
|
<th>Notes</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>id</td>
|
|
<td>uuid-str</td>
|
|
<td>N/A</td>
|
|
<td>R</td>
|
|
<td>generated</td>
|
|
<td>N/A</td>
|
|
<td>Unique identifier for the Floating IP
|
|
instance</td>
|
|
</tr>
|
|
<tr>
|
|
<td>floating_network_id</td>
|
|
<td>uuid-str</td>
|
|
<td>Yes</td>
|
|
<td>CR</td>
|
|
<td>N/A</td>
|
|
<td>UUID Pattern</td>
|
|
<td>UUID of the external network where the
|
|
floating IP is to be created</td>
|
|
</tr>
|
|
<tr>
|
|
<td>port_id</td>
|
|
<td>uuid-str</td>
|
|
<td>Yes</td>
|
|
<td>CRU</td>
|
|
<td>N/A</td>
|
|
<td>UUID Pattern</td>
|
|
<td>UUID of the port on an internal OpenStack
|
|
Networking network which should be associated
|
|
to the Floating IP</td>
|
|
</tr>
|
|
<tr>
|
|
<td>fixed_ip_address</td>
|
|
<td>IP Address</td>
|
|
<td>No</td>
|
|
<td>CRU</td>
|
|
<td>None</td>
|
|
<td>IP address or null</td>
|
|
<td>Specific IP address on
|
|
<literal>port_id</literal> which should be
|
|
associated with the floating IP</td>
|
|
</tr>
|
|
<tr>
|
|
<td>floating_ip_address</td>
|
|
<td>IP Address</td>
|
|
<td>N/A</td>
|
|
<td>R</td>
|
|
<td>Automatically allocated from pool</td>
|
|
<td>N/A</td>
|
|
<td>Address of the floating IP on the external
|
|
network</td>
|
|
</tr>
|
|
<tr>
|
|
<td>tenant_id</td>
|
|
<td>uuid-str</td>
|
|
<td>No</td>
|
|
<td>CR</td>
|
|
<td>Derived from Authentication token</td>
|
|
<td>N/A</td>
|
|
<td>Owner of the Floating IP. Only admin users can
|
|
specify a tenant identifier other than its own
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="router_ext_ops_router">
|
|
<title>Router API Operations</title>
|
|
<para>This section discusses operations for creating and
|
|
managing routers through the OpenStack Networking L3 API
|
|
extension.</para>
|
|
<section xml:id="router_list">
|
|
<title>List Routers</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="20%"/>
|
|
<col width="20%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&GET;</td>
|
|
<td>/routers</td>
|
|
<td>Returns a list of logical routers
|
|
accessible to the tenant submitting
|
|
the request.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Normal Response Code: <returnvalue>200</returnvalue>
|
|
</para>
|
|
<simpara>Error Response Codes: Unauthorized
|
|
(<errorcode>401</errorcode>)</simpara>
|
|
<para>This operation returns a list of routers to which
|
|
the tenant has access. Default policy settings return
|
|
only those routers that are owned by the tenant who
|
|
submits the request, unless the request is submitted
|
|
by an user with administrative rights. Users can
|
|
control which attributes should be returned by using
|
|
the <parameter>fields</parameter> query parameter.
|
|
Additionally, results can be filtered by using query
|
|
string parameters.</para>
|
|
<para>This operation does not require a request body; this
|
|
operation returns a response body.</para>
|
|
<example>
|
|
<title>List Routers: JSON Request</title>
|
|
<literallayout class="monospaced">GET /v2.0/routers
|
|
Accept: application/json</literallayout>
|
|
</example>
|
|
<example>
|
|
<title>List Routers: JSON Response</title>
|
|
<programlisting language="json"><xi:include href="samples/routers-get-res.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="router_show">
|
|
<title>Show Router</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="20%"/>
|
|
<col width="20%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&GET;</td>
|
|
<td>/routers/<parameter>router_id</parameter></td>
|
|
<td>Returns details about a specific
|
|
logical router.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Normal Response Code: <returnvalue>200</returnvalue>
|
|
</para>
|
|
<simpara>Error Response Codes: Unauthorized
|
|
(<errorcode>401</errorcode>), Forbidden
|
|
(<errorcode>403</errorcode>), Not Found
|
|
(<errorcode>404</errorcode>)</simpara>
|
|
<para>This operation returns the details for a specific
|
|
router whose identifier is specified on the request
|
|
URI. Users can control which attributes should be
|
|
returned by using the <parameter>fields</parameter>
|
|
query parameter.</para>
|
|
<para>This operation does not require a request
|
|
body.</para>
|
|
<para>This operation returns a response body.</para>
|
|
<example>
|
|
<title>Show Router: JSON Request</title>
|
|
<literallayout class="monospaced">GET /v2.0/routers/a9254bdb-2613-4a13-ac4c-adc581fba50d
|
|
Accept: application/json</literallayout>
|
|
</example>
|
|
<example>
|
|
<title>Show Router: JSON Response</title>
|
|
<programlisting language="json"><xi:include href="samples/routers-show-res.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="router_create">
|
|
<title>Create Router</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="20%"/>
|
|
<col width="20%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&POST;</td>
|
|
<td>/routers</td>
|
|
<td>Create a new logical router.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Normal Response Code: <returnvalue>201</returnvalue>
|
|
</para>
|
|
<simpara>Error Response Codes: Unauthorized
|
|
(<errorcode>401</errorcode>), Bad Request
|
|
(<errorcode>400</errorcode>)</simpara>
|
|
<simpara>This operation creates a new logical router. When
|
|
it is created, a logical router does not have any
|
|
internal interface. In other words, it is not
|
|
associated to any subnet. The user can optionally
|
|
specify an external gateway for a router at create
|
|
time; a router's external gateway must be plugged into
|
|
an external network, that is to say a network for
|
|
which the extended field
|
|
<literal>router:external</literal> is set to true. </simpara>
|
|
<para>In order to specify an external gateway, the
|
|
identifier of the external network must be passed in
|
|
the request body's
|
|
<literal>external_gateway_info</literal>
|
|
attribute. This can be achieved as shown in the
|
|
following snippet:</para>
|
|
<para><programlisting language="json">"external_gateway_info" :
|
|
{
|
|
"network_id": <external_network_uuid>
|
|
}</programlisting></para>
|
|
<para>This operation requires a request body.</para>
|
|
<para>This operation returns a response body.</para>
|
|
<example>
|
|
<title>Create Router: JSON Request</title>
|
|
<programlisting language="json"><xi:include href="samples/routers-post-req.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Create Router: JSON Response</title>
|
|
<programlisting language="json"><xi:include href="samples/routers-post-res.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="router_update">
|
|
<title>Update Router</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="20%"/>
|
|
<col width="20%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&PUT;</td>
|
|
<td>/routers/<parameter>router_id</parameter></td>
|
|
<td>Updates a logical router.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Normal Response Code: <returnvalue>200</returnvalue>
|
|
</para>
|
|
<simpara>Error Response Codes: Unauthorized
|
|
(<errorcode>401</errorcode>), Bad Request
|
|
(<errorcode>400</errorcode>), Not Found
|
|
(<errorcode>404</errorcode>)</simpara>
|
|
<simpara>This operation updates a logical router. Beyond
|
|
the name and the administrative state, the only
|
|
parameter which can be updated with this operation is
|
|
the external gateway. For more information concerning
|
|
how to set the external gateway for a router, please
|
|
refer to the previous section (Create Router) or to
|
|
the following example.</simpara>
|
|
<simpara>Please note that this operation does not allow to
|
|
update router interfaces. To this aim, the <link
|
|
linkend="router_add_interface">add router
|
|
interface</link> and <link
|
|
linkend="router_remove_interface">remove router
|
|
interface</link> should be used.</simpara>
|
|
<example>
|
|
<title>Update Router: JSON Request</title>
|
|
<programlisting language="json"><xi:include href="samples/routers-put-req.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Update Router: JSON Response</title>
|
|
<programlisting language="json"><xi:include href="samples/routers-put-res.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="router_delete">
|
|
<title>Delete Router</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="20%"/>
|
|
<col width="20%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&DELETE;</td>
|
|
<td>/routers/<parameter>router_id</parameter></td>
|
|
<td>Removes a logical router and its
|
|
external gateway interface, if it
|
|
exists</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Normal Response Code: <returnvalue>204</returnvalue>
|
|
</para>
|
|
<simpara>Error Response Codes: Unauthorized
|
|
(<errorcode>401</errorcode>), Not Found
|
|
(<errorcode>404</errorcode>), Conflict
|
|
(<errorcode>409</errorcode>)</simpara>
|
|
<simpara>This operation removes a logical router; the
|
|
operation will fail if the router still has some
|
|
internal interfaces.</simpara>
|
|
<simpara>Users must remove all router interfaces before
|
|
deleting the router, by removing all internal
|
|
interfaces through <link
|
|
linkend="router_remove_interface"> remove router
|
|
interface operation</link>. </simpara>
|
|
<para>This operation does not require a request
|
|
body.</para>
|
|
<para>This operation does not return a response
|
|
body.</para>
|
|
<example>
|
|
<title>Delete Router: JSON Request</title>
|
|
<literallayout class="monospaced">DELETE /v2.0/routers/8604a0de-7f6b-409a-a47c-a1cc7bc77b2e
|
|
Accept: application/json</literallayout>
|
|
</example>
|
|
</section>
|
|
<section xml:id="router_add_interface">
|
|
<title>Add Interface to Router</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="20%"/>
|
|
<col width="20%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&PUT;</td>
|
|
<td>/routers/<parameter>router_id</parameter>/add_router_interface</td>
|
|
<td>Adds an internal interface to a
|
|
logical router.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Normal Response Code: <returnvalue>200</returnvalue>
|
|
</para>
|
|
<simpara>Error Response Codes: Unauthorized
|
|
(<errorcode>401</errorcode>), Bad Request
|
|
(<errorcode>400</errorcode>), Not Found
|
|
(<errorcode>404</errorcode>), Conflict
|
|
(<errorcode>409</errorcode>)</simpara>
|
|
<para>This operation attaches a subnet to an internal
|
|
router interface. Either a subnet identifier or a port
|
|
identifier must be passed in the request body. If both
|
|
are specified, a <literal>400 Bad Request</literal>
|
|
error is returned.</para>
|
|
<para>When the <literal>subnet_id</literal> attribute is
|
|
specified in the request body, the subnet's gateway ip
|
|
address is used to create the router interface;
|
|
otherwise, if <literal>port_id</literal> is specified,
|
|
the IP address associated with the port is used for
|
|
creating the router interface.</para>
|
|
<para>It is worth remarking that a <literal>400 Bad
|
|
Request</literal> error is returned if several IP
|
|
addresses are associated with the specified port, or
|
|
if no IP address is associated with the port; also a
|
|
<literal>409 Conflict</literal> is returned if the
|
|
port is already used.</para>
|
|
<example>
|
|
<title>Add Router Interface: JSON Request</title>
|
|
<programlisting language="json">PUT /v2.0/routers/8604a0de-7f6b-409a-a47c-a1cc7bc77b2e/add_router_interface
|
|
Accept: application/json
|
|
|
|
{"subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1"}</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Add Router Interface: JSON Response</title>
|
|
<programlisting language="json">{
|
|
"subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1",
|
|
"port_id": "3a44f4e5-1694-493a-a1fb-393881c673a4"
|
|
}</programlisting>
|
|
</example>
|
|
<para>The port identifier returned by this operation can
|
|
either be the same identifier passed in the request
|
|
body or the identifier of a new port created by this
|
|
operation to attach the subnet specified by
|
|
<literal>subnet_id</literal> to the router.</para>
|
|
<para>It is also worth noting that after executing this
|
|
operation, the <literal>device_id</literal> attribute
|
|
of this port is set to the router's identifier, and
|
|
the <literal>device_owner</literal> attribute is set
|
|
to <literal>network:router_interface</literal>, as
|
|
shown in the following example:</para>
|
|
<programlisting language="json"><xi:include href="samples/router-port-res.json" parse="text"/></programlisting>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="router_remove_interface">
|
|
<title>Remove Interface from Router</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="20%"/>
|
|
<col width="20%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&PUT;</td>
|
|
<td>/routers/<parameter>router_id</parameter>/remove_router_interface</td>
|
|
<td>Removes an internal interface from a
|
|
logical router.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Normal Response Code: <returnvalue>200</returnvalue>
|
|
</para>
|
|
<simpara>Error Response Codes: Unauthorized
|
|
(<errorcode>401</errorcode>), Bad Request
|
|
(<errorcode>400</errorcode>), Not Found
|
|
(<errorcode>404</errorcode>), Conflict
|
|
(<errorcode>409</errorcode>)</simpara>
|
|
<simpara>This request requires a request body.</simpara>
|
|
<simpara>This request returns a response body.</simpara>
|
|
<para>This operation removes an internal router interface,
|
|
thus detaching a subnet from the router.</para>
|
|
<para>This operation removes an internal router interface,
|
|
which detaches a subnet from the router. You must
|
|
specify either a subnet ID or port ID in the request
|
|
body; this value is used to identify the router
|
|
interface to remove.</para>
|
|
<para>You can also specify both a subnet ID and port ID.
|
|
If you specify both IDs, the subnet ID must correspond
|
|
to the subnet ID of the first IP address on the port
|
|
specified by the port ID. Otherwise, the operation
|
|
returns a <errorcode>409</errorcode>
|
|
<errortext>Conflict</errortext> error. The response
|
|
contains information about the affected router and
|
|
interface.</para>
|
|
<para>A <errorcode>404</errorcode>
|
|
<errortext>Not Found</errortext> error will be
|
|
returned either if the router or the subnet/port do
|
|
not exist or are not visible to the user.</para>
|
|
<para>As a consequence of this operation, the port
|
|
connecting the router with the subnet is removed from
|
|
the subnet's network.</para>
|
|
<example>
|
|
<title>Remove Router Interface: JSON Request</title>
|
|
<programlisting language="json">PUT /v2.0/routers/8604a0de-7f6b-409a-a47c-a1cc7bc77b2e/remove_router_interface
|
|
Accept: application/json
|
|
|
|
{"subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1"}</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Remove Router Interface: Response</title>
|
|
<programlisting language="json">{
|
|
"id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e",
|
|
"tenant_id": "2f245a7b-796b-4f26-9cf9-9e82d248fda7",
|
|
"port_id": "3a44f4e5-1694-493a-a1fb-393881c673a4",
|
|
"subnet_id": "a2f1f29d-571b-4533-907f-5803ab96ead1"
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="router_ext_ops_floatingip">
|
|
<title>Floating IP API Operations</title>
|
|
<para>This section discusses operations for creating and
|
|
managing floating IPs through the OpenStack Networking L3
|
|
API extension.</para>
|
|
<section xml:id="floatingip_list">
|
|
<title>List Floating IPs</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="20%"/>
|
|
<col width="20%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&GET;</td>
|
|
<td>/floatingips</td>
|
|
<td>Returns a list of floating IPs
|
|
accessible to the tenant submitting
|
|
the request.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Normal Response Code: 200 OK</para>
|
|
<para>Error Response Codes: 401 Unauthorized</para>
|
|
<para>This operation does not require a request
|
|
body.</para>
|
|
<para>This operation returns a response body.</para>
|
|
<para>The operation returns a list of floating IPs to
|
|
which the tenant has access. Default policy settings
|
|
return only those floating IPs that are owned by the
|
|
tenant who submits the request, unless the request is
|
|
submitted by an user with administrative rights. Users
|
|
can control which attributes should be returned by
|
|
using the <parameter>fields</parameter> query
|
|
parameter. Additionally, results can be filtered by
|
|
using query string parameters.</para>
|
|
<example>
|
|
<title>List Floating IPs: JSON Request</title>
|
|
<literallayout class="monospaced">GET /v2.0/floatingips
|
|
Accept: application/json</literallayout>
|
|
</example>
|
|
<example>
|
|
<title>List Floating IPs: JSON Response</title>
|
|
<programlisting language="json"><xi:include href="samples/floatingips-get-res.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="floatingip_show">
|
|
<title>Show Floating IP</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="10%"/>
|
|
<col width="30%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&GET;</td>
|
|
<td>/floatingips/<parameter>floatingip_id</parameter></td>
|
|
<td>Returns details about a specific
|
|
Floating IP.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Normal Response Code: 200 OK</para>
|
|
<para>Error Response Code: 401 Unauthorized, 404 Not
|
|
Found</para>
|
|
<para>This operation does not require a request
|
|
body.</para>
|
|
<para>This operation returns a response body.</para>
|
|
<para>This operation returns the details for a specific
|
|
floating IP whose identifier is specified on the
|
|
request URI. Users can control which attributes should
|
|
be returned by using the <parameter>fields</parameter>
|
|
query parameter.</para>
|
|
<example>
|
|
<title>Show Floating IP: JSON Request</title>
|
|
<literallayout class="monospaced">GET /v2.0/floatingips/2f245a7b-796b-4f26-9cf9-9e82d248fda7.json?fields=fixed_ip_address&fields=floating_ip_address
|
|
Accept: application/json</literallayout>
|
|
</example>
|
|
<example>
|
|
<title>Show Floating IP: JSON Response</title>
|
|
<programlisting language="json"><xi:include href="samples/floatingips-show-res.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="floatingip_create">
|
|
<title>Create Floating IP</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="20%"/>
|
|
<col width="20%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&POST;</td>
|
|
<td>/floatingips</td>
|
|
<td>Creates a floating IP, and configures
|
|
its association with an internal port,
|
|
if the relevant information are
|
|
specified</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Normal Response Code: 200 OK</para>
|
|
<para>Error Response Code: 400 Bad Request, 401
|
|
Unauthorized, 409 Conflict</para>
|
|
<para>This operation requires a request body.</para>
|
|
<para>This operation returns a response body.</para>
|
|
<para>This operation creates a floating IP. Users can
|
|
specify association information for this floating IP
|
|
in the request body. These information are however
|
|
optional, and can be specified with an UPDATE call at
|
|
a later stage. The only mandatory parameter in the
|
|
request body is the external network identifier,
|
|
<literal>floating_network_id</literal>. Floating
|
|
IPs can only be created on external networks. If the
|
|
network specified by
|
|
<literal>floating_network_id</literal> is not
|
|
external (for example,
|
|
<errorcode>router:external=False</errorcode>), a
|
|
<errorcode>400</errorcode> error is
|
|
returned.</para>
|
|
<para>An address for the floating ip will be automatically
|
|
allocated, unless the
|
|
<literal>floating_ip_address</literal> attribute
|
|
is specified in the request body. If the requested
|
|
floating IP address does not fall in the external
|
|
network's subnet range, a <errorcode>400</errorcode>
|
|
error will be returned. If the requested floating IP
|
|
address is already in use, a
|
|
<errorcode>409</errorcode> error code will be
|
|
returned.</para>
|
|
<para>Users can associate the floating IP with an internal
|
|
port using the <literal>port_id</literal> attribute in
|
|
the request body. If an invalid port identifier is
|
|
specified, a <errorcode>404</errorcode> error will be
|
|
returned. The internal OpenStack Networking port
|
|
associated with the Floating IP must have at least an
|
|
IP address configured, otherwise a
|
|
<errorcode>400</errorcode> error will be
|
|
returned.</para>
|
|
<para>As an OpenStack Networking port might be associated
|
|
with multiple IP addresses, the particular IP address
|
|
to associate with the floating IP can be specified
|
|
using the <literal>fixed_ip_address</literal> request
|
|
body parameter. The default logic of this operation is
|
|
to associate the floating IP with a single IP address
|
|
configured on a port; hence, if a port has multiple IP
|
|
addresses, it is mandatory to specify the
|
|
<literal>fixed_ip_address</literal> attribute. If
|
|
an invalid IP address is specified in
|
|
<literal>fixed_ip_address</literal> a
|
|
<errorcode>400</errorcode> error will be
|
|
returned.</para>
|
|
<para>If the internal OpenStack Networking port and ip
|
|
address selected for association are already
|
|
associated to another floating IP, a 409 error will be
|
|
returned.</para>
|
|
<example>
|
|
<title>Create Floating IP: JSON Request</title>
|
|
<programlisting language="json"><xi:include href="samples/floatingips-post-req-json-http.txt" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Create Floating IP: JSON Response</title>
|
|
<programlisting language="json"><xi:include href="samples/floatingips-post-res.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="floatingip_update">
|
|
<title>Update Floating IP</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="10%"/>
|
|
<col width="30%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&PUT;</td>
|
|
<td>/floatingips/<parameter>floatingip_id</parameter></td>
|
|
<td>Updates a floating IP and its
|
|
association with an internal port, if
|
|
the relevant information are specified
|
|
in the request body.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Normal Response Code: 200 OK</para>
|
|
<para>Error Response Code: 400 Bad Request, 401
|
|
Unauthorized, 404 Not Found, 409 Conflict</para>
|
|
<para>This operation requires a request body.</para>
|
|
<para>This operation returns a response body.</para>
|
|
<para xml:id="para_jmc_xsv_pj">This operation updates an
|
|
association between a floating IP and an OpenStack
|
|
Networking port. The association process is exactly
|
|
the same as the one discussed for the <emphasis
|
|
role="italic">create floating IP</emphasis>
|
|
operation.</para>
|
|
<para>To disassociate a floating IP from a port, set the
|
|
<literal>port_id</literal> request attribute to
|
|
null or omit it from the request body.</para>
|
|
<example>
|
|
<title>Update Floating IP (associate): JSON
|
|
Request</title>
|
|
<programlisting language="json"><xi:include href="samples/floatingips-put-ass-req.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Update Floating IP (associate): JSON
|
|
Response</title>
|
|
<programlisting language="json"><xi:include href="samples/floatingips-put-ass-res.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Update Floating IP (disassociate): JSON
|
|
Request</title>
|
|
<programlisting language="json"><xi:include href="samples/floatingips-put-disass-req.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Update Floating IP (disassociate): JSON
|
|
Response</title>
|
|
<programlisting language="json"><xi:include href="samples/floatingips-put-disass-res.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="floatingip_delete">
|
|
<title>Delete Floating IP</title>
|
|
<para>
|
|
<informaltable rules="all" width="100%">
|
|
<col width="20%"/>
|
|
<col width="20%"/>
|
|
<col width="60%"/>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&DELETE;</td>
|
|
<td>/floatingips/<parameter>floatingip_id</parameter></td>
|
|
<td>Removes a floating IP and its
|
|
association information.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Normal Response Code: 204</para>
|
|
<para>Error Response Code: 401 Unauthorized, 404 Not
|
|
Found</para>
|
|
<para>This operation does not require a request
|
|
body.</para>
|
|
<para>This operation does not return a response
|
|
body.</para>
|
|
<para>The operation removes the floating IP whose
|
|
identifier is specified in the request URI. If the
|
|
floating IP being removed is associated with an
|
|
OpenStack Networking port, the association is removed
|
|
as well.</para>
|
|
<para>
|
|
<example>
|
|
<title>Delete Floating IP: JSON Request</title>
|
|
<literallayout class="monospaced">DELETE /v2.0/floatingips/2f245a7b-796b-4f26-9cf9-9e82d248fda7
|
|
Accept: application/json</literallayout>
|
|
</example>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</section>
|