commit a988f79507c16ccf364fd4f03bbdf6b0ee2b497e
Author: Giorgos Korfiatis <gkorf@grnet.gr>
Date:   Thu Oct 31 18:26:55 2013 +0200

    resource limit design

diff --git a/docs/design/resource-limits.rst b/docs/design/resource-limits.rst
new file mode 100644
index 0000000..4f42b65
--- /dev/null
+++ b/docs/design/resource-limits.rst
@@ -0,0 +1,126 @@
+Resource default limits and visibility
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We wish to keep track of resources which are not visible to the user or
+resources that we don't care to impose a certain limit on. For example, we
+wish to know the total number of CPUs per user without checking a limit and
+without the user needing to specify a value when applying for a new project.
+However, the administrator should be able at any time to change either of
+these parameters.
+
+Changes for 0.15
+================
+
+Resource registration
+---------------------
+
+A new resource will be registered with an infinite base quota limit (denoted
+by None); all fields in astakos and quotaholder containing limits will have
+to be set ``null=True``. A holding is created in the quotaholder for each
+accepted user with the said limit. This means that the resource is ready to
+be used in a commission, but we are not interested in checking a senseful
+limit.
+
+Resource ``cyclades.cpu`` will from now on denote the number of active cpus.
+Its description will change to explain this. A new resource,
+``cyclades.total_cpu``, will also be registered in the system, with the
+semantics ``cyclades.cpu`` used to have. The reason for this change is that
+(in our default policy) we would like to control the number of active CPUs
+but not the total CPUs (the latter would have an infinite limit). However,
+existing projects have specified a value for the resource ``cyclades.cpu``.
+If we don't reinterpret it as active CPUs, then this grant will be
+useless: It will add a value to infinite total CPUs, but provide no active
+CPUs. Likewise we will change ``cyclades.ram`` and register
+``cyclades.total_ram``.
+
+There now exists attribute ``allow_in_projects`` in resource definitions,
+which controls whether a resource appears in a project application in the
+UI. Currently, this is set to False only for resource
+``astakos.pending_app``. This will be renamed to ``allow_in_ui`` and affect
+also the appearance in the Usage page. A new attribute ``allow_in_api`` will
+also be included in resource definition (True by default), to control
+whether the resource can appear in related API calls: GET /resources, GET
+/quotas, POST /projects (applying for a project), etc. ``allow_in_ui`` will
+entail ``allow_in_api``. Both attributes will be adjustable through
+``snf-manage resource-modify``.
+
+Resources ``cyclades.total_cpu`` and ``cyclades.total_ram`` will be marked
+with ``allow_in_ui=False`` and ``allow_in_api=False``.
+
+Changing base quota
+-------------------
+
+Base quota for a certain user is determined by looking up the base quota
+limit that is registered for the resource, unless there exists a custom
+limit for the user/resource pair in the model AstakosUserQuota. Resource
+limit can change with::
+
+  snf-manage resource-modify <resource_name> --limit <value>
+
+This not only changes the quota scheme for future users but also affects all
+existing users that have no custom limit for this resource. Option
+``--limit`` will be renamed ``--set-base-quota``. Moreover, admin will be
+forced to provide an extra option ``--preserve-existing=True|False``; if
+false, it will operate as before; if true, it will preserve limits for
+existing users by generating entries in AstakosUserQuota with the old
+default value before changing it. In the latter case, in order to allow
+reverting the change, a log file will be written containing the list of
+users whose quota has been preserved, in the following format::
+
+  Description: Preserved the following base quota, because default has changed
+  Resource: <resource_name>
+  Date: 2013-12-31T00:00Z
+  <user1_uuid> <username1@example.org>
+  <user2_uuid> <username2@example.org>
+
+Log file will be provided by option ``--log-file <filename>``.
+If options ``--preserve-existing`` and ``--log-file`` are not given in
+the command line, the user will be prompted to fill them in.
+
+.. note:: With the following command you can revert a user quota back to
+   the current default::
+
+     snf-manage user-modify <id> --set-base-quota <resource_name> default
+
+Inspecting base quota
+---------------------
+
+Management command ``user-list`` will get a new option
+``--with-custom-quota`` to filter users that have custom base quota at least
+for one resource. Option ``--filter-by-resource=<pred>`` will filter users
+whose base quota satisfy the given predicate. For example::
+
+  snf-manage user-list -o uuid,resource,limit --filter-by-resource=cyclades.vm>2
+
+Changes for resource-pool projects (0.16)
+=========================================
+
+In 0.16, projects will be seen as a pool of resources, where one can
+allocate from and put back. This means that we need to specify a limit for
+resources, even for those not specified in a project application. (This was
+not needed prior to 0.16, because quota were cumulative; if you had had
+infinite total CPUs through base quota, you didn't need an extra project
+grant for this resource.)
+
+Moreover, base quota will be expressed by user-specific base projects. So,
+we need two different quota schemes: one for filling the resources of a
+base project when a new user is created, and a second one for completing
+the values for resources not specified by a project application.
+
+The former will be handled with ``snf-manage resource-modify
+--set-base-quota`` as before; the latter with a new option
+``--set-project-default``. Similar to the custom base quota logic of 0.15,
+resources granted by projects will be identified by first looking up the
+project grant definitions (as described in a project application) and if a
+resource is missing, it will be looked up in the appropriate scheme.
+
+When creating a new user, the base project created will not specify any
+resources, inheriting thusly the base quota scheme. If a resource base
+quota limit is changed with option ``--preserve-existing=True``, a new
+entry will be created in the project definition to keep the old value
+before changing the default.
+
+In the new projects, there are actually two limits per resource we need to
+define: the project-level and the member-level limit. For reasons of
+simplicity, the default schemes will only contain one value per resource,
+which will be consulted for both types of limits.
