b51a471b55
Remove extra whitespace like whitespace at end of line or before a closing </para>. Also, change tabs to spaces. Change-Id: I43d5418cc6c21736a29921e88774cdfdadc09b28
256 lines
11 KiB
XML
256 lines
11 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="external_net" 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>External Network Extension (<literal>external-net</literal>)</title>
|
|
<para>
|
|
The external network extension is used to specify whether
|
|
the network is external or not. This information is used
|
|
by Layer-3 network (<literal>router</literal>) extension.
|
|
External networks are connected to a router's external
|
|
gateway and host floating IPs.
|
|
</para>
|
|
<section xml:id="ext_net_concepts">
|
|
<title>Concepts</title>
|
|
<para>
|
|
The External Network extension adds the
|
|
<emphasis role="italic">router:external</emphasis>
|
|
attribute to the network resource.
|
|
</para>
|
|
<table rules="all">
|
|
<caption>Network 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="crud_ext_net">
|
|
<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>router:external</td>
|
|
<td>Bool</td>
|
|
<td>No</td>
|
|
<td>CRU</td>
|
|
<td>False</td>
|
|
<td>{ True | False }</td>
|
|
<td>Specifies whether the network is an external network or not.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<section xml:id="external_net_ops">
|
|
<title>Network API operations with external network extension</title>
|
|
<section xml:id="external_network_list">
|
|
<title>List Networks</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>/networks</td>
|
|
<td>Returns a list of networks with their router:external
|
|
attributes.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
Response codes are same as the normal operation of listing networks.
|
|
<emphasis role="italic">router:external</emphasis> attribute is visible
|
|
to all users by default policy setting.
|
|
</para>
|
|
<para>
|
|
Regular users are not authorized to create ports on external networks,
|
|
however they will be able to see this attribute in their network list.
|
|
This is because external networks can be used by any tenant to
|
|
set an external gateway for Neutron routers or create floating
|
|
IPs and associate them with ports on internal tenant networks.
|
|
</para>
|
|
<example>
|
|
<title>List Networks with router:external attribute: JSON Response</title>
|
|
<programlisting language="json"><xi:include href="samples/networks-get-res-extnet.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="external_network_show">
|
|
<title>Show Network</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>/networks/<parameter>network_id</parameter></td>
|
|
<td>Returns details about a specific network, including external
|
|
networks attributes.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>Response codes are same as the normal operation of listing networks.
|
|
<emphasis role="italic">router:external</emphasis> attribute is visible
|
|
to all users including non-admin by default policy setting.
|
|
</para>
|
|
<example>
|
|
<title>Show network with external attributes: JSON Response</title>
|
|
<programlisting language="json"><xi:include href="samples/networks-show-res-extnet.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="external_network_create">
|
|
<title>Create Network</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>/networks</td>
|
|
<td>Creates a new network using the external network extension
|
|
attribute.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
If the user submitting the request is not allowed to set this
|
|
attribute, a 403 Forbidden response will be returned.
|
|
Usage of this attribute might be restricted through authorization policies.
|
|
By the default policy only admin users can set this attribute.
|
|
</para>
|
|
<example>
|
|
<title>Create Network with external attributes: JSON Request</title>
|
|
<programlisting language="json"><xi:include href="samples/networks-post-req-extnet.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="external_network_update">
|
|
<title>Update Network</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>/networks/<parameter>network_id</parameter></td>
|
|
<td>Updates a network, including the external
|
|
network extension attribute.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
If the user submitting the request is not allowed to set this
|
|
attribute, a 403 Forbidden response will be returned.
|
|
Usage of this attribute might be restricted through authorization policies.
|
|
By the default policy only admin users can set this attribute.
|
|
</para>
|
|
<example>
|
|
<title>Update external attributes for a network: JSON Request</title>
|
|
<programlisting language="json"><xi:include href="samples/networks-put-req-extnet.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
<?hard-pagebreak?>
|