openstack-attic/netconn-api
Code Issues Proposed changes
2cd41cb7a4
netconn-api/v2.0/section_neutron-agent-ext.xml
Andreas Jaeger b51a471b55 Remove extra whitespace 
Remove extra whitespace like whitespace at end of line or
before a closing </para>. Also, change tabs to spaces.

Change-Id: I43d5418cc6c21736a29921e88774cdfdadc09b28
2013-12-26 18:40:20 +01:00

277 lines
12 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- 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 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="agent_ext">
<title>The Agent Management Extension</title>
<para>In a typical OpenStack Networking deployment, some agents run on network or compute
nodes, such as <literal>neutron-dhcp-agent</literal>, <literal>neutron-ovs-agent</literal>,
and <literal>neutron-l3-agent</literal>. This extension provides a way for
administrators(enforced by the policy engine) to view their status and update their
attributes. Updating agent management API attributes will affect operations of other
components such as OpenStack Networking schedulers. For instance administrators can disable
a certain agent, and OpenStack Networking schedulers will not schedule resources to
it.</para>
<para>For how to use agent management extension and OpenStack Networking schedulers feature,
see the <citetitle>OpenStack Cloud Administrator Guide</citetitle>.</para>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr align="center">
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&GET;</td>
<td>/agents</td>
<td>List agents which report their status to OpenStack Networking server.</td>
</tr>
<tr>
<td>&GET;</td>
<td>/agents/<parameter>agent_id</parameter></td>
<td>Show information of the given agent.</td>
</tr>
<tr>
<td>&PUT;</td>
<td>/agents/<parameter>agent_id</parameter></td>
<td>Update the agent's admin status and description.</td>
</tr>
<tr>
<td>&DELETE;</td>
<td>/agents/<parameter>agent_id</parameter></td>
<td>Delete the given agent.</td>
</tr>
</tbody>
</informaltable>
<?hard-pagebreak?>
<section xml:id="List_Agents">
<title>List Agents</title>
<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>/agents</td>
<td>List agents which report their status to OpenStack Networking server.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>200</returnvalue>
</simpara>
<para>This operation does not require a request body.</para>
<para>This operation returns a response body.
The default policy behavior is that non-admin user
won't be able to see any agent in the response when this call is invoked</para>
<example>
<title>List Agents: JSON Request</title>
<programlisting>
GET /v2.0/agents HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: c52a1b304fec4ca0ac85dc1741eec6e2
</programlisting>
</example>
<example><title>List Agents: JSON Response</title>
<programlisting language="json"><xi:include href="samples/agents-list-res.json" parse="text"/></programlisting>
</example>
</section>
<?hard-pagebreak?>
<section xml:id="Show_Agent">
<title>Show Agent</title>
<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>/agents/<parameter>agent_id</parameter></td>
<td>Show information of the given agent.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>200</returnvalue>
</simpara>
<simpara>Error Response Codes:NotFound
(<errorcode>404</errorcode>) if not authorized or the agent does not exist</simpara>
<para>This operation returns information for the given agent.</para>
<para>This operation does not require a request
body.</para>
<para>This operation returns a response body. The body contents depend on the agent's type.</para>
<example>
<title>Show Agent: JSON Request</title>
<para>
<programlisting>
GET /v2.0/agents/af4567ad-c2e6-4311-944d-22efc12f89af HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: a54d6fdda41341f892150e2aaf648f0d
</programlisting>
</para>
</example>
<example>
<title>Show Agent: JSON Response</title>
<programlisting language="json"><xi:include href="samples/agents-show-res.json" parse="text"/></programlisting>
</example>
</section>
<?hard-pagebreak?>
<section xml:id="Update_Agent">
<title>Update Agent</title>
<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>/agents/<parameter>agent_id</parameter></td>
<td>Update the agent's admin status and description.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>200</returnvalue>
</simpara>
<simpara>Error Response Codes: BadRequest (<errorcode>400</errorcode>)
if something other than description or admin status is changed,
NotFound (<errorcode>404</errorcode>) if not authorized or the agent does not exist</simpara>
<para>This operation updates the agent's admin status and description.</para>
<para>This operation requires a request body.
</para>
<para>This operation returns a response body.</para>
<example>
<title>Update Agent: JSON Request</title>
<programlisting>
PUT /v2.0/agents/af4567ad-c2e6-4311-944d-22efc12f89af HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: 4cbb09e780434b249ff596d6979fd8fc
Content-Length: 38
<xi:include href="samples/agents-put-req.json" parse="text"/></programlisting>
</example>
<example>
<title>Update Agents: JSON Response</title>
<programlisting language="json"><xi:include href="samples/agents-put-res.json" parse="text"/></programlisting>
</example>
</section>
<?hard-pagebreak?>
<section xml:id="Delete_Agent">
<title>Delete Agent</title>
<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>/agents/<parameter>agent_id</parameter></td>
<td>Delete the given agent.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>204</returnvalue>
</simpara>
<simpara>Error Response Codes: NotFound
(<errorcode>404</errorcode>) if not authorized or the agent does not exist</simpara>
<para>This operation deletes the agent.</para>
<para>This operation does not require a request body.
</para>
<para>This operation does not return a response body.</para>
<example>
<title>Delete Agent: JSON Request</title>
<programlisting>
DELETE /v2.0/agents/44002aeb-2817-4cb8-9306-34308b4b40d9 HTTP/1.1
Host: controlnode:9696
User-Agent: python-neutronclient
Content-Type: application/json
Accept: application/json
X-Auth-Token: 4cbb09e780434b249ff596d6979fd8fc
</programlisting>
</example>
<example>
<title>Delete Agent: JSON Response</title>
<programlisting language="json"><xi:include href="samples/agents-delete-res.json" parse="text"/></programlisting>
</example>
</section>
</section>
View Git Blame Copy Permalink