cloudstack-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From t..@apache.org
Subject [39/50] [abbrv] git commit: refs/heads/bvt - Docs. CLOUDSTACK-866. Add section on API request throttling. Included in Admin Guide and Developer's Guide.
Date Sat, 23 Mar 2013 12:31:19 GMT
Docs. CLOUDSTACK-866. Add section on API request throttling. Included in Admin Guide and Developer's
Guide.


Project: http://git-wip-us.apache.org/repos/asf/cloudstack/repo
Commit: http://git-wip-us.apache.org/repos/asf/cloudstack/commit/976a5fa7
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack/tree/976a5fa7
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack/diff/976a5fa7

Branch: refs/heads/bvt
Commit: 976a5fa788863cd955b279ae571c88c9f0ed1e18
Parents: 33937c9
Author: Jessica Tomechak <jessica.tomechak@gmail.com>
Authored: Thu Mar 21 19:05:07 2013 -0700
Committer: Jessica Tomechak <jessica.tomechak@gmail.com>
Committed: Thu Mar 21 20:00:34 2013 -0700

----------------------------------------------------------------------
 docs/en-US/api-calls.xml              |    3 +-
 docs/en-US/api-throttling.xml         |   67 ++++++++++++++++++++++++++++
 docs/en-US/sys-reliability-and-ha.xml |    3 +-
 3 files changed, 71 insertions(+), 2 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cloudstack/blob/976a5fa7/docs/en-US/api-calls.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/api-calls.xml b/docs/en-US/api-calls.xml
index 3b97893..af4073a 100644
--- a/docs/en-US/api-calls.xml
+++ b/docs/en-US/api-calls.xml
@@ -25,8 +25,9 @@
 <chapter id="api-calls">
     <title>Calling the &PRODUCT; API</title>
     <xi:include href="making-api-request.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
-    <xi:include href="enabling-api-call-expiration.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
     <xi:include href="signing-api-requests.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+    <xi:include href="enabling-api-call-expiration.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+    <xi:include href="api-throttling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href="responses.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href="asynchronous-commands.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
 </chapter>

http://git-wip-us.apache.org/repos/asf/cloudstack/blob/976a5fa7/docs/en-US/api-throttling.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/api-throttling.xml b/docs/en-US/api-throttling.xml
new file mode 100644
index 0000000..908e223
--- /dev/null
+++ b/docs/en-US/api-throttling.xml
@@ -0,0 +1,67 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="api-throttling">
+  <title>Limiting the Rate of API Requests</title>
+  <para>You can limit the rate at which API requests can be placed for each
+    account. This is useful to avoid malicious attacks on the Management Server, prevent
+    performance degradation, and provide fairness to all accounts.</para>
+  <para>If the number of API calls exceeds the threshold, an error message is returned
for any additional API calls.
+    The caller will have to retry these API calls at another time.</para>
+  <section id="api-throttling-configure">
+    <title>Configuring the API Request Rate</title>
+    <para>To control the API request rate, use the following global configuration
+      settings:</para>
+    <itemizedlist>
+      <listitem><para>api.throttling.enabled - Enable/Disable API throttling.
By default, this setting is false, so
+        API throttling is not enabled.</para></listitem>
+      <listitem><para>api.throttling.interval (in seconds) - Time interval during
which the number of API requests is to be counted.
+        When the interval has passed, the API count is reset to 0.</para></listitem>
+      <listitem><para>api.throttling.max - Maximum number of APIs that can be
placed within the api.throttling.interval period.</para></listitem>
+      <listitem><para>api.throttling.cachesize - Cache size for storing API counters.
+        Use a value higher than the total number of accounts managed by the cloud.
+        One cache entry is needed for each account, to store the running API total for that
account.
+      </para></listitem>
+    </itemizedlist>
+  </section>
+  <section id="api-throttling-limitations">
+    <title>Limitations on API Throttling</title>
+    <para>The following limitations exist in the current implementation of this feature.</para>
+    <note><para>Even with these limitations, &PRODUCT; is still able to effectively
use API throttling to
+      avoid malicious attacks causing denial of service.</para></note>
+    <para/>
+    <itemizedlist>
+      <listitem><para>In a deployment with multiple Management Servers,
+        the cache is not synchronized across them.
+        In this case, &PRODUCT; might not be able to
+        ensure that only the exact desired number of API requests are allowed.
+        In the worst case, the number of API calls that might be allowed is
+        (number of Management Servers) * (api.throttling.max).
+      </para></listitem>
+      <listitem><para>The API commands resetApiLimit and getApiLimit are limited
to the
+        Management Server where the API is invoked.
+      </para></listitem>
+    </itemizedlist>        
+  </section>
+</section>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/cloudstack/blob/976a5fa7/docs/en-US/sys-reliability-and-ha.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/sys-reliability-and-ha.xml b/docs/en-US/sys-reliability-and-ha.xml
index 94385ff..3d6ebe1 100644
--- a/docs/en-US/sys-reliability-and-ha.xml
+++ b/docs/en-US/sys-reliability-and-ha.xml
@@ -28,5 +28,6 @@
     <xi:include href="ha-enabled-vm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

     <xi:include href="ha-for-hosts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href="primary-storage-outage-and-data-loss.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>     
-    <xi:include href="secondary-storage-outage-and-data-loss.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/> 
+    <xi:include href="secondary-storage-outage-and-data-loss.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+    <xi:include href="api-throttling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 </chapter>


Mime
View raw message