From e6859ded3170580b2be692a3fbf320bb8d1eb567 Mon Sep 17 00:00:00 2001
From: Stephen Finucane <stephenfin@redhat.com>
Date: Tue, 23 Mar 2021 12:44:24 +0000
Subject: [PATCH] docs: Add docs for 'RateLimitingMiddleware'

Per bug #1662637, it seems this is a hangover from the forklift out of
nova and can probably be deprecated. From what I can tell, hasn't
happened yet though so at least acknowledge the existence of this
middleware.

Change-Id: I1d99d89dc782e697705cab05269821e8675e5fd8
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
Closes-Bug: #1662637
---
 doc/source/admin/api-configuration.rst | 78 ++++++++++++++++++++++++++
 doc/source/admin/index.rst             |  1 +
 doc/source/conf.py                     |  1 +
 3 files changed, 80 insertions(+)
 create mode 100644 doc/source/admin/api-configuration.rst

diff --git a/doc/source/admin/api-configuration.rst b/doc/source/admin/api-configuration.rst
new file mode 100644
index 00000000000..b9e3a901fe0
--- /dev/null
+++ b/doc/source/admin/api-configuration.rst
@@ -0,0 +1,78 @@
+=================
+API Configuration
+=================
+
+.. todo::
+
+   This needs to be expanded to include information on e.g. PasteDeploy.
+
+Rate limiting
+-------------
+
+.. warning::
+
+   This is legacy functionality that is poorly tested and may be removed in the
+   future. You may wish to enforce rate limiting through a proxy server
+   instead.
+
+Cinder supports admin-configured API limits. These are disabled by default but
+can be configured by modifying :file:`api-paste.ini` to enabled the
+``RateLimitingMiddleware`` middleware. For example, given the following
+composite application definitions in e.g. ``/etc/cinder/api-paste.ini``:
+
+.. code-block:: ini
+
+  [composite:openstack_volume_api_v2]
+  use = call:cinder.api.middleware.auth:pipeline_factory
+  noauth = cors ... apiv2
+  keystone = cors ... apiv2
+  keystone_nolimit = cors ... apiv2
+
+  [composite:openstack_volume_api_v3]
+  use = call:cinder.api.middleware.auth:pipeline_factory
+  noauth = cors ... apiv3
+  keystone = cors ... apiv3
+  keystone_nolimit = cors ... apiv3
+
+You can configure rate limiting by adding a new filter to call
+``RateLimitingMiddleware`` and configure the composite applications to use this
+filter:
+
+.. code-block:: ini
+
+  [composite:openstack_volume_api_v2]
+  use = call:cinder.api.middleware.auth:pipeline_factory
+  noauth = cors ... ratelimit apiv2
+  keystone = cors ... ratelimit apiv2
+  keystone_nolimit = cors ... ratelimit apiv2
+
+  [composite:openstack_volume_api_v3]
+  use = call:cinder.api.middleware.auth:pipeline_factory
+  noauth = cors ... ratelimit apiv3
+  keystone = cors ... ratelimit apiv3
+  keystone_nolimit = cors ... ratelimit apiv3
+
+  [filter:ratelimit]
+  paste.filter_factory = cinder.api.v2.limits:RateLimitingMiddleware.factory
+
+Once configured, restart the :program:`cinder-api` service. Users can then view
+API limits using the ``openstack limits show --rate`` command. For example:
+
+.. code-block:: bash
+
+   $ openstack limits show --rate
+   +--------+-----------------+-------+--------+--------+---------------------+
+   | Verb   | URI             | Value | Remain | Unit   | Next Available      |
+   +--------+-----------------+-------+--------+--------+---------------------+
+   | POST   | *               |    10 |     10 | MINUTE | 2021-03-23T12:36:09 |
+   | PUT    | *               |    10 |     10 | MINUTE | 2021-03-23T12:36:09 |
+   | DELETE | *               |   100 |    100 | MINUTE | 2021-03-23T12:36:09 |
+   | POST   | */servers       |    50 |     50 | DAY    | 2021-03-23T12:36:09 |
+   | GET    | *changes-since* |     3 |      3 | MINUTE | 2021-03-23T12:36:09 |
+   +--------+-----------------+-------+--------+--------+---------------------+
+
+.. note::
+
+   Rate limits are entirely separate from absolute limits, which track resource
+   utilization and can be seen using the ``openstack limits show --absolute``
+   command.
diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
index a88b29a428a..6b3bbe19b93 100644
--- a/doc/source/admin/index.rst
+++ b/doc/source/admin/index.rst
@@ -53,6 +53,7 @@ Amazon EC2 Elastic Block Storage (EBS) offering.
    blockstorage-volume-multiattach.rst
    blockstorage-volume-number-weigher.rst
    blockstorage-default-volume-types.rst
+   api-configuration
 
 .. _`Storage Decisions`: https://docs.openstack.org/arch-design/design-storage/design-storage-arch.html
 .. _`OpenStack Operations Guide`: https://wiki.openstack.org/wiki/OpsGuide
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 3821cb14e8d..c2ea48cf264 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -36,6 +36,7 @@ sys.path.insert(0, os.path.abspath('./'))
 # or your custom ones.
 
 extensions = ['sphinx.ext.coverage',
+              'sphinx.ext.todo',
               'sphinx.ext.graphviz',
               'sphinx_feature_classification.support_matrix',
               'openstackdocstheme',