openstack/glance
Code Issues Proposed changes

Add unified quotas documentation

Browse Source 
Related to blueprint glance-unified-quotas

Change-Id: I59d0b48f0652120eaae39509685345a12447933e
This commit is contained in:
Dan Smith 2021-06-03 12:23:49 -07:00
parent 8d6ee6f822
commit da771fce25
11 changed files with 336 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/admin/index.rst
View File

@ -24,3 +24,4 @@ Glance Administration Guide
manage-images
useful-image-properties
requirements
quotas

158
doc/source/admin/quotas.rst Normal file
View File

@ -0,0 +1,158 @@
..
Copyright 2021 Red Hat, Inc.
Licensed 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.
.. _quotas:
Per-Tenant Quotas
=================
Glance supports resource consumption quotas on tenants through the use
of Keystone's unified limits functionality. Resource limits are
*registered* in Keystone with suitable default values, and may be
overridden on a per-tenant basis. When a resource consumption attempt
is made in Glance, the current consumption is computed and compared
against the limit set in Keystone; the request is denied if the user
is over the specified limit.
Due to the design of Glance, most of the storage-focused quotas in
Glance are **soft limits**. Since Glance allows clients to stream image
data of unknown total size during an upload or import operation, it is
not possible to determine if quota has been exceeded until *after* the
operation has completed. Thus, a user is permitted to go over their
quota for a single operation, and then denied additional stored on
subsequent operations. There are object-focused quotas that can help
operators limit the damage caused by multiple large competing data
streams. Those details are covered below.
.. note::
Glance also has legacy global resource limits that may be ignored if
per-tenant quotas are enabled. Currently the ``user_storage_quota``
limit will be ignored if per-tenant quotas are used.
See the Keystone docs for more information on `unified limits
<https://docs.openstack.org/keystone/latest/admin/unified-limits.html>`_.
Quota Resource Types
--------------------
Glance supports quota limits on multiple areas of resource
consumption. Limits are enforced at the time in which resource
consumption is attempted, so setting an existing user's quota for any
item below the current usage will only prevent them from consuming
*more* data until they free up space.
Total Image Size
~~~~~~~~~~~~~~~~
The ``image_size_total`` limit defines the maximum amount of storage
(in MiB) that the tenant may consume across all of their active
images. Images with multiple locations contribute to this count
according to the number of places the image is stored. Thus, if you
have a single 1GiB image stored in four locations, the usage will be
considered to be 4GiB.
Total Staging Size
~~~~~~~~~~~~~~~~~~
The :ref:`iir` function uses a two-step upload
process, whereby a user first uploads an image into the *staging*
store, and then subsequently *imports* the image to the final
destination(s). The staging store is generally local storage on the
API workers themselves, and thus is likely at somewhat of a premium,
compared to the bulk shared storage allocated for general images. The
``image_stage_total`` limit defines the total amount of staging space
that may be used. This should be set to a value sufficient to allow
a user to import one or more images at the same time, according to
your desired level of parallelism. It may be appropriate to provide
the user with a very generous ``image_size_total`` quota, but a
relatively restrictive ``image_stage_total`` allocation, effectively
limiting them to one image being imported at any given point.
Keep in mind that images being imported using the ``web-download``
method will need to fit within this allocation as well, as those are
first downloaded to the staging store before being imported to the
final destination(s). Images being copied from one store to another
using the ``copy-image`` method are similarly affected. Note that the
conventional image upload method does not stage the image, and thus is
not impacted by this limit.
Total Number of Images
~~~~~~~~~~~~~~~~~~~~~~
The ``image_count_total`` limit controls the maximum number of image
objects that the user may have, regardless of the individual or
collective sizes or impact to storage. This limit may be useful if you
wish to prevent users from taking thousands of small server snapshots
without ever deleting them.
Total Number of In-Progress Uploads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Because Glance can not enforce storage-focused quotas until after a
stream is finished, it may be useful to limit the number of parallel
upload operations that can be in-progress at any single point. The
``image_count_uploading`` limit provides this control, and affects
conventional image upload, pre-import stage (including
``web-download`` and ``glance-direct``), as well as any ``copy-image``
operations that may be pending. It may be desirable to limit untrusted
users to a single in-progress image upload, which will limit the
amount of damage a malicious user may be able to inflict on your image
storage if they initiate multiple simultaneous unbounded upload
streams.
Quota Strategies
----------------
Below are a couple of use-case example strategies for different types
of deployments. In all cases, it makes sense for ``image_size_total``
and ``image_stage_total`` to be set to at least the size of the
largest image you expect a user to use. The global limit on a single
image (see configuration item ``image_size_cap``) may be relevant as
well. Users with an ``image_count_total`` of zero will be unable to
create any images, and with an ``image_count_uploading`` of zero will
be able to upload data to any images.
#. **Public cloud, users are billed per-byte**: In this case, it
probably makes sense to set fairly high default quota limits for
each of the above resource classes, allowing users to consume as
much as they are willing to pay for. It still may be desirable to
set ``image_stage_total`` to something modest to prevent
overrunning limited staging space, if you have import enabled.
#. **Private cloud, trusted users are billed by quota**: In this case,
each user pays for the amount of resource they are *allowed* to
consume, instead of what they *are* consuming. Generally this
involves billing total space, so ``image_size_total`` is set to
their allotment, potentially with some upper bound on total images
via ``image_count_total``. If they are somewhat trusted or
low-impact customers, limiting the staging usage and upload count
is probably not necessary, and can be left unbounded or set to some
high upper bound.
#. **Private cloud, semi-trusted third party users**: This case may be
similar to either of the above in terms of paying for allotment or
strict usage. However, the lack of full trust may suggest limiting
the total number of image uploads to something like 10% of their
compute quota (to allow for snapshots) and limiting staging usage
to enough for one or two image imports at a time.
Configuring Glance for Per-Tenant Quotas
----------------------------------------
.. include:: ../install/register-quotas.rst
#. Tell Glance to use Keystone quotas
.. include:: ../install/configure-quotas.rst

