diff --git a/doc/source/_extra/.htaccess b/doc/source/_extra/.htaccess index a06ebeb3a4bb..1332e6bba23a 100644 --- a/doc/source/_extra/.htaccess +++ b/doc/source/_extra/.htaccess @@ -1,6 +1,7 @@ redirectmatch 301 ^/nova/([^/]+)/addmethod.openstackapi.html$ /nova/$1/contributor/api-2.html redirectmatch 301 ^/nova/([^/]+)/admin/flavors2.html$ /nova/$1/admin/flavors.html redirectmatch 301 ^/nova/([^/]+)/admin/numa.html$ /nova/$1/admin/cpu-topologies.html +redirectmatch 301 ^/nova/([^/]+)/admin/quotas2.html$ /nova/$1/admin/quotas.html redirectmatch 301 ^/nova/([^/]+)/aggregates.html$ /nova/$1/user/aggregates.html redirectmatch 301 ^/nova/([^/]+)/api_microversion_dev.html$ /nova/$1/contributor/microversions.html redirectmatch 301 ^/nova/([^/]+)/api_microversion_history.html$ /nova/$1/reference/api-microversion-history.html diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 7609ee6aeb37..bf0c85726327 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -151,7 +151,6 @@ Additional guides migrate-instance-with-snapshot networking-nova networking - quotas2 quotas security-groups security diff --git a/doc/source/admin/quotas.rst b/doc/source/admin/quotas.rst index 94fa1313e60b..c8000b3ba28c 100644 --- a/doc/source/admin/quotas.rst +++ b/doc/source/admin/quotas.rst @@ -1,371 +1,370 @@ -============================= -Manage Compute service quotas -============================= - -As an administrative user, you can use the :command:`nova quota-*` commands, -which are provided by the ``python-novaclient`` package, to update the Compute -service quotas for a specific project or project user, as well as update the -quota defaults for a new project. - -.. rubric:: Compute quota descriptions - -.. list-table:: - :header-rows: 1 - :widths: 10 40 - - * - Quota name - - Description - * - cores - - Number of instance cores (VCPUs) allowed per project. - * - instances - - Number of instances allowed per project. - * - key_pairs - - Number of key pairs allowed per user. - * - metadata_items - - Number of metadata items allowed per instance. - * - ram - - Megabytes of instance ram allowed per project. - * - server_groups - - Number of server groups per project. - * - server_group_members - - Number of servers per server group. - -The following quotas were previously available but were removed in microversion -2.36 as they proxied information available from the networking service. - -.. list-table:: - :header-rows: 1 - :widths: 10 40 - - * - Quota name - - Description - * - fixed_ips - - Number of fixed IP addresses allowed per project. This number - must be equal to or greater than the number of allowed - instances. - * - floating_ips - - Number of floating IP addresses allowed per project. - * - networks - - Number of networks allowed per project (nova-network only). - * - security_groups - - Number of security groups per project. - * - security_group_rules - - Number of security group rules per project. - -Similarly, the following quotas were previously available but were removed in -microversion 2.57 as the personality files feature was deprecated. - -.. list-table:: - :header-rows: 1 - :widths: 10 40 - - * - Quota name - - Description - * - injected_files - - Number of injected files allowed per project. - * - injected_file_content_bytes - - Number of content bytes allowed per injected file. - * - injected_file_path_bytes - - Length of injected file path. - -View and update Compute quotas for a project -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To view and update default quota values ---------------------------------------- - -#. List all default quotas for all projects: - - .. code-block:: console - - $ openstack quota show --default - +----------------------+----------+ - | Field | Value | - +----------------------+----------+ - | backup-gigabytes | 1000 | - | backups | 10 | - | cores | 20 | - | fixed-ips | -1 | - | floating-ips | 50 | - | gigabytes | 1000 | - | health_monitors | None | - | injected-file-size | 10240 | - | injected-files | 5 | - | injected-path-size | 255 | - | instances | 10 | - | key-pairs | 100 | - | l7_policies | None | - | listeners | None | - | load_balancers | None | - | location | None | - | name | None | - | networks | 10 | - | per-volume-gigabytes | -1 | - | pools | None | - | ports | 50 | - | project | None | - | project_name | project | - | properties | 128 | - | ram | 51200 | - | rbac_policies | 10 | - | routers | 10 | - | secgroup-rules | 100 | - | secgroups | 10 | - | server-group-members | 10 | - | server-groups | 10 | - | snapshots | 10 | - | subnet_pools | -1 | - | subnets | 10 | - | volumes | 10 | - +----------------------+----------+ - - .. note:: - - This lists default quotas for all services and not just nova. - -#. Update a default value for a new project, for example: - - .. code-block:: console - - $ openstack quota set --instances 15 --class default - -To view quota values for an existing project --------------------------------------------- - -#. List the currently set quota values for a project: - - .. code-block:: console - - $ openstack quota show PROJECT_NAME - +----------------------+----------------------------------+ - | Field | Value | - +----------------------+----------------------------------+ - | backup-gigabytes | 1000 | - | backups | 10 | - | cores | 32 | - | fixed-ips | -1 | - | floating-ips | 10 | - | gigabytes | 1000 | - | health_monitors | None | - | injected-file-size | 10240 | - | injected-files | 5 | - | injected-path-size | 255 | - | instances | 10 | - | key-pairs | 100 | - | l7_policies | None | - | listeners | None | - | load_balancers | None | - | location | None | - | name | None | - | networks | 20 | - | per-volume-gigabytes | -1 | - | pools | None | - | ports | 60 | - | project | c8156b55ec3b486193e73d2974196993 | - | project_name | project | - | properties | 128 | - | ram | 65536 | - | rbac_policies | 10 | - | routers | 10 | - | secgroup-rules | 50 | - | secgroups | 50 | - | server-group-members | 10 | - | server-groups | 10 | - | snapshots | 10 | - | subnet_pools | -1 | - | subnets | 20 | - | volumes | 10 | - +----------------------+----------------------------------+ - - .. note:: - - This lists quotas for all services and not just nova. - - -To update quota values for an existing project ----------------------------------------------- - -#. Obtain the project ID. - - .. code-block:: console - - $ project=$(openstack project show -f value -c id PROJECT_NAME) - -#. Update a particular quota value. - - To update quotas for a project: - - .. code-block:: console - - $ openstack quota set --QUOTA_NAME QUOTA_VALUE PROJECT_NAME - - To update quotas for a class: - - .. code-block:: console - - $ openstack quota set --class --QUOTA_NAME QUOTA_VALUE CLASS_NAME - - .. note:: - - Only the ``default`` class is supported by nova. - - For example: - - .. code-block:: console - - $ openstack quota set --instances 50 PROJECT_NAME - $ openstack quota show PROJECT_NAME - +----------------------+----------------------------------+ - | Field | Value | - +----------------------+----------------------------------+ - | ... | ... | - | instances | 50 | - | ... | ... | - +----------------------+----------------------------------+ - - .. note:: - - To view a list of options for the :command:`openstack quota set` command, - run: - - .. code-block:: console - - $ openstack help quota set - -View and update Compute quotas for a project user -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To view quota values for a project user ---------------------------------------- - -#. Place the user ID in a usable variable. - - .. code-block:: console - - $ projectUser=$(openstack user show -f value -c id USER_NAME) - -#. Place the user's project ID in a usable variable, as follows: - - .. code-block:: console - - $ project=$(openstack project show -f value -c id PROJECT_NAME) - -#. List the currently set quota values for a project user. - - .. code-block:: console - - $ nova quota-show --user $projectUser --tenant $project - - For example: - - .. code-block:: console - - $ nova quota-show --user $projectUser --tenant $project - +-----------------------------+-------+ - | Quota | Limit | - +-----------------------------+-------+ - | instances | 10 | - | cores | 20 | - | ram | 51200 | - | floating_ips | 20 | - | fixed_ips | -1 | - | metadata_items | 128 | - | injected_files | 5 | - | injected_file_content_bytes | 10240 | - | injected_file_path_bytes | 255 | - | key_pairs | 100 | - | security_groups | 10 | - | security_group_rules | 20 | - | server_groups | 10 | - | server_group_members | 10 | - +-----------------------------+-------+ - -To update quota values for a project user ------------------------------------------ - -#. Place the user ID in a usable variable. - - .. code-block:: console - - $ projectUser=$(openstack user show -f value -c id USER_NAME) - -#. Place the user's project ID in a usable variable, as follows: - - .. code-block:: console - - $ project=$(openstack project show -f value -c id PROJECT_NAME) - -#. Update a particular quota value, as follows: - - .. code-block:: console - - $ nova quota-update --user $projectUser --QUOTA_NAME QUOTA_VALUE $project - - For example: - - .. code-block:: console - - $ nova quota-update --user $projectUser --floating-ips 12 $project - $ nova quota-show --user $projectUser --tenant $project - +-----------------------------+-------+ - | Quota | Limit | - +-----------------------------+-------+ - | instances | 10 | - | cores | 20 | - | ram | 51200 | - | floating_ips | 12 | - | fixed_ips | -1 | - | metadata_items | 128 | - | injected_files | 5 | - | injected_file_content_bytes | 10240 | - | injected_file_path_bytes | 255 | - | key_pairs | 100 | - | security_groups | 10 | - | security_group_rules | 20 | - | server_groups | 10 | - | server_group_members | 10 | - +-----------------------------+-------+ - - .. note:: - - To view a list of options for the :command:`nova quota-update` command, - run: - - .. code-block:: console - - $ nova help quota-update - -To display the current quota usage for a project user ------------------------------------------------------ - -Use :command:`nova limits` to get a list of the -current quota values and the current quota usage: - -.. code-block:: console - - $ nova limits --tenant PROJECT_NAME - - +------+-----+-------+--------+------+----------------+ - | Verb | URI | Value | Remain | Unit | Next_Available | - +------+-----+-------+--------+------+----------------+ - +------+-----+-------+--------+------+----------------+ - - +--------------------+------+-------+ - | Name | Used | Max | - +--------------------+------+-------+ - | Cores | 0 | 20 | - | Instances | 0 | 10 | - | Keypairs | - | 100 | - | Personality | - | 5 | - | Personality Size | - | 10240 | - | RAM | 0 | 51200 | - | Server Meta | - | 128 | - | ServerGroupMembers | - | 10 | - | ServerGroups | 0 | 10 | - +--------------------+------+-------+ +============= +Manage quotas +============= .. note:: - The :command:`nova limits` command generates an empty - table as a result of the Compute API, which prints an - empty list for backward compatibility purposes. + This section provides deployment information about the quota feature. For + end-user information about quotas, including information about the type of + quotas available, refer to the :doc:`user guide `. + +To prevent system capacities from being exhausted without notification, you can +set up quotas. Quotas are operational limits. For example, the number of +gigabytes allowed for each project can be controlled so that cloud resources +are optimized. Quotas can be enforced at both the project and the project-user +level. + +Starting in the 16.0.0 Pike release, the quota calculation system in nova was +overhauled and the old reserve/commit/rollback flow was changed to `count +resource usage`__ at the point of whatever operation is being performed, such +as creating or resizing a server. A check will be performed by counting current +usage for the relevant resource and then, if +:oslo.config:option:`quota.recheck_quota` is True, another check will be +performed to ensure the initial check is still valid. + +By default resource usage is counted using the API and cell databases but nova +can be configured to count some resource usage without using the cell +databases. See `Quota usage from placement`_ for details. + +Using the command-line interface, you can manage quotas for nova, along with +:cinder-doc:`cinder ` and :neutron-doc:`neutron +`. You would typically change default values +because, for example, a project requires more than ten volumes or 1 TB on a +compute node. + +__ https://specs.openstack.org/openstack/nova-specs/specs/pike/implemented/cells-count-resources-to-check-quota-in-api.html + + +Checking quota +-------------- + +When calculating limits for a given resource and project, the following checks +are made in order: + +#. Project-specific limits + + Depending on the resource, is there a project-specific limit on the + resource in either the ``quotas`` or ``project_user_quotas`` tables in the + database? If so, use that as the limit. You can create these resources + using: + + .. code-block:: console + + $ openstack quota set --instances 5 + +#. Default limits + + Check to see if there is a hard limit for the given resource in the + ``quota_classes`` table in the database for the ``default`` quota class. If + so, use that as the limit. You can modify the default quota limit for a + resource using: + + .. code-block:: console + + $ openstack quota set --instances 5 --class default + + .. note:: + + Only the ``default`` class is supported by nova. + +#. Config-driven limits + + If the above does not provide a resource limit, then rely on the + configuration options in the :oslo.config:group:`quota` config group for + the default limits. + +.. note:: + + The API sets the limit in the ``quota_classes`` table. Once a default limit + is set via the `default` quota class, that takes precedence over any + changes to that resource limit in the configuration options. In other + words, once you've changed things via the API, you either have to keep + those synchronized with the configuration values or remove the default + limit from the database manually as there is no REST API for removing quota + class values from the database. + + +.. _quota-usage-from-placement: + +Quota usage from placement +-------------------------- + +Starting in the Train (20.0.0) release, it is possible to configure quota usage +counting of cores and RAM from the placement service and instances from +instance mappings in the API database instead of counting resources from cell +databases. This makes quota usage counting resilient in the presence of `down +or poor-performing cells`__. + +Quota usage counting from placement is opt-in via the +::oslo.config:option:`quota.count_usage_from_placement` config option: + +.. code-block:: ini + + [quota] + count_usage_from_placement = True + +There are some things to note when opting in to counting quota usage from +placement: + +* Counted usage will not be accurate in an environment where multiple Nova + deployments are sharing a placement deployment because currently placement + has no way of partitioning resource providers between different Nova + deployments. Operators who are running multiple Nova deployments that share a + placement deployment should not set the + :oslo.config:option:`quota.count_usage_from_placement` configuration option + to ``True``. + +* Behavior will be different for resizes. During a resize, resource allocations + are held on both the source and destination (even on the same host, see + https://bugs.launchpad.net/nova/+bug/1790204) until the resize is confirmed + or reverted. Quota usage will be inflated for servers in this state and + operators should weigh the advantages and disadvantages before enabling + :oslo.config:option:`quota.count_usage_from_placement`. + +* The ``populate_queued_for_delete`` and ``populate_user_id`` online data + migrations must be completed before usage can be counted from placement. + Until the data migration is complete, the system will fall back to legacy + quota usage counting from cell databases depending on the result of an EXISTS + database query during each quota check, if + :oslo.config:option:`quota.count_usage_from_placement` is set to ``True``. + Operators who want to avoid the performance hit from the EXISTS queries + should wait to set the :oslo.config:option:`quota.count_usage_from_placement` + configuration option to ``True`` until after they have completed their online + data migrations via ``nova-manage db online_data_migrations``. + +* Behavior will be different for unscheduled servers in ``ERROR`` state. A + server in ``ERROR`` state that has never been scheduled to a compute host + will not have placement allocations, so it will not consume quota usage for + cores and ram. + +* Behavior will be different for servers in ``SHELVED_OFFLOADED`` state. A + server in ``SHELVED_OFFLOADED`` state will not have placement allocations, so + it will not consume quota usage for cores and ram. Note that because of this, + it will be possible for a request to unshelve a server to be rejected if the + user does not have enough quota available to support the cores and ram needed + by the server to be unshelved. + +__ https://docs.openstack.org/api-guide/compute/down_cells.html + + +Known issues +------------ + +If not :ref:`counting quota usage from placement ` +it is possible for down or poor-performing cells to impact quota calculations. +See the :ref:`cells documentation ` for details. + + +Future plans +------------ + +Hierarchical quotas +~~~~~~~~~~~~~~~~~~~ + +There has long been a desire to support hierarchical or nested quotas +leveraging support in the identity service for hierarchical projects. +See the `unified limits`__ spec for details. + +__ https://review.opendev.org/#/c/602201/ + + +Configuration +------------- + +View and update default quota values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To list all default quotas for a project, run: + +.. code-block:: console + + $ openstack quota show --default + +.. note:: + + This lists default quotas for all services and not just nova. + +To update a default value for a new project, run: + +.. code-block:: console + + $ openstack quota set --class --instances 15 default + +View and update quota values for a project or class +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To list quotas for a project, run: + +.. code-block:: console + + $ openstack quota show PROJECT + +.. note:: + + This lists project quotas for all services and not just nova. + +To update quotas for a project, run: + +.. code-block:: console + + $ openstack quota set --QUOTA QUOTA_VALUE PROJECT + +To update quotas for a class, run: + +.. code-block:: console + + $ openstack quota set --class --QUOTA QUOTA_VALUE CLASS + +.. note:: + + Only the ``default`` class is supported by nova. + +For example: + +.. code-block:: console + + $ openstack quota set --instances 12 my-project + $ openstack quota show my-project + +----------------------+----------------------------------+ + | Field | Value | + +----------------------+----------------------------------+ + | backup-gigabytes | 1000 | + | backups | 10 | + | cores | 32 | + | fixed-ips | -1 | + | floating-ips | 10 | + | gigabytes | 1000 | + | health_monitors | None | + | injected-file-size | 10240 | + | injected-files | 5 | + | injected-path-size | 255 | + | instances | 12 | + | key-pairs | 100 | + | l7_policies | None | + | listeners | None | + | load_balancers | None | + | location | None | + | name | None | + | networks | 20 | + | per-volume-gigabytes | -1 | + | pools | None | + | ports | 60 | + | project | c8156b55ec3b486193e73d2974196993 | + | project_name | project | + | properties | 128 | + | ram | 65536 | + | rbac_policies | 10 | + | routers | 10 | + | secgroup-rules | 50 | + | secgroups | 50 | + | server-group-members | 10 | + | server-groups | 10 | + | snapshots | 10 | + | subnet_pools | -1 | + | subnets | 20 | + | volumes | 10 | + +----------------------+----------------------------------+ + +To view a list of options for the :command:`openstack quota show` and +:command:`openstack quota set` commands, run: + +.. code-block:: console + + $ openstack quota show --help + $ openstack quota set --help + +View and update quota values for a project user +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + User-specific quotas are legacy and will be removed when migration to + :keystone-doc:`unified limits ` is complete. + User-specific quotas were added as a way to provide two-level hierarchical + quotas and this feature is already being offered in unified limits. For + this reason, the below commands have not and will not be ported to + openstackclient. + +To show quotas for a specific project user, run: + +.. code-block:: console + + $ nova quota-show --user USER PROJECT + +To update quotas for a specific project user, run: + +.. code-block:: console + + $ nova quota-update --user USER --QUOTA QUOTA_VALUE PROJECT + +For example: + +.. code-block:: console + + $ projectUser=$(openstack user show -f value -c id USER) + $ project=$(openstack project show -f value -c id PROJECT) + + $ nova quota-update --user $projectUser --instance 12 $project + $ nova quota-show --user $projectUser --tenant $project + +-----------------------------+-------+ + | Quota | Limit | + +-----------------------------+-------+ + | instances | 12 | + | cores | 20 | + | ram | 51200 | + | floating_ips | 10 | + | fixed_ips | -1 | + | metadata_items | 128 | + | injected_files | 5 | + | injected_file_content_bytes | 10240 | + | injected_file_path_bytes | 255 | + | key_pairs | 100 | + | security_groups | 10 | + | security_group_rules | 20 | + | server_groups | 10 | + | server_group_members | 10 | + +-----------------------------+-------+ + +To view the quota usage for the current user, run: + +.. code-block:: console + + $ nova limits --tenant PROJECT + +For example: + +.. code-block:: console + + $ nova limits --tenant my-project + +------+-----+-------+--------+------+----------------+ + | Verb | URI | Value | Remain | Unit | Next_Available | + +------+-----+-------+--------+------+----------------+ + +------+-----+-------+--------+------+----------------+ + + +--------------------+------+-------+ + | Name | Used | Max | + +--------------------+------+-------+ + | Cores | 0 | 20 | + | Instances | 0 | 10 | + | Keypairs | - | 100 | + | Personality | - | 5 | + | Personality Size | - | 10240 | + | RAM | 0 | 51200 | + | Server Meta | - | 128 | + | ServerGroupMembers | - | 10 | + | ServerGroups | 0 | 10 | + +--------------------+------+-------+ + +.. note:: + + The :command:`nova limits` command generates an empty table as a result of + the Compute API, which prints an empty list for backward compatibility + purposes. + +To view a list of options for the :command:`nova quota-show` and +:command:`nova quota-update` commands, run: + +.. code-block:: console + + $ nova help quota-show + $ nova help quota-update diff --git a/doc/source/admin/quotas2.rst b/doc/source/admin/quotas2.rst deleted file mode 100644 index 19cd8d507518..000000000000 --- a/doc/source/admin/quotas2.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _manage-quotas: - -============= -Manage quotas -============= - -.. todo:: Merge this into 'quotas.rst' - -To prevent system capacities from being exhausted without notification, you can -set up quotas. Quotas are operational limits. For example, the number of -gigabytes allowed for each project can be controlled so that cloud resources -are optimized. Quotas can be enforced at both the project and the project-user -level. - -Using the command-line interface, you can manage quotas for the OpenStack -Compute service, the OpenStack Block Storage service, and the OpenStack -Networking service. - -The cloud operator typically changes default values because a project requires -more than ten volumes or 1 TB on a compute node. - -.. note:: - - To view all projects, run: - - .. code-block:: console - - $ openstack project list - +----------------------------------+----------+ - | ID | Name | - +----------------------------------+----------+ - | e66d97ac1b704897853412fc8450f7b9 | admin | - | bf4a37b885fe46bd86e999e50adad1d3 | services | - | 21bd1c7c95234fd28f589b60903606fa | tenant01 | - | f599c5cd1cba4125ae3d7caed08e288c | tenant02 | - +----------------------------------+----------+ - - To display all current users for a project, run: - - .. code-block:: console - - $ openstack user list --project PROJECT_NAME - +----------------------------------+--------+ - | ID | Name | - +----------------------------------+--------+ - | ea30aa434ab24a139b0e85125ec8a217 | demo00 | - | 4f8113c1d838467cad0c2f337b3dfded | demo01 | - +----------------------------------+--------+ - -Use :samp:`openstack quota show {PROJECT_NAME}` to list all quotas for a -project. - -Use :samp:`openstack quota set {PROJECT_NAME} {--parameters}` to set quota -values. diff --git a/doc/source/admin/security-groups.rst b/doc/source/admin/security-groups.rst index 423fa3e5d29e..7c1d6f750ea3 100644 --- a/doc/source/admin/security-groups.rst +++ b/doc/source/admin/security-groups.rst @@ -258,4 +258,4 @@ hosts which share a network. There are two possible values: Additionally, the number of maximum rules per security group is controlled by the ``security_group_rules`` and the number of allowed security groups per project is controlled by the ``security_groups`` quota (see -:ref:`manage-quotas`). +:doc:`/admin/quotas`). diff --git a/doc/source/user/quotas.rst b/doc/source/user/quotas.rst index 22011a8b8e29..d4a5d36ac9f2 100644 --- a/doc/source/user/quotas.rst +++ b/doc/source/user/quotas.rst @@ -1,151 +1,235 @@ -.. - 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 -======== +====== +Quotas +====== Nova uses a quota system for setting limits on resources such as number of instances or amount of CPU that a specific project or user can use. -Starting in the 16.0.0 Pike release the quota calculation system in nova was -overhauled and the old reserve/commit/rollback flow was changed to `count -resource usage`_ at the point of whatever operation is being performed, such -as creating or resizing a server. A check will be performed by counting -current usage for the relevant resource and then if -:oslo.config:option:`quota.recheck_quota` is True (it is by default) another -check will be performed to ensure the initial check is still valid. - -By default resource usage is counted using the API and cell databases but -nova can be configured to count some resource usage without using the cell -databases, see `Quota usage from placement`_ for details. - -Quota limits and usage can be retrieved via the `limits`_ REST API. Quota -limits can be set per-tenant using the `quota sets`_ REST API or per class -(all tenants) using the `quota class sets`_ API. - -.. _count resource usage: https://specs.openstack.org/openstack/nova-specs/specs/pike/implemented/cells-count-resources-to-check-quota-in-api.html -.. _limits: https://docs.openstack.org/api-ref/compute/#limits-limits -.. _quota sets: https://docs.openstack.org/api-ref/compute/#quota-sets-os-quota-sets -.. _quota class sets: https://docs.openstack.org/api-ref/compute/#quota-class-sets-os-quota-class-sets - -Checking quota -============== - -When calculating limits for a given resource and tenant, the following -checks are made in order: - -* Depending on the resource, is there a tenant-specific limit on the resource - in either the `quotas` or `project_user_quotas` tables in the database? If - so, use that as the limit. You can create these resources by doing:: - - openstack quota set --instances 5 - -* Check to see if there is a hard limit for the given resource in the - `quota_classes` table in the database for the `default` quota class. If so, - use that as the limit. You can modify the default quota limit for a resource - by doing:: - - openstack quota set --class --instances 5 default - -* If the above does not provide a resource limit, then rely on the - :oslo.config:group:`quota` configuration options for the default limit. - -.. note:: The API sets the limit in the `quota_classes` table. Once a default - limit is set via the `default` quota class, that takes precedence over - any changes to that resource limit in the configuration options. In other - words, once you've changed things via the API, you either have to keep those - synchronized with the configuration values or remove the default limit from - the database manually as there is no REST API for removing quota class - values from the database. - -.. _quota-usage-from-placement: - -Quota usage from placement -========================== - -Starting in the Train (20.0.0) release, it is possible to configure quota usage -counting of cores and ram from the placement service and instances from -instance mappings in the API database instead of counting resources from cell -databases. This makes quota usage counting resilient in the presence of `down -or poor-performing cells`_. - -Quota usage counting from placement is opt-in via configuration option: - -.. code-block:: ini - - [quota] - count_usage_from_placement = True - -There are some things to note when opting in to counting quota usage from -placement: - -* Counted usage will not be accurate in an environment where multiple Nova - deployments are sharing a placement deployment because currently placement - has no way of partitioning resource providers between different Nova - deployments. Operators who are running multiple Nova deployments that share a - placement deployment should not set the - :oslo.config:option:`quota.count_usage_from_placement` configuration option - to ``True``. - -* Behavior will be different for resizes. During a resize, resource allocations - are held on both the source and destination (even on the same host, see - https://bugs.launchpad.net/nova/+bug/1790204) until the resize is confirmed - or reverted. Quota usage will be inflated for servers in this state and - operators should weigh the advantages and disadvantages before enabling - :oslo.config:option:`quota.count_usage_from_placement`. - -* The ``populate_queued_for_delete`` and ``populate_user_id`` online data - migrations must be completed before usage can be counted from placement. - Until the data migration is complete, the system will fall back to legacy - quota usage counting from cell databases depending on the result of an EXISTS - database query during each quota check, if - :oslo.config:option:`quota.count_usage_from_placement` is set to ``True``. - Operators who want to avoid the performance hit from the EXISTS queries - should wait to set the :oslo.config:option:`quota.count_usage_from_placement` - configuration option to ``True`` until after they have completed their online - data migrations via ``nova-manage db online_data_migrations``. - -* Behavior will be different for unscheduled servers in ``ERROR`` state. A - server in ``ERROR`` state that has never been scheduled to a compute host - will not have placement allocations, so it will not consume quota usage for - cores and ram. - -* Behavior will be different for servers in ``SHELVED_OFFLOADED`` state. A - server in ``SHELVED_OFFLOADED`` state will not have placement allocations, so - it will not consume quota usage for cores and ram. Note that because of this, - it will be possible for a request to unshelve a server to be rejected if the - user does not have enough quota available to support the cores and ram needed - by the server to be unshelved. - -.. _down or poor-performing cells: https://docs.openstack.org/api-guide/compute/down_cells.html +Quota limits and usage can be retrieved using the command-line interface. -Known issues -============ +Types of quota +-------------- -If not :ref:`counting quota usage from placement ` -it is possible for down or poor performing cells to impact quota calculations. -See the :ref:`cells documentation ` for details. +.. list-table:: + :header-rows: 1 + :widths: 10 40 -Future plans -============ + * - Quota name + - Description + * - cores + - Number of instance cores (VCPUs) allowed per project. + * - instances + - Number of instances allowed per project. + * - key_pairs + - Number of key pairs allowed per user. + * - metadata_items + - Number of metadata items allowed per instance. + * - ram + - Megabytes of instance ram allowed per project. + * - server_groups + - Number of server groups per project. + * - server_group_members + - Number of servers per server group. -Hierarchical quotas -------------------- +The following quotas were previously available but were removed in microversion +2.36 as they proxied information available from the networking service. -There has long been a desire to support hierarchical or nested quotas -leveraging support in the identity service for hierarchical projects. -See the `unified limits`_ spec for details. +.. list-table:: + :header-rows: 1 + :widths: 10 40 -.. _unified limits: https://review.opendev.org/#/c/602201/ + * - Quota name + - Description + * - fixed_ips + - Number of fixed IP addresses allowed per project. This number + must be equal to or greater than the number of allowed + instances. + * - floating_ips + - Number of floating IP addresses allowed per project. + * - networks + - Number of networks allowed per project (nova-network only). + * - security_groups + - Number of security groups per project. + * - security_group_rules + - Number of security group rules per project. + +Similarly, the following quotas were previously available but were removed in +microversion 2.57 as the personality files feature was deprecated. + +.. list-table:: + :header-rows: 1 + :widths: 10 40 + + * - Quota name + - Description + * - injected_files + - Number of injected files allowed per project. + * - injected_file_content_bytes + - Number of content bytes allowed per injected file. + * - injected_file_path_bytes + - Length of injected file path. + + +Usage +----- + +Project quotas +~~~~~~~~~~~~~~ + +To list all default quotas for projects, run: + +.. code-block:: console + + $ openstack quota show --default + +.. note:: + + This lists default quotas for all services and not just nova. + +For example: + +.. code-block:: console + + $ openstack quota show --default + +----------------------+----------+ + | Field | Value | + +----------------------+----------+ + | backup-gigabytes | 1000 | + | backups | 10 | + | cores | 20 | + | fixed-ips | -1 | + | floating-ips | 50 | + | gigabytes | 1000 | + | health_monitors | None | + | injected-file-size | 10240 | + | injected-files | 5 | + | injected-path-size | 255 | + | instances | 10 | + | key-pairs | 100 | + | l7_policies | None | + | listeners | None | + | load_balancers | None | + | location | None | + | name | None | + | networks | 10 | + | per-volume-gigabytes | -1 | + | pools | None | + | ports | 50 | + | project | None | + | project_name | project | + | properties | 128 | + | ram | 51200 | + | rbac_policies | 10 | + | routers | 10 | + | secgroup-rules | 100 | + | secgroups | 10 | + | server-group-members | 10 | + | server-groups | 10 | + | snapshots | 10 | + | subnet_pools | -1 | + | subnets | 10 | + | volumes | 10 | + +----------------------+----------+ + +To list the currently set quota values for your project, run: + +.. code-block:: console + + $ openstack quota show PROJECT + +where ``PROJECT`` is the ID or name of your project. For example: + +.. code-block:: console + + $ openstack quota show $OS_PROJECT_ID + +----------------------+----------------------------------+ + | Field | Value | + +----------------------+----------------------------------+ + | backup-gigabytes | 1000 | + | backups | 10 | + | cores | 32 | + | fixed-ips | -1 | + | floating-ips | 10 | + | gigabytes | 1000 | + | health_monitors | None | + | injected-file-size | 10240 | + | injected-files | 5 | + | injected-path-size | 255 | + | instances | 10 | + | key-pairs | 100 | + | l7_policies | None | + | listeners | None | + | load_balancers | None | + | location | None | + | name | None | + | networks | 20 | + | per-volume-gigabytes | -1 | + | pools | None | + | ports | 60 | + | project | c8156b55ec3b486193e73d2974196993 | + | project_name | project | + | properties | 128 | + | ram | 65536 | + | rbac_policies | 10 | + | routers | 10 | + | secgroup-rules | 50 | + | secgroups | 50 | + | server-group-members | 10 | + | server-groups | 10 | + | snapshots | 10 | + | subnet_pools | -1 | + | subnets | 20 | + | volumes | 10 | + +----------------------+----------------------------------+ + +To view a list of options for the :command:`openstack quota show` command, run: + +.. code-block:: console + + $ openstack quota show --help + +User quotas +~~~~~~~~~~~ + +.. note:: + + User-specific quotas are legacy and will be removed when migration to + :keystone-doc:`unified limits ` is complete. + User-specific quotas were added as a way to provide two-level hierarchical + quotas and this feature is already being offered in unified limits. For + this reason, the below commands have not and will not be ported to + openstackclient. + +To list the quotas for your user, run: + +.. code-block:: console + + $ nova quota-show --user USER --tenant PROJECT + +where ``USER`` is the ID or name of your user and ``PROJECT`` is the ID or name +of your project. For example: + +.. code-block:: console + + $ nova quota-show --user $OS_USERNAME --tenant $OS_PROJECT_ID + +-----------------------------+-------+ + | Quota | Limit | + +-----------------------------+-------+ + | instances | 10 | + | cores | 32 | + | ram | 65536 | + | metadata_items | 128 | + | injected_files | 5 | + | injected_file_content_bytes | 10240 | + | injected_file_path_bytes | 255 | + | key_pairs | 100 | + | server_groups | 10 | + | server_group_members | 10 | + +-----------------------------+-------+ + +To view a list of options for the :command:`nova quota-show` command, run: + +.. code-block:: console + + $ nova help quota-show diff --git a/doc/test/redirect-tests.txt b/doc/test/redirect-tests.txt index 0bbe64cd1f7b..5a78be5289cc 100644 --- a/doc/test/redirect-tests.txt +++ b/doc/test/redirect-tests.txt @@ -1,5 +1,6 @@ /nova/latest/addmethod.openstackapi.html 301 /nova/latest/contributor/api-2.html /nova/latest/admin/flavors2.html 301 /nova/latest/admin/flavors.html +/nova/latest/admin/quotas2.html 301 /nova/latest/admin/quotas.html /nova/latest/admin/numa.html 301 /nova/latest/admin/cpu-topologies.html /nova/latest/aggregates.html 301 /nova/latest/user/aggregates.html /nova/latest/api_microversion_dev.html 301 /nova/latest/contributor/microversions.html