75e75b03b3
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
208 lines
9.4 KiB
XML
208 lines
9.4 KiB
XML
<?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>
|