API docs for configurable external gateway modes extension
Bug 1216576 The documentation discusses how the router resources is extended and provides information concerning how to enable or disable SNAT using the Neutron API. Change-Id: I20f2913495558dd40b1d9ffa59797a97a342bf49
This commit is contained in:
Salvatore Orlando
parent
64cca08847
commit
75e75b03b3
@ -2676,6 +2676,7 @@ Date: Wed, 12 Sep 2012 11:36:20 GMT</literallayout>
|
|||||||
</section>
|
</section>
|
||||||
<xi:include href="neutron-provider-ext.xml"/>
|
<xi:include href="neutron-provider-ext.xml"/>
|
||||||
<xi:include href="neutron-l3-ext.xml"/>
|
<xi:include href="neutron-l3-ext.xml"/>
|
||||||
|
<xi:include href="neutron-extgwmodes-ext.xml"/>
|
||||||
<xi:include href="neutron-quotas-ext.xml"/>
|
<xi:include href="neutron-quotas-ext.xml"/>
|
||||||
<xi:include href="neutron-security-groups-ext.xml"/>
|
<xi:include href="neutron-security-groups-ext.xml"/>
|
||||||
<xi:include href="neutron-agent-ext.xml"/>
|
<xi:include href="neutron-agent-ext.xml"/>
|
||||||
|
|||||||
207
v2.0/neutron-extgwmodes-ext.xml
Normal file
207
v2.0/neutron-extgwmodes-ext.xml
Normal file
@ -0,0 +1,207 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE section[
|
||||||
|
<!-- 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>'>
|
||||||
|
]>
|
||||||
|
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" version="5.0" status="final" xml:id="extgwmodes-ext">
|
||||||
|
<title>Configurable external gateway modes extension</title>
|
||||||
|
<para>By default, when a gateway is attached to a router using the Neutron L3 extension, Network
|
||||||
|
Address Translation (NAT) is enabled for traffic generated by subnets attached to the
|
||||||
|
router. With this extension, the user will have the option of choosing whether SNAT
|
||||||
|
should be enabled or not on a router basis.</para>
|
||||||
|
<para>This is achieved simply by specifying a boolean attribute, <literal>enable_snat</literal>,
|
||||||
|
in the <literal>external_gateway_info</literal> attribute of the <literal>router</literal>
|
||||||
|
resource. </para>
|
||||||
|
<para>This extension redefines the external_gateway_info attribute as depicted in the following
|
||||||
|
table. </para>
|
||||||
|
<table rules="all">
|
||||||
|
<caption>external_gateway_info attributes</caption>
|
||||||
|
<col width="20%"/>
|
||||||
|
<col width="8%"/>
|
||||||
|
<col width="10%"/>
|
||||||
|
<col width="15%"/>
|
||||||
|
<col width="15%"/>
|
||||||
|
<col width="32%"/>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Attribute </th>
|
||||||
|
<th>Type </th>
|
||||||
|
<th>Required </th>
|
||||||
|
<th>Default Value </th>
|
||||||
|
<th>Validation Constraints </th>
|
||||||
|
<th>Notes</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td>network_id</td>
|
||||||
|
<td>UUID</td>
|
||||||
|
<td>Yes</td>
|
||||||
|
<td>N/A</td>
|
||||||
|
<td>Must be a valid uuid representative of an external network.</td>
|
||||||
|
<td/>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>enable_snat</td>
|
||||||
|
<td>Boolean</td>
|
||||||
|
<td>No</td>
|
||||||
|
<td>True</td>
|
||||||
|
<td>{True|False}</td>
|
||||||
|
<td>The default setting is <literal>True</literal> to ensure backward compatibility
|
||||||
|
for plugins supporting this extension.</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<para>SNAT can be enabled or disabled at any time on a Neutron router regardless of the
|
||||||
|
current status of floating IPs. Floating IPs will continue working even when SNAT is
|
||||||
|
disabled.</para>
|
||||||
|
<section xml:id="list_routers_extgwmodes">
|
||||||
|
<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>Retrieve Neutron routers</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</informaltable>
|
||||||
|
</para>
|
||||||
|
<simpara>Success and error response codes are not changed with regards to the operation as
|
||||||
|
introduced by the L3 API extension.</simpara>
|
||||||
|
<simpara>When this extension is enabled, this operation will also return the current Source
|
||||||
|
NAT status for configured routers, as shown in the sample below.</simpara>
|
||||||
|
<simpara>The response for the <emphasis>show router</emphasis> operation is the same, with
|
||||||
|
the obvious exception that a single router is returned.</simpara>
|
||||||
|
<example>
|
||||||
|
<title>Router list with configurable external gateway modes enabled</title>
|
||||||
|
<programlisting language="json"><xi:include href="samples/routers-get-enablesnat-res.json" parse="text"/></programlisting>
|
||||||
|
</example>
|
||||||
|
</section>
|
||||||
|
<section xml:id="create_router_extgwmodes">
|
||||||
|
<title>Create Router with external gateway</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 Neutron router</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</informaltable>
|
||||||
|
|
||||||
|
</para>
|
||||||
|
<para>Success and error response codes are not changed with regards to the operation as
|
||||||
|
introduced by the L3 API extension.</para>
|
||||||
|
<para>Neutron API users can specify whether SNAT should be performed on the network
|
||||||
|
specifed as the router's external gateway by setting <literal>enable_snat</literal> in
|
||||||
|
<literal>external_gateway_info</literal> to either <literal>True</literal> or
|
||||||
|
<literal>False</literal>; the default value is <literal>True</literal>.</para>
|
||||||
|
<example>
|
||||||
|
<title>Create router with SNAT disabled</title>
|
||||||
|
<programlisting><xi:include href="samples/router-create-enablesnat.sample" parse="text"/></programlisting>
|
||||||
|
</example>
|
||||||
|
</section>
|
||||||
|
<section xml:id="update_router_extgwmodes">
|
||||||
|
<title>Update Router's external gateway info</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/<literal>router_id</literal></td>
|
||||||
|
<td>Create a new Neutron router</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</informaltable>
|
||||||
|
</para>
|
||||||
|
<para>Success and error response codes are not changed with regards to the operation as
|
||||||
|
introduced by the L3 API extension.</para>
|
||||||
|
<para>Neutron API users can enable or disable SNAT on a router specifying the
|
||||||
|
<literal>enable_snat</literal> attribute in the
|
||||||
|
<literal>external_gateway_info</literal> attribute for the router resource. This
|
||||||
|
operation can be either used for updating the SNAT status only, the
|
||||||
|
external network, or both attributes at the same time. In any case, if
|
||||||
|
the <literal>enable_snat</literal> attribute is not specified, it will default to
|
||||||
|
<literal>True</literal>. For instance, if the current SNAT status is disabled, and
|
||||||
|
the router's gateway is updated to a different external network without specifying
|
||||||
|
<literal>enable_snat</literal>, SNAT will be enabled for the new network.</para>
|
||||||
|
<para>It is important to note that whenever updating a router's external gateway
|
||||||
|
information, the <literal>network_id </literal>parameter must be specified always, even
|
||||||
|
if the final goal is just to enable or disable SNAT for the router on the same
|
||||||
|
external network.</para>
|
||||||
|
<para>The rest of this section provides some samples for updating a router's external gateway
|
||||||
|
info with SNAT mode.</para>
|
||||||
|
<para>
|
||||||
|
<example>
|
||||||
|
<title>Disable SNAT for the current external network</title>
|
||||||
|
<programlisting><xi:include href="samples/router-update-enablesnat-1.sample" parse="text"/></programlisting>
|
||||||
|
</example>
|
||||||
|
<example>
|
||||||
|
<title>Change external network and enable SNAT</title>
|
||||||
|
<programlisting><xi:include href="samples/router-update-enablesnat-2.sample" parse="text"/></programlisting>
|
||||||
|
</example>
|
||||||
|
<example>
|
||||||
|
<title>Change external network and keep SNAT disabled</title>
|
||||||
|
<programlisting><xi:include href="samples/router-update-enablesnat-3.sample" parse="text"/></programlisting>
|
||||||
|
</example>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
<?hard-pagebreak?>
|
||||||
|
|
||||||
|
</section>
|
||||||
29
v2.0/samples/router-create-enablesnat.sample
Normal file
29
v2.0/samples/router-create-enablesnat.sample
Normal file
@ -0,0 +1,29 @@
|
|||||||
|
|
||||||
|
POST /v2.0/routers
|
||||||
|
Accept: application/json
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"name": "another_router",
|
||||||
|
"admin_state_up": true,
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
|
||||||
|
"enable_snat": false}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
HTTP/1.1 201 OK
|
||||||
|
Content-Type: application/json; charset=UTF-8
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
|
||||||
|
"enable_snat": false}
|
||||||
|
"name": "another_router",
|
||||||
|
"admin_state_up": true,
|
||||||
|
"tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
|
||||||
|
"id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
|
||||||
|
}
|
||||||
|
}
|
||||||
55
v2.0/samples/router-update-enablesnat-1.sample
Normal file
55
v2.0/samples/router-update-enablesnat-1.sample
Normal file
@ -0,0 +1,55 @@
|
|||||||
|
POST /v2.0/routers
|
||||||
|
Accept: application/json
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"name": "another_router",
|
||||||
|
"admin_state_up": true,
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8"}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
HTTP/1.1 201 OK
|
||||||
|
Content-Type: application/json; charset=UTF-8
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
|
||||||
|
"enable_snat": true}
|
||||||
|
"name": "another_router",
|
||||||
|
"admin_state_up": true,
|
||||||
|
"tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
|
||||||
|
"id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
PUT /v2.0/routers
|
||||||
|
Accept: application/json
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
|
||||||
|
"enable_snat": false}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-Type: application/json; charset=UTF-8
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
|
||||||
|
"enable_snat": false}
|
||||||
|
"name": "another_router",
|
||||||
|
"admin_state_up": true,
|
||||||
|
"tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
|
||||||
|
"id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
|
||||||
|
}
|
||||||
|
}
|
||||||
55
v2.0/samples/router-update-enablesnat-2.sample
Normal file
55
v2.0/samples/router-update-enablesnat-2.sample
Normal file
@ -0,0 +1,55 @@
|
|||||||
|
POST /v2.0/routers
|
||||||
|
Accept: application/json
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"name": "another_router",
|
||||||
|
"admin_state_up": true,
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
|
||||||
|
"enable_snat": false}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
HTTP/1.1 201 OK
|
||||||
|
Content-Type: application/json; charset=UTF-8
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
|
||||||
|
"enable_snat": false}
|
||||||
|
"name": "another_router",
|
||||||
|
"admin_state_up": true,
|
||||||
|
"tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
|
||||||
|
"id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
PUT /v2.0/routers
|
||||||
|
Accept: application/json
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "002ab3b9-9127-4158-be30-4b45f3814df5"}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-Type: application/json; charset=UTF-8
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "002ab3b9-9127-4158-be30-4b45f3814df5",
|
||||||
|
"enable_snat": true}
|
||||||
|
"name": "another_router",
|
||||||
|
"admin_state_up": true,
|
||||||
|
"tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
|
||||||
|
"id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
|
||||||
|
}
|
||||||
|
}
|
||||||
56
v2.0/samples/router-update-enablesnat-3.sample
Normal file
56
v2.0/samples/router-update-enablesnat-3.sample
Normal file
@ -0,0 +1,56 @@
|
|||||||
|
POST /v2.0/routers
|
||||||
|
Accept: application/json
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"name": "another_router",
|
||||||
|
"admin_state_up": true,
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
|
||||||
|
"enable_snat": false}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
HTTP/1.1 201 OK
|
||||||
|
Content-Type: application/json; charset=UTF-8
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
|
||||||
|
"enable_snat": false}
|
||||||
|
"name": "another_router",
|
||||||
|
"admin_state_up": true,
|
||||||
|
"tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
|
||||||
|
"id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
PUT /v2.0/routers
|
||||||
|
Accept: application/json
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "002ab3b9-9127-4158-be30-4b45f3814df5",
|
||||||
|
"enable_snat": false}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-Type: application/json; charset=UTF-8
|
||||||
|
{
|
||||||
|
"router":
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"external_gateway_info": {
|
||||||
|
"network_id": "002ab3b9-9127-4158-be30-4b45f3814df5",
|
||||||
|
"enable_snat": false}
|
||||||
|
"name": "another_router",
|
||||||
|
"admin_state_up": true,
|
||||||
|
"tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
|
||||||
|
"id": "8604a0de-7f6b-409a-a47c-a1cc7bc77b2e"
|
||||||
|
}
|
||||||
|
}
|
||||||
23
v2.0/samples/routers-get-enablesnat-res.json
Normal file
23
v2.0/samples/routers-get-enablesnat-res.json
Normal file
@ -0,0 +1,23 @@
|
|||||||
|
{
|
||||||
|
"routers":
|
||||||
|
[{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"external_gateway_info":
|
||||||
|
{"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
|
||||||
|
"enable_snat": true},
|
||||||
|
"name": "second_router",
|
||||||
|
"admin_state_up": true,
|
||||||
|
"tenant_id": "6b96ff0cb17a4b859e1e575d221683d3",
|
||||||
|
"id": "7177abc4-5ae9-4bb7-b0d4-89e94a4abf3b"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"status": "ACTIVE",
|
||||||
|
"external_gateway_info":
|
||||||
|
{"network_id": "3c5bcddd-6af9-4e6b-9c3e-c153e521cab8",
|
||||||
|
"enable_snat": false},
|
||||||
|
"name": "router1",
|
||||||
|
"admin_state_up": true,
|
||||||
|
"tenant_id": "33a40233088643acb66ff6eb0ebea679",
|
||||||
|
"id": "a9254bdb-2613-4a13-ac4c-adc581fba50d"
|
||||||
|
}]
|
||||||
|
}
|
||||||
Loading…
Reference in New Issue
Block a user