f9cdba79aa
Docs on a plane returns. A cohort of small changes, reducing cruft and improving clarity of these common sections. Change-Id: I11c0ee83f4b2805304bb2e84e548c0a6aeaa135e
167 lines
7.6 KiB
XML
167 lines
7.6 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<section 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"
|
|
xml:id="configuring-compute-API">
|
|
<title>Configuring the Compute API</title>
|
|
<para>The Compute API, run by the
|
|
<systemitem class="service">nova-api</systemitem>
|
|
daemon, is the component of OpenStack Compute that
|
|
receives and responds to user requests, whether they
|
|
be direct API calls, or via the CLI tools or dashboard.</para>
|
|
<simplesect>
|
|
<title>Configuring Compute API password handling</title>
|
|
<para>The OpenStack Compute API allows the user to specify an
|
|
admin password when creating (or rebuilding) a server
|
|
instance. If no password is specified, a randomly generated
|
|
password is used. The password is returned in the API
|
|
response.</para>
|
|
<para>In practice, the handling of the admin password depends on
|
|
the hypervisor in use, and may require additional
|
|
configuration of the instance, such as installing an agent to
|
|
handle the password setting. If the hypervisor and instance
|
|
configuration do not support the setting of a password at
|
|
server create time, then the password returned by the create
|
|
API call will be misleading, since it was ignored.</para>
|
|
<para>To prevent this confusion, the configuration option
|
|
<literal>enable_instance_password</literal> can be used to
|
|
disable the return of the admin password for installations
|
|
that don't support setting instance passwords.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Configuring Compute API Rate Limiting</title>
|
|
<para>OpenStack Compute supports API rate limiting for the
|
|
OpenStack API. The rate limiting allows an administrator to
|
|
configure limits on the type and number of API calls that can
|
|
be made in a specific time interval.</para>
|
|
<para>When API rate limits are exceeded, HTTP requests will
|
|
return a error with a status code of 413 "Request entity too
|
|
large", and will also include a 'Retry-After' HTTP header. The
|
|
response body will include the error details, and the delay
|
|
before the request should be retried.</para>
|
|
<para>Rate limiting is not available for the EC2 API.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Specifying Limits</title>
|
|
<para>Limits are specified using five values:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The <emphasis role="bold">HTTP method</emphasis> used
|
|
in the API call, typically one of GET, PUT, POST, or
|
|
DELETE.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>A <emphasis role="bold">human readable URI</emphasis>
|
|
that is used as a friendly description of where the limit
|
|
is applied.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>A <emphasis role="bold">regular expression</emphasis>.
|
|
The limit will be applied to all URI's that match the
|
|
regular expression and HTTP Method.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>A <emphasis role="bold">limit value </emphasis> that
|
|
specifies the maximum count of units before the limit
|
|
takes effect.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>An <emphasis role="bold">interval</emphasis> that
|
|
specifies time frame the limit is applied to. The interval
|
|
can be SECOND, MINUTE, HOUR, or DAY.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>Rate limits are applied in order, relative to the HTTP
|
|
method, going from least to most specific. For example,
|
|
although the default threshold for POST to */servers is 50 per
|
|
day, one cannot POST to */servers more than 10 times within a
|
|
single minute because the rate limits for any POST is
|
|
10/min.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Default Limits</title>
|
|
<para>OpenStack compute is normally installed with the following
|
|
limits enabled:</para>
|
|
<table rules="all">
|
|
<caption>Default API Rate Limits</caption>
|
|
<thead>
|
|
<tr>
|
|
<td>HTTP method</td>
|
|
<td>API URI</td>
|
|
<td>API regular expression</td>
|
|
<td>Limit</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>POST</td>
|
|
<td>any URI (*)</td>
|
|
<td>.*</td>
|
|
<td>10 per minute</td>
|
|
</tr>
|
|
<tr>
|
|
<td>POST</td>
|
|
<td>/servers</td>
|
|
<td>^/servers</td>
|
|
<td>50 per day</td>
|
|
</tr>
|
|
<tr>
|
|
<td>PUT</td>
|
|
<td>any URI (*)</td>
|
|
<td>.*</td>
|
|
<td>10 per minute</td>
|
|
</tr>
|
|
<tr>
|
|
<td>GET</td>
|
|
<td>*changes-since*</td>
|
|
<td>.*changes-since.*</td>
|
|
<td>3 per minute</td>
|
|
</tr>
|
|
<tr>
|
|
<td>DELETE</td>
|
|
<td>any URI (*)</td>
|
|
<td>.*</td>
|
|
<td>100 per minute</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Configuring and Changing Limits</title>
|
|
<para>The actual limits are specified in the file
|
|
<filename>etc/nova/api-paste.ini</filename>, as part of the
|
|
WSGI pipeline.</para>
|
|
<para>To enable limits, ensure the
|
|
'<literal>ratelimit</literal>' filter is included in the API
|
|
pipeline specification. If the '<literal>ratelimit</literal>'
|
|
filter is removed from the pipeline, limiting will be
|
|
disabled. There should also be a definition for the rate limit
|
|
filter. The lines will appear as follows:</para>
|
|
<programlisting language="ini">
|
|
[pipeline:openstack_compute_api_v2]
|
|
pipeline = faultwrap authtoken keystonecontext ratelimit osapi_compute_app_v2
|
|
|
|
[pipeline:openstack_volume_api_v1]
|
|
pipeline = faultwrap authtoken keystonecontext ratelimit osapi_volume_app_v1
|
|
|
|
[filter:ratelimit]
|
|
paste.filter_factory = nova.api.openstack.compute.limits:RateLimitingMiddleware.factory
|
|
</programlisting>
|
|
<para>To modify the limits, add a '<literal>limits</literal>'
|
|
specification to the <literal>[filter:ratelimit]</literal>
|
|
section of the file. The limits are specified in the order
|
|
HTTP method, friendly URI, regex, limit, and interval. The
|
|
following example specifies the default rate limiting
|
|
values:</para>
|
|
<programlisting language="ini">
|
|
[filter:ratelimit]
|
|
paste.filter_factory = nova.api.openstack.compute.limits:RateLimitingMiddleware.factory
|
|
limits =(POST, "*", .*, 10, MINUTE);(POST, "*/servers", ^/servers, 50, DAY);(PUT, "*", .*, 10, MINUTE);(GET, "*changes-since*", .*changes-since.*, 3, MINUTE);(DELETE, "*", .*, 100, MINUTE)
|
|
</programlisting>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>List of configuration options for Compute API</title>
|
|
<xi:include href="tables/nova-api.xml"/>
|
|
</simplesect>
|
|
</section>
|