c5a1e0fb52
remove unneeded files fix formatting spell-check title capitalization Change-Id: I6f98cf14a02d138a87f22b213be82664372a7727 author: diane fleming
588 lines
24 KiB
XML
588 lines
24 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 APIv2 'Networking API v2.0'>
|
|
]>
|
|
<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:xsdxt="http://docs.rackspacecloud.com/xsd-ext/v1.0"
|
|
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
|
|
xml:id="Concepts-d1e369">
|
|
<?dbhtml stop-chunking?>
|
|
<title>Concepts</title>
|
|
<para>Use the &APIv2; to manage the following entities:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Network</emphasis>. An
|
|
isolated virtual layer-2 domain. A network can also be
|
|
a virtual, or logical, switch. See <xref
|
|
linkend="Network"/>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Subnet</emphasis>. An IP
|
|
version 4 or version 6 address block from which IP
|
|
addresses that are assigned to VMs on a specified
|
|
network are selected. See <xref linkend="subnet"
|
|
/>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Port</emphasis>. A virtual, or
|
|
logical, switch port on a specified network. See <xref
|
|
linkend="Port"/>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>These entities have auto-generated unique identifiers and
|
|
support basic create, read, update, and delete (CRUD)
|
|
functions with the &POST;, &GET;, &PUT;, and &DELETE;
|
|
verbs.</para>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Network">
|
|
<title>Network</title>
|
|
<para>A network is an isolated virtual layer-2 broadcast
|
|
domain that is typically reserved for the tenant who
|
|
created it unless you configure the network to be shared.
|
|
Tenants can create multiple networks until the thresholds
|
|
per-tenant quota is reached.</para>
|
|
<para>In the &APIv2;, the network is the main entity. Ports
|
|
and subnets are always associated with a network.</para>
|
|
<?hard-pagebreak?>
|
|
<para>The following table describes the attributes for network
|
|
objects:</para>
|
|
<table rules="all" width="95%">
|
|
<caption>Network attributes</caption>
|
|
<col width="20%"/>
|
|
<col width="10%"/>
|
|
<col width="10%"/>
|
|
<col width="10%"/>
|
|
<col width="15%"/>
|
|
<col width="17%"/>
|
|
<col width="20%"/>
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Type</th>
|
|
<th>Required</th>
|
|
<th>CRUD<footnote xml:id="crud">
|
|
<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>
|
|
</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>UUID for the network.</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 network. Might not
|
|
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>The administrative state of network. If false
|
|
(down), the network does not forward
|
|
packets.</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><para>Indicates whether network is currently
|
|
operational. Possible values
|
|
include:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>ACTIVE</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>DOWN</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>BUILD</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>ERROR</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>Plug-ins might define additional
|
|
values.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td>subnets</td>
|
|
<td>list(uuid-str)</td>
|
|
<td>No</td>
|
|
<td>R</td>
|
|
<td>Empty List</td>
|
|
<td>N/A</td>
|
|
<td>subnets associated with this network.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>shared</td>
|
|
<td>Bool</td>
|
|
<td>No</td>
|
|
<td>CRU</td>
|
|
<td>False</td>
|
|
<td>{ True | False }</td>
|
|
<td>Specifies whether the network resource can be
|
|
accessed by any tenant or not.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>tenant_id</td>
|
|
<td>uuid-str</td>
|
|
<td>No<footnote xml:id="tenant">
|
|
<para>If OpenStack Networking is not
|
|
running with the Keystone Identity
|
|
service, the
|
|
<literal>tenant_id</literal>
|
|
attribute is required.</para>
|
|
</footnote>
|
|
</td>
|
|
<td>CR</td>
|
|
<td>N/A</td>
|
|
<td>No constraint</td>
|
|
<td>Owner of network. Only admin users can specify
|
|
a tenant_id other than its own.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="subnet">
|
|
<title>Subnet</title>
|
|
<para>A subnet represents an IP address block that can be used
|
|
to assign IP addresses to virtual instances. Each subnet
|
|
must have a CIDR and must be associated with a network.
|
|
IPs can be either selected from the whole subnet CIDR or
|
|
from allocation pools that can be specified by the
|
|
user.</para>
|
|
<para>A subnet can also optionally have a gateway, a list of
|
|
dns name servers, and host routes. This information is
|
|
pushed to instances whose interfaces are associated with
|
|
the subnet.</para>
|
|
<?hard-pagebreak?>
|
|
<table rules="all" width="95%">
|
|
<caption>Subnet Attributes</caption>
|
|
<col width="20%"/>
|
|
<col width="10%"/>
|
|
<col width="10%"/>
|
|
<col width="10%"/>
|
|
<col width="15%"/>
|
|
<col width="17%"/>
|
|
<col width="20%"/>
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Type</th>
|
|
<th>Required</th>
|
|
<th>CRUD<footnote xml:id="crud2">
|
|
<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>
|
|
</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>UUID representing the subnet</td>
|
|
</tr>
|
|
<tr>
|
|
<td>network_id</td>
|
|
<td>uuid-str</td>
|
|
<td>Yes</td>
|
|
<td>CR</td>
|
|
<td>N/A</td>
|
|
<td>network this subnet is associated with.</td>
|
|
<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 subnet. Might not
|
|
be unique.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>ip_version</td>
|
|
<td>int</td>
|
|
<td>Yes</td>
|
|
<td>CR</td>
|
|
<td>4</td>
|
|
<td>{ 4 | 6 }</td>
|
|
<td>IP version</td>
|
|
</tr>
|
|
<tr>
|
|
<td>cidr</td>
|
|
<td>string</td>
|
|
<td>Yes</td>
|
|
<td>CR</td>
|
|
<td>N/A</td>
|
|
<td>valid cidr in the form
|
|
<network_address>/<prefix></td>
|
|
<td>cidr representing IP range for this subnet,
|
|
based on IP version</td>
|
|
</tr>
|
|
<tr>
|
|
<td>gateway_ip</td>
|
|
<td>string</td>
|
|
<td>No</td>
|
|
<td>CRUD</td>
|
|
<td>first address in <emphasis role="italic"
|
|
>cidr</emphasis>
|
|
</td>
|
|
<td>Valid IP address or null</td>
|
|
<td>default gateway used by devices in this
|
|
subnet</td>
|
|
</tr>
|
|
<tr>
|
|
<td>dns_nameservers</td>
|
|
<td>list(str)</td>
|
|
<td>No</td>
|
|
<td>CRU</td>
|
|
<td>Empty list</td>
|
|
<td>No constraint</td>
|
|
<td>DNS name servers used by hosts in this
|
|
subnet.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>allocation_pools</td>
|
|
<td>list(dict)</td>
|
|
<td>No</td>
|
|
<td>CR</td>
|
|
<td>Every address in <emphasis role="italic"
|
|
>cidr</emphasis>, excluding <emphasis
|
|
role="italic">gateway_ip</emphasis> if
|
|
configured</td>
|
|
<td>star/end of range must be valid ip</td>
|
|
<td>Sub-ranges of cidr available for dynamic
|
|
allocation to ports [ { "start": "10.0.0.2",
|
|
"end": "10.0.0.254"} ]</td>
|
|
</tr>
|
|
<tr>
|
|
<td>host_routes</td>
|
|
<td>list(dict)</td>
|
|
<td>No</td>
|
|
<td>CRU</td>
|
|
<td>Empty List</td>
|
|
<td>
|
|
<emphasis role="italic">[]</emphasis>
|
|
</td>
|
|
<td>Routes that should be used by devices with IPs
|
|
from this subnet (not including local subnet
|
|
route).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>enable_dhcp</td>
|
|
<td>Bool</td>
|
|
<td>No</td>
|
|
<td>CRU</td>
|
|
<td>True</td>
|
|
<td>{ True | False }</td>
|
|
<td>Specifies whether DHCP is enabled for this
|
|
subnet or not.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>tenant_id</td>
|
|
<td>uuid-str</td>
|
|
<td>No<footnote xml:id="tenant2">
|
|
<para>If OpenStack Networking is not
|
|
running with the Keystone Identity
|
|
service, the
|
|
<literal>tenant_id</literal>
|
|
attribute is required.</para>
|
|
</footnote></td>
|
|
<td>CR</td>
|
|
<td>N/A</td>
|
|
<td>No constraint</td>
|
|
<td>Owner of network. Only admin users can specify
|
|
a tenant_id other than its own.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Port">
|
|
<title>Port</title>
|
|
<para>A port represents a virtual switch port on a logical
|
|
network switch. Virtual instances attach their interfaces
|
|
into ports. The logical port also defines the MAC address
|
|
and the IP address(es) to be assigned to the interfaces
|
|
plugged into them. When IP addresses are associated to a
|
|
port, this also implies the port is associated with a
|
|
subnet, as the IP address was taken from the allocation
|
|
pool for a specific subnet.</para>
|
|
<?hard-pagebreak?>
|
|
<table rules="all" width="95%">
|
|
<caption>Port Attributes</caption>
|
|
<col width="20%"/>
|
|
<col width="10%"/>
|
|
<col width="10%"/>
|
|
<col width="10%"/>
|
|
<col width="15%"/>
|
|
<col width="17%"/>
|
|
<col width="20%"/>
|
|
<thead>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Type</th>
|
|
<th>Required</th>
|
|
<th>CRUD<footnote xml:id="crud3">
|
|
<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>
|
|
</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>UUID for the port.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>network_id</td>
|
|
<td>uuid-str</td>
|
|
<td>Yes</td>
|
|
<td>CR</td>
|
|
<td>N/A</td>
|
|
<td>existing network identifier</td>
|
|
<td>Network that this port is associated with.
|
|
</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 port. Might not 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 port. If false (down),
|
|
port does not forward packets.</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><para>Indicates whether network is currently
|
|
operational. Possible values
|
|
include:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>ACTIVE</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>DOWN</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>BUILD</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>ERROR</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>Plug-ins might define additional
|
|
values.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td>mac_address</td>
|
|
<td>string</td>
|
|
<td>No</td>
|
|
<td>CR</td>
|
|
<td>generated</td>
|
|
<td>valid MAC in 6-octet form separated by
|
|
colons</td>
|
|
<td>Mac address to use on this port.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>fixed_ips</td>
|
|
<td>list(dict)</td>
|
|
<td>No</td>
|
|
<td>CRU</td>
|
|
<td>automatically allocated from pool</td>
|
|
<td>Valid IP address and existing subnet
|
|
identifier</td>
|
|
<td>Specifies IP addresses for the port thus
|
|
associating the port itself with the subnets
|
|
where the IP addresses are picked from</td>
|
|
</tr>
|
|
<tr>
|
|
<td>device_id</td>
|
|
<td>str</td>
|
|
<td>No</td>
|
|
<td>CRUD</td>
|
|
<td>None</td>
|
|
<td>No constraint</td>
|
|
<td>identifies the device (e.g., virtual server)
|
|
using this port.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>device_owner</td>
|
|
<td>str</td>
|
|
<td>No</td>
|
|
<td>CRUD</td>
|
|
<td>None</td>
|
|
<td>No constraint</td>
|
|
<td>Identifies the entity (e.g.: dhcp agent) using
|
|
this port.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>tenant_id</td>
|
|
<td>uuid-str</td>
|
|
<td>No<footnote xml:id="tenant3">
|
|
<para>If OpenStack Networking is not
|
|
running with the Keystone Identity
|
|
service, the
|
|
<literal>tenant_id</literal>
|
|
attribute is required.</para>
|
|
</footnote>
|
|
</td>
|
|
<td>CR</td>
|
|
<td>N/A</td>
|
|
<td>No constraint</td>
|
|
<td>Owner of network. Only admin users can specify
|
|
a tenant_id other than its own.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>security_groups</td>
|
|
<td>list(dict)</td>
|
|
<td>No</td>
|
|
<td>CRUD</td>
|
|
<td>None</td>
|
|
<td>Existing security group IDs</td>
|
|
<td>Specifies the IDs of any security groups
|
|
associated with a port.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
</section>
|