Skip to content

Commit a4032b9

Browse files
Zuulopenstack-gerrit
Zuul
authored and
openstack-gerrit
committed
Merge "Add spec for rate limiting"
2 parents 71d41d7 + 0aef474 commit a4032b9

File tree

2 files changed

+244
-1
lines changed

2 files changed

+244
-1
lines changed

‎doc/source/contributor/index.rst

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,6 @@ Version 14.0 (caracal)
100100

101101
Version 15.0 (Dalmatian)
102102
````````````````````````
103-
104103
.. toctree::
105104
:glob:
106105
:maxdepth: 1

‎specs/version15.0/rate_limiting.rst

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
..
2+
This work is licensed under a Creative Commons Attribution 3.0 Unported
3+
License.
4+
5+
http://creativecommons.org/licenses/by/3.0/legalcode
6+
7+
============================================
8+
Support for traffic rate limiting in Octavia
9+
============================================
10+
Rate limiting is an essential technique for managing
11+
the traffic that is handled by
12+
a load balancer and for ensuring fairness and system stability.
13+
14+
Problem description
15+
===================
16+
Without rate limiting malicious clients and bots
17+
may be able to attack a server by flooding it with traffic or requests.
18+
Rate limiting can help to limit the amount of resources that
19+
single clients can allocate on server side and therefor
20+
can help to mitigate DoS attacks.
21+
22+
Octavia already allows to limit the number of concurrent connections
23+
by using the ``connection_limit`` option when configuring a listener. This
24+
option will continue to exist and will work independently of this new rate
25+
limiting feature.
26+
27+
Proposed change
28+
===============
29+
Both the data model and the REST API need to be extended.
30+
The concept of *rate limit policies* and *rate limit rules* allows to manage
31+
rules for rate limiting and to apply them to listeners. This document
32+
refers to them as policies and rules for simplicity.
33+
34+
A policy consists of one or more rules.
35+
Each policy defines an ``action`` that specifies the rate limiting method
36+
that should be used.
37+
Rules within a policy will be combined using a logical AND operation.
38+
That means all rules within a policy need to be broken before rate limiting
39+
gets applied. Multiple policies on a single listener logically OR
40+
each other.
41+
42+
Rate limiting can be implemented in various ways using different metrics for
43+
different protocols. Hence, this specification tries to be as flexible
44+
as possible while keeping the API simple. Drivers may choose to
45+
implement only a subset of the possible configuration variants,
46+
or even none of them.
47+
The algorithm used for rate limiting is considered an implementation detail
48+
of the driver and out of the scope of this document.
49+
50+
Alternatives
51+
------------
52+
Rate limiting for all request based protocols (HTTP protocols) could be
53+
done by extending the L7 policy API and by managing rules as L7 rules.
54+
55+
Rate limiting for all TCP based protocols could be supported
56+
and configured using the listener API.
57+
58+
Splitting the configuration between two different APIs may confuse users,
59+
however. Using a separate API for rate limiting seems like the cleaner
60+
approach.
61+
62+
Data model impact
63+
-----------------
64+
A new ``RateLimitPolicy`` model class contains data about policies.
65+
Its attributes are:
66+
67+
* ``id`` (string)
68+
* ``name`` (string)
69+
* ``description`` (string)
70+
* ``rules`` (``RateLimitRule``\s)
71+
* ``action`` (string)
72+
* ``listener_id`` (string)
73+
* ``listener`` (string)
74+
* ``enabled`` (boolean)
75+
* ``provisioning_status`` (string)
76+
* ``operating_status`` (string)
77+
* ``project_id`` (string)
78+
* ``created_at`` (DateTime)
79+
* ``updated_at`` (DateTime)
80+
* ``tags`` (string)
81+
82+
The ``rules`` attribute forms a
83+
one-to-many relationship with a new ``RateLimitRule`` model class.
84+
``action`` defines the rate limiting method.
85+
Possible values are
86+
``DENY`` (respond with HTTP 429),
87+
``REJECT`` (close the connection with no response),
88+
``SILENT_DROP`` (like ``REJECT``, but without client notification)
89+
``QUEUE`` (queue new requests, "leaky bucket") using a Python enum.
90+
The existing ``Listener`` model class gets a new
91+
one-to-may relationship with the
92+
``RateLimitPolicy`` model class using a new ``rate_limit_policies``
93+
attribute. That means a listener may have multiple policies, but a policy
94+
can be linked to only one listener.
95+
96+
The new ``RateLimitRule`` model class defines a specific
97+
rate limiting rule. Its attributes are:
98+
99+
* ``id`` (string)
100+
* ``name`` (string)
101+
* ``project_id`` (string)
102+
* ``metric`` (string)
103+
* ``threshold`` (integer)
104+
* ``interval`` (integer, defaults to 30)
105+
* ``urls`` (ScalarListType)
106+
* ``provisioning_status`` (string)
107+
* ``operating_status`` (string)
108+
* ``tags`` (string)
109+
110+
Possible values of ``metric`` are
111+
``REQUESTS`` ``REQUESTS_PER_URL``,
112+
``KBYTES`` and ``PACKETS``.
113+
``interval`` denotes the time interval in seconds in
114+
which the metric gets measured for each client.
115+
``threshold`` defines the threshold at which the rate gets limited.
116+
The ``urls`` field defines the URL paths for the specific rule and is
117+
ignored if ``metric`` is not ``REQUESTS_PER_URL``.
118+
119+
REST API impact
120+
---------------
121+
If not stated otherwise the attributes in the responses match with the
122+
ones in the data model. The relationships will be shown using IDs of
123+
related objects.
124+
125+
Listener
126+
~~~~~~~~
127+
The listener API gets a new ``rate_limit_policies`` (Optional) attribute.
128+
Valid values are ``null`` (the default) or a list of policy IDs.
129+
130+
Rate Limit Policy
131+
~~~~~~~~~~~~~~~~~
132+
The request of the ``POST /v2/lbaas/ratelimitpolicies``
133+
and ``PUT /v2/lbaas/ratelimitpolicies/{policy_id}`` methods of the
134+
``Rate Limit Policy`` API takes the attributes
135+
``name`` (Optional), ``description`` (Optional), ``listener_id``,
136+
``action``,
137+
``enabled`` (Optional), ``project_id`` (Optional), ``tags`` (Optional).
138+
The response contains all attributes in the data model.
139+
The ``GET /v2/lbaas/ratelimitpolicies`` method supports the attributes
140+
the ``project_id`` (Optional) and ``fields`` (Optional).
141+
The response is a list of policies filtered by the optional ``project_id``
142+
and containing the desired ``fields`` (or all).
143+
The endpoint ``/v2/lbaas/ratelimitpolicies/{policy_id}`` supports the
144+
``GET`` and ``DELETE`` methods.
145+
146+
Rate Limit Rule
147+
~~~~~~~~~~~~~~~
148+
The ``GET /v2/lbaas/ratelimitpolicies/{policy_id}/rules``
149+
method behaves like the GET method for the policy, but for rules.
150+
The ``POST /v2/lbaas/ratelimitpolicies/{policy_id}/rules`` method accepts
151+
the request attributes ``listener_id``,
152+
``project_id`` (Optional),
153+
``metric``, ``threshold``, ``interval`` (Optional), ``urls`` (Optional)
154+
``tags`` (Optional).
155+
The ``GET /v2/lbaas/ratelimitpolicies/{policy_id}/rules/{rule_id}`` request
156+
accepts an optional ``fields`` attribute.
157+
The ``PUT /v2/lbaas/ratelimitpolicies/{policy_id}/rules/{rule_id}``
158+
method accepts
159+
the request attributes `, ``project_id`` (Optional),
160+
``metric``, ``threshold``, ``interval`` (Optional), ``urls`` (Optional),
161+
``tags`` (Optional).
162+
The ``DELETE /v2/lbaas/ratelimitpolicies/{policy_id}/rules/{rule_id}``
163+
method has no response body.
164+
165+
Security impact
166+
---------------
167+
None.
168+
169+
Notifications impact
170+
--------------------
171+
None.
172+
173+
Other end user impact
174+
---------------------
175+
None.
176+
177+
Performance Impact
178+
------------------
179+
Rate limiting is an optional feature and has no performance impact in a
180+
default configuration. Depending on the complexity of the rules and the
181+
implementation, some processing overhead may impact performance. In the
182+
ACTIVE/STANDBY topology some additional network overhead for synchronization
183+
of request statistics (ie. stick tables for Amphorae) is to be expected.
184+
185+
Overall,
186+
however, fairness and performance can improve when using rate limiting.
187+
188+
Other deployer impact
189+
---------------------
190+
Deployers might want to review the RAM setting of the Nova flavor
191+
that is used for the load balancers. Rate limiting will require some
192+
additional memory on Amphorae, depending on the number of rules and
193+
the interval setting.
194+
195+
Developer impact
196+
----------------
197+
Driver developers are impacted by the extended API and data model that allows
198+
them to implement the new feature in future versions.
199+
200+
Implementation
201+
==============
202+
The reference implementation using the Amphora driver will use HAProxy's own
203+
rate limiting capabilities. In addition to limiting the number of
204+
HTTP requests it will also be possible to limit the number of HTTP requests
205+
by URL path [#haproxy-url-path]_.
206+
The sliding window rate limiting algorithm will be
207+
used [#haproxy-four-examples]_.
208+
209+
Rate limiting based on the TCP protocol is not part of the
210+
initial implementation, but might be added in a future version.
211+
This could be done using ``nftables`` rules [#nftables]_.
212+
213+
Assignee(s)
214+
-----------
215+
Primary assignee:
216+
Tom Weininger
217+
218+
Work Items
219+
----------
220+
#. Adjust API documentation
221+
#. Create user documentation
222+
#. Implement HTTP rate limiting in Amphora driver
223+
#. Implement HTTP by URL rate limiting in Amphora driver
224+
#. Implement unit tests
225+
226+
Dependencies
227+
============
228+
None.
229+
230+
Testing
231+
=======
232+
Testing should focus on API changes, verification and correctness of
233+
generated HAProxy configuration.
234+
235+
Documentation Impact
236+
====================
237+
API and user documentation will need to be extended.
238+
239+
References
240+
==========
241+
242+
.. [#haproxy-four-examples] https://www.haproxy.com/blog/four-examples-of-haproxy-rate-limiting
243+
.. [#nftables] https://wiki.nftables.org/wiki-nftables/index.php/Meters
244+
.. [#haproxy-url-path] https://www.haproxy.com/documentation/haproxy-configuration-tutorials/traffic-policing/#rate-limit-http-requests-by-url-path

0 commit comments

Comments
 (0)