241 lines
7.3 KiB
ReStructuredText
241 lines
7.3 KiB
ReStructuredText
************************
|
|
Quotas API - User Guide
|
|
************************
|
|
|
|
Running with default settings, the barbican REST API doesn't impose an upper
|
|
limit on the number of resources that are allowed to be created. barbican's
|
|
backend depends on limited resources. These limited resources include database,
|
|
plugin, and Hardware Security Module (HSM) storage space. This
|
|
can be an issue in a multi-project or multi-user environment when one project
|
|
can exhaust available resources, impacting other projects.
|
|
|
|
The answer to this, on a per-project basis, is project quotas.
|
|
|
|
This user guide will show you how a user can lookup his current effective
|
|
quotas and how a service admin can create, update, read, and delete project quota
|
|
configuration for all projects in his cloud.
|
|
|
|
This guide will assume you will be using a local running development environment of barbican.
|
|
If you need assistance with getting set up, please reference the
|
|
`development guide <https://docs.openstack.org/barbican/latest/contributor/dev.html>`__.
|
|
|
|
.. _user_project_quotas_overview:
|
|
|
|
Project Quotas Overview
|
|
#######################
|
|
|
|
All users authenticated with barbican are able to read the effective quota values
|
|
that apply to their project. Barbican can derive the project that a user belongs
|
|
to by reading the project scope from the authentication token.
|
|
|
|
Service administrators can read, set, and delete quota configurations for each
|
|
project known to barbican. The service administrator is recognized by his authenticated
|
|
role. The service administrator's role is defined in barbican's policy.json file.
|
|
The default role for a service admin is "key-manager:service-admin".
|
|
|
|
Quotas can be enforced for the following barbican resources: secrets, containers,
|
|
orders, consumers, and CAs. The configured quota value can be None (use the default),
|
|
-1 (unlimited), 0 (disabled), or a positive integer defining the maximum number
|
|
allowed for a project.
|
|
|
|
.. _default_project_quotas:
|
|
|
|
Default Quotas
|
|
--------------
|
|
|
|
When no project quotas have been set for a project, the default
|
|
project quotas are enforced for that project. Default quotas are specified
|
|
in the barbican configuration file (barbican.conf). The defaults provided
|
|
in the standard configuration file are as follows.
|
|
|
|
.. code-block:: none
|
|
|
|
# default number of secrets allowed per project
|
|
quota_secrets = -1
|
|
|
|
# default number of orders allowed per project
|
|
quota_orders = -1
|
|
|
|
# default number of containers allowed per project
|
|
quota_containers = -1
|
|
|
|
# default number of consumers allowed per project
|
|
quota_consumers = -1
|
|
|
|
# default number of CAs allowed per project
|
|
quota_cas = -1
|
|
|
|
The default quotas are returned via a **GET** on the **quotas** resource when no
|
|
explicit project quotas have been set for the current project.
|
|
|
|
|
|
.. _user_get_quotas:
|
|
|
|
How to Read Effective Quotas
|
|
############################
|
|
|
|
The current effective quotas for a project can be read via a **GET** to the **quotas** resource.
|
|
Barbican determines the current project ID from the scope of the authentication token sent
|
|
with the request.
|
|
|
|
.. code-block:: bash
|
|
|
|
Request:
|
|
|
|
curl -i -X GET -H "X-Auth-Token:$TOKEN" \
|
|
-H "Accept:application/json" \
|
|
http://localhost:9311/v1/quotas
|
|
|
|
|
|
Response:
|
|
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json; charset=UTF-8
|
|
{"quotas":
|
|
{"secrets": -1,
|
|
"orders": -1,
|
|
"containers": -1,
|
|
"consumers": -1,
|
|
"cas": -1
|
|
}
|
|
}
|
|
|
|
|
|
To get more details on the quota lookup API, you can reference the
|
|
`Get Quotas <https://docs.openstack.org/barbican/latest/api/reference/quotas.html#get-quotas-request>`__
|
|
documentation.
|
|
|
|
|
|
.. _user_put_project_quotas:
|
|
|
|
How to Set or Replace Project Quotas
|
|
####################################
|
|
|
|
The quotas for a project can be modified via a **PUT** to the **project-quotas** resource.
|
|
This request completely replaces existing quota settings for a project. The project
|
|
ID is passed in the URI of the request.
|
|
|
|
To set or replace the quotas for the project with the ID 1234:
|
|
|
|
.. code-block:: bash
|
|
|
|
Request:
|
|
|
|
curl -i -X PUT -H "content-type:application/json" \
|
|
-H "X-Auth-Token:$TOKEN" \
|
|
-d '{"project_quotas": {"secrets": 500,
|
|
"orders": 100, "containers": -1, "consumers": 100,
|
|
"cas": 50}}' \
|
|
http://localhost:9311/v1/project-quotas/1234
|
|
|
|
Response:
|
|
|
|
HTTP/1.1 204 No Content
|
|
|
|
|
|
To get more details on the project quota setting API you can reference the
|
|
`Set Project Quotas <https://docs.openstack.org/barbican/latest/api/reference/quotas.html#put-project-quotas>`__
|
|
documentation.
|
|
|
|
|
|
.. _user_get_project_quotas:
|
|
|
|
How to Retrieve Configured Project Quotas
|
|
#########################################
|
|
|
|
The project quota information defined for a project can be retrieved by using
|
|
a **GET** operation on the respective **project-quota** resource. The project
|
|
ID is passed in the URI of the request. The returned response contains project
|
|
quota data.
|
|
|
|
To get project quota information for a single project:
|
|
|
|
.. code-block:: bash
|
|
|
|
Request:
|
|
|
|
curl -i -X GET -H "X-Auth-Token:$TOKEN" \
|
|
-H "Accept:application/json" \
|
|
http://localhost:9311/v1/project-quotas/1234
|
|
|
|
Response:
|
|
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json; charset=UTF-8
|
|
{"project_quotas":
|
|
{"secrets": 500,
|
|
"orders": 100,
|
|
"containers": -1,
|
|
"consumers": 100,
|
|
"cas": 50}}
|
|
|
|
|
|
The project quota information defined for all projects can be retrieved by using
|
|
a **GET** operation on the **project-quota** resource.
|
|
The returned response contains a list with all project quota data.
|
|
|
|
.. code-block:: bash
|
|
|
|
Request:
|
|
|
|
curl -i -X GET -H "X-Auth-Token:$TOKEN" \
|
|
-H "Accept:application/json" \
|
|
http://localhost:9311/v1/project-quotas
|
|
|
|
|
|
Response:
|
|
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json; charset=UTF-8
|
|
{"project_quotas":
|
|
[{"project_id": "1234",
|
|
"project_quotas":
|
|
{"secrets": 500,
|
|
"orders": 100,
|
|
"containers": -1,
|
|
"consumers": 100,
|
|
"cas": 50}},
|
|
{"project_id": "5678",
|
|
"project_quotas":
|
|
{"secrets": 500,
|
|
"orders": 100,
|
|
"containers": -1,
|
|
"consumers": 100,
|
|
"cas": 50}}]}
|
|
|
|
|
|
To get more details on project quota lookup APIs you can reference
|
|
the
|
|
`Get Project Quota <https://docs.openstack.org/barbican/latest/api/reference/quotas.html#get-project-quotas-uuid>`__
|
|
and
|
|
`Get Project Quota List <https://docs.openstack.org/barbican/latest/api/reference/quotas.html#get-project-quotas>`__
|
|
documentation.
|
|
|
|
|
|
.. _user_delete_project_quotas:
|
|
|
|
How to Delete Configured Project Quotas
|
|
#######################################
|
|
|
|
Quotas defined for a project can be deleted by using the **DELETE** operation
|
|
on the respective **project-quotas** resource. The quota configuration information
|
|
is deleted for a project, the default quotas will then apply to that project.
|
|
There is no response content returned on successful deletion.
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
Request:
|
|
|
|
curl -i -X DELETE -H "X-Auth-Token:$TOKEN" \
|
|
http://localhost:9311/v1/project-quotas/1234
|
|
|
|
Response:
|
|
|
|
HTTP/1.1 204 No Content
|
|
|
|
|
|
To get more details on project quota delete APIs, you can reference the
|
|
`Delete Project Quotas <https://docs.openstack.org/barbican/latest/api/reference/quotas.html#delete-project-quotas>`__
|
|
documentation.
|