19
doc/source/configuration/configuring.rst
View File

@ -1346,6 +1346,13 @@ Configuring Glance User Storage Quota
The following configuration option is specified in the
``glance-api.conf`` configuration file in the section ``[DEFAULT]``.
.. note::
As of the Xena release, Glance supports :ref:`per-tenant <config-per-tenant-quotas>`
quotas with more granularity than the global limit provided by this
option. You may want to enable per-tenant quotas and leave this
unset.
``user_storage_quota``
Optional. Default: 0 (Unlimited).
@ -1357,6 +1364,18 @@ The following configuration option is specified in the
Example values would be,
user_storage_quota=20GB
.. _config-per-tenant-quotas:
Configuring Glance Per-Tenant Quotas
------------------------------------
Glance can utilize per-tenant resource limits set in Keystone to
enforce quotas on users. These limits must be registered with defaults
in Keystone, with optional per-tenant overrides, prior to enabling
them in Glance. To instruct glance to use limits in Keystone, set
``[DEFAULT]/use_keystone_limits=True`` in ``glance-api.conf``.
Configuring the Image Cache
---------------------------

41
doc/source/install/configure-quotas.rst Normal file
View File

@ -0,0 +1,41 @@
* In the ``[oslo_limit]`` section, configure access to keystone:
.. code-block:: ini
[oslo_limit]
auth_url = http://controller:5000
auth_type = password
user_domain_id = default
username = MY_SERVICE
system_scope = all
password = MY_PASSWORD
endpoint_id = ENDPOINT_ID
region_name = RegionOne
.. end
Make sure that the MY_SERVICE account has reader access to
system-scope resources (like limits):
.. code-block:: console
$ openstack role add --user MY_SERVICE --user-domain Default --system all reader
.. end
See `the oslo_limit docs
<https://docs.openstack.org/oslo.limit/latest/user/usage.html#configuration>`_
for more information about configuring the unified limits client.
* In the ``[DEFAULT]`` section, optionally enable per-tenant quotas:
.. path /etc/glance/glance.conf
.. code-block:: ini
[DEFAULT]
use_keystone_quotas = True
.. end
Note that you must have created the registered limits as
described above if this is enabled.

4
doc/source/install/install-debian.rst
View File

@ -166,6 +166,8 @@ create a database, service credentials, and API endpoints.
.. end
.. include:: register-quotas.rst
Install and configure components
--------------------------------
@ -247,6 +249,8 @@ Install and configure components
.. end
.. include:: configure-quotas.rst
3. Populate the Image service database:
.. code-block:: console

4
doc/source/install/install-obs.rst
View File

@ -166,6 +166,8 @@ create a database, service credentials, and API endpoints.
.. end
.. include:: register-quotas.rst
Install and configure components
--------------------------------
@ -258,6 +260,8 @@ Install and configure components
.. end
.. include:: configure-quotas.rst
Finalize installation
---------------------

3
doc/source/install/install-rdo.rst
View File

@ -166,6 +166,8 @@ create a database, service credentials, and API endpoints.
.. end
.. include:: register-quotas.rst
Install and configure components
--------------------------------
@ -247,6 +249,7 @@ Install and configure components
.. end
.. include:: configure-quotas.rst
3. Populate the Image service database:

