From e6859ded3170580b2be692a3fbf320bb8d1eb567 Mon Sep 17 00:00:00 2001 From: Stephen Finucane 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 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',