Tethys Quotas API
Last Updated: March 2019
Tethys Quotas allows portal admins to set-up, manage and enforce storage, compute-time and other resource quotas on users, apps and other entities. The portal admins can declare a quota's defaults and state (i.e. active/inactive) and change it at anytime to meet the needs of the portal. They can also set entity specific quotas if the need arises (an entity can be a Tethys App or a User). For example, if there is a portal default quota on user workspace storage of 5 GB but there is a specific user who needs double that to complete their workflows, an admin can go into that user's settings and change their user-specific quota to 10 GB.
Built-in Quotas
Custom quotas can be created, but by default Tethys includes two built-in quotas: User Workspace Quotas and App Workspace Quotas.
Tip
See Creating Custom Quotas for information on how to remove quotas and/or add custom quotas.
Admin Pages
For information on how to manage the built-in quotas see Manage App Storage and Manage User Storage
ResourceQuotaHandler
-
class
tethys_quotas.handlers.base.
ResourceQuotaHandler
(entity, *args, **kwargs) -
Defines one or more ResourceQuotas. Also houses logic to check quota.
-
codename
-
unique codename for quota, used to look up specific quotas easily (e.g. ‘workspace_storage’).
- Type
str
-
description
-
more detailed description of the quota resource (e.g.: "Storage limit on workspaces.").
- Type
str
-
applies_to
-
list of dot-paths to the entities to which this quota will apply. Any of “django.contrib.auth.models.User” or “tethys_apps.models.TethysApp”.
- Type
list<str>
-
Creating Custom Quotas
To create a custom quota you will have to create a new quota handler class. Your new handler class will have to inherit from the ResourceQuotaHandler class. Follow the pattern in the built-in handler class, WorkspaceQuotaHandler
(located at src/tethys_quotas/handlers/workspace.py
).
Important
The abstract method, get_current_use
, which needs to be overridden in any custom quota handler class, is essential as it holds the logic for what the quota is measuring (time, storage, etc.).
To load a custom quota, append the classpath to the RESOURCE_QUOTA_HANDLERS
section of the portal_config.yml
file (see snippet of portal_config.yml
below).
# RESOURCE QUOTAS TO INSTALL
RESOURCE_QUOTA_HANDLERS:
- tethys_quotas.handlers.workspace.WorkspaceQuotaHandler
Figure 1. portal_config.yml
file showing the RESOURCE_QUOTA_HANDLERS
section.
Note
Delete or comment out classpath strings in the portal_config.yml
file to remove certain quota types from the portal.
Enforcing Quotas
Using the @app_workspace or @user_workspace decorators will automatically enforce the built in workspace quotas. To enforce a custom quota, the @enforce_quota
decorator must be used. Within the decorator initialization, pass in the respective codename
of the quota you wish to enforce.
# Import the enforce_quota decorator
from tethys_sdk.quotas import enforce_quota
...
# Enforce the desired quota (taken from the Dam Inventory Tutorial)
@enforce_quota('user_dam_quota')
@permission_required('add_dams')
def add_dam(request):
"""
Controller for the Add Dam page.
"""
...
Figure 2. Example usage of @enforce_quota
, taken from the Dam Inventory Tutorial.
The @enforce_quota
decorator will check to make sure the desired quota hasn't been met. If the quota has been met the user will be rerouted to an error page displaying the quota's help text.
Quotas API
A few helper functions have been added with Tethys Quotas to help developers integrate quotas within their apps.
get_quota
-
tethys_quotas.utilities.
get_quota
(entity, codename) -
Gets the quota value
- Parameters
entity (User or TethysApp) -- the entity on which to perform quota check.
codename (str) -- codename of the Quota to get
- Returns
Dictionary with two keys: quota(int) - value of quota, units(str) - units of value, if applicable # noqa: E501
- Return type
dict (quota, units)
get_resource_available
-
tethys_quotas.utilities.
get_resource_available
(entity, codename) -
Checks the quantity of resources remaining before the quota is met
- Parameters
entity (User or TethysApp) -- the entity on which to check.
codename (str) -- codename of the Quota to check
- Returns
Dictionary with two keys: resource_available(int) - amount of resource remaining, units(str) - units of amount, if applicable # noqa: E501
- Return type
dict (resource_available, units)
passes_quota
-
tethys_quotas.utilities.
passes_quota
(entity, codename, raise_on_false=True) -
Checks to see if the quota has been exceeded or not
- Parameters
entity (User or TethysApp) -- the entity on which to check.
codename (str) -- codename of the Quota to check
raise_on_false (bool) -- raise error if entity does not pass quota.
- Returns
False if the entity has exceeded the quota, otherwise True.
Additional Resources
For more information and examples on how to use the Tethys Quotas API (including creating and enforcing custom quotas) see the Quotas Concepts tutorial.