4
doc/source/install/install-ubuntu.rst
View File

@ -166,6 +166,8 @@ create a database, service credentials, and API endpoints.
.. end
.. include:: register-quotas.rst
Install and configure components
--------------------------------
@ -247,6 +249,8 @@ Install and configure components
.. end
.. include:: configure-quotas.rst
3. Populate the Image service database:
.. code-block:: console

66
doc/source/install/register-quotas.rst Normal file
View File

@ -0,0 +1,66 @@
#. Register quota limits (optional):
If you decide to use per-tenant quotas in Glance, you must register
the limits in Keystone first:
.. code-block:: console
$ openstack --os-cloud devstack-system-admin registered limit create \
--service glance --default-limit 1000 --region RegionOne image_size_total
+---------------+----------------------------------+
| Field | Value |
+---------------+----------------------------------+
| default_limit | 1000 |
| description | None |
| id | 9cedfc5de80345a9b13ed00c2b5460f2 |
| region_id | RegionOne |
| resource_name | image_size_total |
| service_id | e38c84a2487f49fd9864193bdc8a3174 |
+---------------+----------------------------------+
$ openstack --os-cloud devstack-system-admin registered limit create \
--service glance --default-limit 1000 --region RegionOne image_stage_total
+---------------+----------------------------------+
| Field | Value |
+---------------+----------------------------------+
| default_limit | 1000 |
| description | None |
| id | 5a68712b6ba6496d823d0c66e5e860b9 |
| region_id | RegionOne |
| resource_name | image_stage_total |
| service_id | e38c84a2487f49fd9864193bdc8a3174 |
+---------------+----------------------------------+
$ openstack --os-cloud devstack-system-admin registered limit create \
--service glance --default-limit 100 --region RegionOne image_count_total
+---------------+----------------------------------+
| Field | Value |
+---------------+----------------------------------+
| default_limit | 100 |
| description | None |
| id | beb91b043296499f8e6268f29d8b2749 |
| region_id | RegionOne |
| resource_name | image_count_total |
| service_id | e38c84a2487f49fd9864193bdc8a3174 |
+---------------+----------------------------------+
$ openstack --os-cloud devstack-system-admin registered limit create \
--service glance --default-limit 100 --region RegionOne image_count_uploading
+---------------+----------------------------------+
| Field | Value |
+---------------+----------------------------------+
| default_limit | 100 |
| description | None |
| id | fc29649c047a45bf9bc03ec4a7bcb8af |
| region_id | RegionOne |
| resource_name | image_count_uploading |
| service_id | e38c84a2487f49fd9864193bdc8a3174 |
+---------------+----------------------------------+
.. end
Be sure to also set ``use_keystone_quotas=True`` in your ``glance-api.conf`` file.

28
doc/source/user/glanceapi.rst
View File

@ -769,6 +769,34 @@ New API Calls
where <STATUS_VALUE> is ``pending``, ``accepted``, or ``rejected``.
The {memberId} is the project ID of the image member.
Resource Limits
---------------
A user should always expect that an HTTP 413 error could result from
any operation, indicating that a resource consumption limit has been
exceeded. Some of the common situations are detailed below:
* Creating an image: If your administrator has limited the total
number of images that you can have, an image create may fail. Delete
another image to proceed.
* Uploading data to an image: If you have exceeded the total amount of
image storage space allocated to you, then an upload may be
rejected. To proceed, delete another image of sufficient
size. Images with multiple locations count multiple times against
your quota, so deleting a location may also free up space. There is
also a quota on the number of upload operations (staging, copying,
and uploading all count against this) so you may need to wait for
other operations to complete before proceeding.
* Staging data for an image: There is a separate quota on the amount
of data you may have staged at any given point. To proceed, finish
importing other images first or delete an image with staged data.
* Importing an image: If importing an image from staging to its final
destination would overrun your total image storage quota, then the
import may fail. To proceed, delete other images to make space.
Of course, in all over-limit situations, requesting more quota from
your administrator may be an option.
Images v2 Stores API
--------------------

8
releasenotes/notes/glance-unified-quotas-fba62fabb00379af.yaml Normal file
View File

@ -0,0 +1,8 @@
---
features:
- |
Glance now has per-tenant quota support based on Keystone unified
limits for resources like image and staging storage, among other
things. For more information about how to configure and use these
quotas, refer to the relevant section of the `Administrator Guide
<https://docs.openstack.org/glance/latest/admin/quotas.html>`_.