This is an automated email from the ASF dual-hosted git repository.
weizhouapache pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/main by this push:
new 555e4624 Add new Quota Plugin documentation (#668)
555e4624 is described below
commit 555e46240d99b551e4d5171cad934068026ea7f1
Author: Fabricio Duarte <[email protected]>
AuthorDate: Wed Sep 2 06:33:08 2026 -0300
Add new Quota Plugin documentation (#668)
---
source/_static/images/quota-balance-report.png | Bin 0 -> 139486 bytes
.../images/quota-consumption-by-resources.png | Bin 0 -> 104748 bytes
.../images/quota-consumption-of-a-resource.png | Bin 0 -> 152567 bytes
.../_static/images/quota-consumption-summary.png | Bin 0 -> 200251 bytes
source/_static/images/quota-credits-report.png | Bin 0 -> 104410 bytes
source/_static/images/quota-email-template.png | Bin 0 -> 127586 bytes
source/_static/images/quota-fixed-tariff.png | Bin 0 -> 75269 bytes
.../images/quota-summary-history-cumulative.png | Bin 0 -> 149949 bytes
source/_static/images/quota-summary-history.png | Bin 0 -> 155660 bytes
source/_static/images/quota-summary-total.png | Bin 0 -> 134584 bytes
.../_static/images/quota-tariff-boolean-return.png | Bin 0 -> 82102 bytes
.../_static/images/quota-tariff-numeric-return.png | Bin 0 -> 91431 bytes
source/plugins/quota.rst | 859 +++++++++++++++++----
13 files changed, 704 insertions(+), 155 deletions(-)
diff --git a/source/_static/images/quota-balance-report.png
b/source/_static/images/quota-balance-report.png
new file mode 100644
index 00000000..bfe3ff6f
Binary files /dev/null and b/source/_static/images/quota-balance-report.png
differ
diff --git a/source/_static/images/quota-consumption-by-resources.png
b/source/_static/images/quota-consumption-by-resources.png
new file mode 100644
index 00000000..a1e281ad
Binary files /dev/null and
b/source/_static/images/quota-consumption-by-resources.png differ
diff --git a/source/_static/images/quota-consumption-of-a-resource.png
b/source/_static/images/quota-consumption-of-a-resource.png
new file mode 100644
index 00000000..a6f00897
Binary files /dev/null and
b/source/_static/images/quota-consumption-of-a-resource.png differ
diff --git a/source/_static/images/quota-consumption-summary.png
b/source/_static/images/quota-consumption-summary.png
new file mode 100644
index 00000000..90fab3b0
Binary files /dev/null and
b/source/_static/images/quota-consumption-summary.png differ
diff --git a/source/_static/images/quota-credits-report.png
b/source/_static/images/quota-credits-report.png
new file mode 100644
index 00000000..bec6492e
Binary files /dev/null and b/source/_static/images/quota-credits-report.png
differ
diff --git a/source/_static/images/quota-email-template.png
b/source/_static/images/quota-email-template.png
new file mode 100644
index 00000000..25c8d60a
Binary files /dev/null and b/source/_static/images/quota-email-template.png
differ
diff --git a/source/_static/images/quota-fixed-tariff.png
b/source/_static/images/quota-fixed-tariff.png
new file mode 100644
index 00000000..36e4ac77
Binary files /dev/null and b/source/_static/images/quota-fixed-tariff.png differ
diff --git a/source/_static/images/quota-summary-history-cumulative.png
b/source/_static/images/quota-summary-history-cumulative.png
new file mode 100644
index 00000000..3bc3a406
Binary files /dev/null and
b/source/_static/images/quota-summary-history-cumulative.png differ
diff --git a/source/_static/images/quota-summary-history.png
b/source/_static/images/quota-summary-history.png
new file mode 100644
index 00000000..e4dcc743
Binary files /dev/null and b/source/_static/images/quota-summary-history.png
differ
diff --git a/source/_static/images/quota-summary-total.png
b/source/_static/images/quota-summary-total.png
new file mode 100644
index 00000000..fd85461c
Binary files /dev/null and b/source/_static/images/quota-summary-total.png
differ
diff --git a/source/_static/images/quota-tariff-boolean-return.png
b/source/_static/images/quota-tariff-boolean-return.png
new file mode 100644
index 00000000..e20a5130
Binary files /dev/null and
b/source/_static/images/quota-tariff-boolean-return.png differ
diff --git a/source/_static/images/quota-tariff-numeric-return.png
b/source/_static/images/quota-tariff-numeric-return.png
new file mode 100644
index 00000000..a1a66757
Binary files /dev/null and
b/source/_static/images/quota-tariff-numeric-return.png differ
diff --git a/source/plugins/quota.rst b/source/plugins/quota.rst
index 3beb0892..e4fd0109 100644
--- a/source/plugins/quota.rst
+++ b/source/plugins/quota.rst
@@ -1,189 +1,738 @@
-.. Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with this
work
- for additional information# regarding copyright ownership. The ASF licenses
this
- file to you 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.
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information#
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+Quota Plugin
+============
+
+The Quota Plugin provides mechanisms for assigning monetary values to
+resource consumption records generated by the Usage Server, based on pricing
+rules defined by cloud operators. It can also be configured to automatically
+lock Accounts that exceed their allocated quota.
+
+ACS does not provide native billing functionalities such as invoice generation.
+These features must be implemented externally by cloud providers. The Quota
+Plugin serves as an intermediate layer that outputs monetary values based on
+resource consumption, which can then be forwarded to external billing systems.
+
+
+Usage Server Prerequisites
+--------------------------
+
+Before configuring the Quota Plugin, you must ensure that the Usage Server is
+installed and enabled. The Usage Server generates records based on actions
+performed by the platform and its users, which the Quota Plugin uses as input
+for its calculations.
+
+The following global settings control the behavior of the Usage Server:
+.. cssclass:: table-striped table-bordered table-hover
-Quota Plugin
-=============
++----------------------------------------+---------------------------------------------------------------+
+| Global Setting | Description
|
++========================================+===============================================================+
+| ``enable.usage.server`` | Controls whether the Usage Server
is active in the |
+| | environment. Set to ``true`` to
enable. |
++----------------------------------------+---------------------------------------------------------------+
+| ``usage.stats.job.exec.time`` | Defines the time when resource
consumption statistics will |
+| | be aggregated for the first time
after the Usage Server |
+| | starts (format: ``HH:mm``).
|
++----------------------------------------+---------------------------------------------------------------+
+| ``usage.execution.timezone`` | Specifies the timezone for the
``usage.stats.job.exec.time`` |
+| | setting.
|
++----------------------------------------+---------------------------------------------------------------+
+| ``usage.stats.job.aggregation.range`` | Specifies the time interval (in
minutes) between each |
+| | aggregation of resource consumption
statistics. |
++----------------------------------------+---------------------------------------------------------------+
+| ``usage.aggregation.timezone`` | Specifies the timezone used for
statistics aggregation. |
+| | For instance, if aggregation is
daily, it determines in |
+| | which timezone a day is considered.
|
++----------------------------------------+---------------------------------------------------------------+
+
+.. note::
+
+ After changing any of these global settings, you must restart the
+ Usage Server service for the changes to take effect.
+
+Usage Aggregation
+~~~~~~~~~~~~~~~~~
+
+Typically, the Usage job runs every hour (60 minutes) or every day (1440
+minutes) to aggregate resource consumption into usage records. Hourly
+aggregation provides greater granularity but generates more database records.
+Daily aggregation groups records together, consuming less storage space and
+taking less time to process, but with reduced granularity.
+
+The aggregation interval only affects how resource consumption is divided into
+usage records. It does **not** affect the values applied by the Quota Plugin.
+Regardless of the aggregation interval, the actual consumed time is accounted
+for accurately. For example, an Instance running continuously for two
+consecutive days will generate 48 one-hour records when hourly aggregation is
+used, or two 24-hour records when daily aggregation is configured.
+
+
+Enabling the Quota Plugin
+-------------------------
+
+The Quota Plugin is disabled by default. To enable it, go to **Global
Settings**
+and configure the following settings:
-Quota service, while allowing for scalability, will make sure that the cloud is
-not exploited by attacks, careless use and program errors. To address this
-problem, employ the quota-enforcement service that allows resource
-usage within certain bounds as defined by policies and available quotas for
-various entities. Quota service extends the functionality of usage server to
-provide a measurement for the resources used by the Accounts and domains using
a
-common unit referred to as cloud currency in this document. It can be
configured
-to ensure that your usage won’t exceed the budget allocated to Accounts/domain
-in cloud currency. It will let users know how much of the cloud resources they
are
-using. It will help the cloud admins, if they want, to ensure that a user does
-not go beyond their allocated quota. Per usage cycle if an Account is found to
be
-exceeding its quota then it is locked. Locking an Account means that it will
not
-be able to initiate a new resource allocation request, whether it is more
-storage or an additional IP. To unlock an Account you need to add more credit
to it.
-In case you want the locking to be disabled on global or on Account scope those
-provisions are also provided. Needless to say quota service as well as any
action
-on the Account is configurable.
+.. cssclass:: table-striped table-bordered table-hover
-Enabling the Quota Service
-----------------------------
++--------------------------------+------------------------------------------------------------------+
+| Global Setting | Description
|
++================================+==================================================================+
+| ``quota.enable.service`` | Controls whether the Quota Plugin is
enabled. Set to ``true`` |
+| | to activate it.
|
++--------------------------------+------------------------------------------------------------------+
+| ``js.interpretation.enabled`` | Enables JavaScript interpretation, which is
used to evaluate |
+| | quota tariff activation rules. This setting
must be ``true`` |
+| | when using the activation rules described
in |
+| | :ref:`quota-activation-rules`.
|
++--------------------------------+------------------------------------------------------------------+
+| ``quota.currency.symbol`` | Specifies the symbol used when representing
monetary values |
+| | (e.g. ``€``, ``US$``, ``R$``).
|
++--------------------------------+------------------------------------------------------------------+
+| ``quota.currency.locale`` | Specifies the locale used for formatting
monetary values |
+| | (e.g. ``pt-BR``, ``en-US``).
|
++--------------------------------+------------------------------------------------------------------+
+| ``quota.enable.enforcement`` | Controls whether an Account is
automatically locked if its |
+| | quota balance goes below zero.
|
++--------------------------------+------------------------------------------------------------------+
+
+.. note::
+
+ After changing ``quota.enable.service`` or ``quota.enable.enforcement``,
you must
+ restart both the Management Server and the Usage Server services for the
changes to
+ take effect.
+
+Once the Quota Plugin is enabled, the last step of the Usage job will
calculate the
+quota consumption for each Account based on the configured quota tariffs. You
can
+also manually trigger quota calculation for all unprocessed usage records by
+calling the ``quotaUpdate`` API.
+
+
+Quota Tariffs
+-------------
-Before installing and configuring the quota service you need to make sure that
-the Usage Server has been installed. This requires extra steps beyond just
-installing the CloudStack software. See Installing the Usage Server (Optional)
-in the Advanced Installation Guide.
+Overview
+~~~~~~~~
-#. enable.usage.server: Set to true to enable usage server.
+To define monetary values for cloud resource consumption, the Quota Plugin
+introduces the concept of tariffs. Each tariff is associated with a usage
+type, which determines the kind of resource consumption to which the tariff
+applies (for example, running virtual machines, volumes, or network traffic).
+The measurement unit also depends on the usage type. Multiple tariffs
+may be associated with the same usage type, allowing cloud operators to
+implement different pricing strategies.
-The quota plugin is disabled by default. To enable it goto Global Settings and
-set the following global configuration to true:
+The simplest form of tariff applies a fixed value per unit of resource consumed
+per month. For example, a tariff may apply 18.25 monetary units for each public
+IP used for a total of one month:
-#. quota.enable.service
+.. figure:: /_static/images/quota-fixed-tariff.png
+ :align: center
+ :alt: Example of a fixed quota tariff
-By default Quota service does not lock the Accounts that have exceeded the
quota
-usage. To enable quota service to lock Accounts set the following global
-configuration to true:
+|
-#. quota.enable.enforcement
+Quota tariffs are applied to each usage record. Therefore, the
+calculated value is proportional to the amount of resource consumption
recorded.
+For example, if a public IP is used for half a month, the tariff above will
+result in a value of 9.125.
-The other configurations that are there for quota service are as:
+Tariffs may apply either fixed values, or dynamic values through
+:ref:`quota-activation-rules`.
-#. quota.currency.symbol : The symbol that is used before any currency
- figure in various quota forms and reports.
-#. quota.usage.smtp.host: Quota SMTP host for sending quota alerts.
-#. quota.usage.smtp.port: Quota SMTP port.
-#. quota.usage.smtp.user: Quota SMTP user.
-#. quota.usage.smtp.password: Quota SMTP password.
-#. quota.usage.smtp.sender: Quota SMTP alert sender email address.
-#. quota.usage.smtp.useAuth: If true, use secure SMTP authentication when
sending emails.
-#. quota.usage.smtp.connection.timeout: Quota SMTP server connection timeout
duration.
+.. _quota-activation-rules:
-There are several configuration variables that are inherited from usage
server,
-these are listed below:
+Activation Rules
+~~~~~~~~~~~~~~~~
-#. usage.aggregation.timezone
+Quota tariffs can also calculate dynamic values based on the resource's context
+through activation rules. Activation rules consist of JavaScript expressions
+that must return either a numeric or a boolean value. The returned value
determines
+how the tariff is applied:
-All these are described in details in Usage Server documentation.
+.. cssclass:: table-striped table-bordered table-hover
-Restart the Management Server and the Usage Server to enable the set
configuration
-values.
++---------------+--------------------------------------------------------+
+| Return type | Effect |
++===============+========================================================+
+| Numeric | Uses the returned value as the tariff value. |
++---------------+--------------------------------------------------------+
+| ``true`` | Applies the configured base tariff value. |
++---------------+--------------------------------------------------------+
+| ``false`` | Applies a tariff value of zero. |
++---------------+--------------------------------------------------------+
-.. code:: bash
+.. important::
- service cloudstack-management restart
- service cloudstack-usage restart
+ Activation rules must not use the ``return`` keyword. Instead, the result of
+ the last evaluated expression is automatically used as the return value of
+ the activation rule.
-Once the quota service is running it will calculate the quota balance for each
Account.
-The quota usage is calculated as per the quota tariff provided by the site
administrator.
+During rule evaluation, ACS automatically exposes resource metadata through
+preset variables. These variables provide access to information about the
+resource being processed, its attributes, and other execution context,
+allowing organizations to implement custom pricing policies. The list of
+available preset variables for each resource type can be obtained through the
+``quotaPresetVariableList`` API.
+The following example demonstrates a tariff that applies 56.85 monetary units
+to each vCPU allocated for a total of one month:
-Quota Tariff
--------------
+.. figure:: /_static/images/quota-tariff-numeric-return.png
+ :align: center
+ :alt: Example of a tariff with an activation rule returning a numeric value
-The following table shows all quota types for which you can specify tariff.
+|
-.. cssclass:: table-striped table-bordered table-hover
+This second example shows a tariff that applies 0.76 monetary units per GB
+of volume allocated for a month in primary storage pools that contain the tag
+``ssd``:
+
+.. figure:: /_static/images/quota-tariff-boolean-return.png
+ :align: center
+ :alt: Example of a tariff with an activation rule returning a boolean value
+
+|
+
+.. important::
+
+ Reserved variable declaration keywords such as ``var``, ``let``, and
+ ``const`` must not be used in activation rules. The expression processing
+ engine is instantiated only once per processing cycle; therefore, using
+ these keywords results in the error
+ ``Identifier has already been declared``. To declare variables, omit the
+ JavaScript declaration keywords.
+
+.. important::
+
+ When writing activation rules that return a numeric value, consider the
+ measurement unit of the corresponding tariff type. For example, the
+ ``VOLUME`` tariff type is measured in ``GB * Month``. Therefore, if an
+ operator wants to charge 0.76 monetary units per GB allocated during a
+ month, the rule should simply return ``0.76`` instead of multiplying it by
+ the volume size.
+
+.. note::
+
+ Activation rules are interpreted using ECMAScript 5.1. Only language
+ features supported by this version are available.
+
+Tariff Processing Order
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The processing order allows tariffs associated with the same usage type to
depend
+on the results of previously executed tariffs. This makes it possible to
+implement pricing models such as cumulative charges, discounts, taxes, or
+additional fees.
+
+Tariffs are processed in ascending order of their position. A tariff with
+position ``1`` is executed before one with position ``2``. If two tariffs
+share the same position, the most recently added tariff is executed first.
+
+As each tariff is processed, ACS makes the results of all previously executed
+tariffs available through the preset variable ``lastTariffs``. This variable is
+a list of objects containing the ``id`` and ``value`` of each previously
+executed tariff, allowing subsequent tariffs to reuse earlier calculations.
+
+For example, if there are three tariffs with the same usage type, ordered as
+``tariff-01``, ``tariff-02``, and ``tariff-03``:
+
+- When processing ``tariff-01``, the value of ``lastTariffs`` is empty:
+
+ .. code:: js
+
+ []
+
+- When processing ``tariff-02``, the value of ``lastTariffs`` is:
+
+ .. code:: js
+
+ [
+ {
+ "id": <uuid-of-tariff-01>,
+ "value": <result-of-tariff-01>
+ }
+ ]
+
+- When processing ``tariff-03``, the value of ``lastTariffs`` is:
+
+ .. code:: js
+
+ [
+ {
+ "id": <uuid-of-tariff-01>,
+ "value": <result-of-tariff-01>
+ },
+ {
+ "id": <uuid-of-tariff-02>,
+ "value": <result-of-tariff-02>
+ }
+ ]
+
+The following example demonstrates how ``lastTariffs`` can be used to apply a
+5% discount to a previously calculated tariff when its value exceeds 100
+monetary units. This tariff must be configured with a higher position than the
+tariff whose value is being discounted.
+
+Suppose the first tariff charges 150 monetary units. A second tariff,
configured
+with a higher position, can then apply the discount through its activation
rule:
+
+.. code:: js
+
+ firstCharge = lastTariffs[0].value;
+
+ if (firstCharge > 100) {
+ firstCharge * -0.05
+ } else {
+ 0
+ }
+
+
+Tariff Examples
+~~~~~~~~~~~~~~~
+
+The following examples illustrate common tariff configurations using both fixed
+values and activation rules. Unless stated otherwise, all monetary values
+represent one month of resource consumption.
+
+Each example lists only the relevant tariff attributes. Unless specified
+otherwise, no activation rule is required.
+
+Compute Resources
+^^^^^^^^^^^^^^^^^
+
+Charging a Fixed Monthly Fee per Virtual Machine
+""""""""""""""""""""""""""""""""""""""""""""""""
+
+To charge a fixed amount of **1 monetary unit per allocated virtual machine
+per month**, configure a tariff with:
+
+- **Type:** ``ALLOCATED_VM``
+- **Value:** ``1``
+
+Charging per Allocated CPU Capacity
+"""""""""""""""""""""""""""""""""""
+
+To charge **0.05 monetary units per MHz allocated per month**, configure:
+
+- **Type:** ``ALLOCATED_VM``
+- **Value:** ``0``
+
+- **Activation rule:**
+
+ .. code:: js
+
+ price = 0.05;
+ allocatedCpuMHz = value.computingResources.cpuNumber *
+ value.computingResources.cpuSpeed;
+ price * allocatedCpuMHz
+
+Charging per Allocated Memory
+"""""""""""""""""""""""""""""
+
+To charge **10 monetary units per GiB of allocated memory per month**,
+configure:
+
+- **Type:** ``ALLOCATED_VM``
+- **Value:** ``0``
+
+- **Activation rule:**
+
+ .. code:: js
+
+ price = 10;
+ usageInGiB = value.computingResources.memory / 1024;
+ price * usageInGiB
+
+Charging a Specific Account
+"""""""""""""""""""""""""""
+
+To charge **2 monetary units per running virtual machine per month** only for
+a specific Account, with UUID ``c1558d9c-45bf-4721-8b4d-c67f911e3f65``,
configure:
+
+- **Type:** ``RUNNING_VM``
+- **Value:** ``2``
+
+- **Activation rule:**
+
+ .. code:: js
+
+ account.id === 'c1558d9c-45bf-4721-8b4d-c67f911e3f65'
+
+Charging Multiple Specific Accounts
+"""""""""""""""""""""""""""""""""""
+
+To charge **2 monetary units per running virtual machine per month** only for
+a predefined set of Accounts, with UUIDs
``c1558d9c-45bf-4721-8b4d-c67f911e3f65``
+and ``294ec2e8-89f7-422e-b201-6cd9a4d0e73b``, configure:
+
+- **Type:** ``RUNNING_VM``
+- **Value:** ``2``
+
+- **Activation rule:**
+
+ .. code:: js
+
+ [
+ 'c1558d9c-45bf-4721-8b4d-c67f911e3f65',
+ '294ec2e8-89f7-422e-b201-6cd9a4d0e73b'
+ ].indexOf(account.id) > -1
+
+Charging Different Prices per Domain
+""""""""""""""""""""""""""""""""""""
+
+To charge **3 monetary units per running virtual machine per month** for
+a specific Domain, with UUID ``c875819c-2e76-40b0-9755-f3c628ff4743``, and **2
monetary units** for all other Domains, configure:
+
+- **Type:** ``RUNNING_VM``
+- **Value:** ``0``
+
+- **Activation rule:**
+
+ .. code:: js
+
+ if (domain.id === 'c875819c-2e76-40b0-9755-f3c628ff4743') {
+ 3
+ } else {
+ 2
+ }
+
+Charging a Domain and Its Subdomains
+""""""""""""""""""""""""""""""""""""
+
+To charge **2 monetary units per running virtual machine per month** for all
+Accounts belonging to a Domain with ``customer-A`` in its path, as well as any
+of its subdomains, configure:
+
+- **Type:** ``RUNNING_VM``
+- **Value:** ``2``
+
+- **Activation rule:**
+
+ .. code:: js
+
+ domain.path.indexOf('customer-A') > -1
+
+
+Storage Resources
+^^^^^^^^^^^^^^^^^
+
+.. _fixed-volume-charge-example:
+
+Charging a Fixed Monthly Fee per Volume
+"""""""""""""""""""""""""""""""""""""""
-+------------------+-----------------------------------+--------------------------+
-| Type ID | Type Name | Tariff Description
|
-| | |
|
-+==================+===================================+==========================+
-| 1 | RUNNING\_VM | One month of running
|
-| | | Compute-Month
|
-+------------------+-----------------------------------+--------------------------+
-| 2 | ALLOCATED\_VM | One month of
allocated |
-| | | Instance
|
-+------------------+-----------------------------------+--------------------------+
-| 3 | IP\_ADDRESS | Quota for a month of
|
-| | | allocated IP
|
-+------------------+-----------------------------------+--------------------------+
-| 4 | NETWORK\_BYTES\_SENT | Quota for 1GB bytes
sent |
-+------------------+-----------------------------------+--------------------------+
-| 5 | NETWORK\_BYTES\_RECEIVED | Quota for 1GB bytes
sent |
-+------------------+-----------------------------------+--------------------------+
-| 6 | VOLUME | Quota for 1 GB of
|
-| | | Volume use for a
month |
-+------------------+-----------------------------------+--------------------------+
-| 7 | TEMPLATE | Quota for 1 GB of
|
-| | | Template use for a
month |
-+------------------+-----------------------------------+--------------------------+
-| 8 | ISO | Quota for 1 GB of
|
-| | | ISO use for a month
|
-+------------------+-----------------------------------+--------------------------+
-| 9 | SNAPSHOT | Quota for 1 GB of
|
-| | | SNAPSHOT use for a
month |
-+------------------+-----------------------------------+--------------------------+
-| 11 | LOAD\_BALANCER\_POLICY | Quota for load
balancer |
-| | | policy month
|
-+------------------+-----------------------------------+--------------------------+
-| 12 | PORT\_FORWARDING\_RULE | Quota for port
forwarding|
-| | | policy month
|
-+------------------+-----------------------------------+--------------------------+
-| 13 | NETWORK\_OFFERING | Quota for Network
|
-| | | Offering for a month
|
-+------------------+-----------------------------------+--------------------------+
-| 14 | VPN\_USERS | Quota for VPN usage
|
-| | | for a month
|
-+------------------+-----------------------------------+--------------------------+
-| 15 | CPU\_CLOCK\_RATE | The tariff for using
|
-| | | 1 CPU i100 MHz clock
|
-+------------------+-----------------------------------+--------------------------+
-| 16 | CPU\_NUMBER | The quota tariff for
|
-| | | using 1 virtual CPU.
|
-+------------------+-----------------------------------+--------------------------+
-| 17 | MEMORY | The quota tariff for
|
-| | | using 1MB RAM size.
|
-+------------------+-----------------------------------+--------------------------+
-
-The quota tariff can be listed using listQuotaTariff API.
-
-quotaTariff: Lists all quota tariff plans
-
-The tariff for each of the above can be set by using the updateQuotaTariff API.
-
-Quota Credits
+.. important::
+
+ The ``VOLUME`` tariff type is measured in ``GB * Month``. Since
+ ``value.size`` is provided in MiB, the activation rule first converts the
+ size to GB by dividing it by ``1024``. The Quota Plugin then
+ multiplies the returned value by the volume size in GB. Therefore, to charge
+ a fixed monthly amount regardless of the volume size, the activation rule
+ must divide the desired charge by the volume size.
+
+To charge **1 monetary unit per volume per month**, configure:
+
+- **Type:** ``VOLUME``
+- **Value:** ``0``
+
+- **Activation rule:**
+
+ .. code:: js
+
+ sizeInGB = value.size / 1024;
+ 1 / sizeInGB
+
+Charging per Allocated Storage
+""""""""""""""""""""""""""""""
+
+To charge **0.2 monetary units per GB of HDD storage per month**, assuming that
+the disk offering has ``hdd`` in its name, configure:
+
+- **Type:** ``VOLUME``
+- **Value:** ``0``
+
+- **Activation rule:**
+
+ .. code:: js
+
+ if (value.diskOffering.name.indexOf('hdd') !== -1) {
+ 0.2
+ } else {
+ 0
+ }
+
+Volume Snapshot Charges
+"""""""""""""""""""""""
+
+Volume snapshot tariffs can be configured similarly to volume tariffs.
+
+To charge a fixed monthly fee per volume snapshot, configure a tariff of type
+``SNAPSHOT`` using the same activation rule shown in
+:ref:`fixed-volume-charge-example`.
+
+To charge 0.2 monetary units according to the actual volume snapshot size in
GB,
+configure:
+
+- **Type:** ``SNAPSHOT``
+- **Value:** ``0.2``
+
+Template and ISO Charges
+""""""""""""""""""""""""
+
+Templates and ISOs can also be charged either with a fixed monthly fee or
+according to their stored size.
+
+To charge 0.2 monetary units according to the actual stored size in GB,
+configure:
+
+- **Type:** ``TEMPLATE`` or ``ISO``
+- **Value:** ``0.2``
+
+
+Network Resources
+^^^^^^^^^^^^^^^^^
+
+Charging for Specific Network Offerings
+"""""""""""""""""""""""""""""""""""""""
+
+To charge **30 monetary units per month** only for networks created from
+offerings containing ``.gold.`` in their name, configure:
+
+- **Type:** ``NETWORK``
+- **Value:** ``0``
+
+- **Activation rule:**
+
+ .. code:: js
+
+ if (value.networkOffering.name.indexOf('.gold.') !== -1) {
+ 30
+ } else {
+ 0
+ }
+
+Charging Public Network Traffic
+"""""""""""""""""""""""""""""""
+
+To charge **0.01 monetary units per GB transferred**, configure two tariffs,
+one for ``NETWORK_BYTES_SENT`` and another for ``NETWORK_BYTES_RECEIVED``:
+
+- **Value:** ``0.01``
+
+.. note::
+
+ ``NETWORK_BYTES_SENT`` and ``NETWORK_BYTES_RECEIVED`` account only for
public
+ traffic that passes through the Virtual Router. Traffic exchanged
exclusively
+ within guest networks or through external networking devices is not included
+ accounted by these usage types.
+
+
+.. _credits-management:
+
+Credits Management
+------------------
+
+The Quota Plugin provides credit management functionality for Accounts.
+Credits can be added or removed for each Account through the ``quotaCredits``
+API, as well as through the graphical interface.
+
+The following additional credit management options are available:
+
+- **Min Balance**: Defines the minimum balance an Account can have. When the
+ Account balance falls below this value, a notification email is sent to the
+ Account.
+
+- **Enforce Quota**: Controls whether the Account is automatically locked when
+ it runs out of credits. Overall enforcement is controlled by the
+ ``quota.enable.enforcement`` global setting.
+
+If an Account is locked due to insufficient credits, adding enough credits to
+raise the balance above the configured minimum balance automatically unlocks
+the Account.
+
+Account balances, credit addition history, and quota consumption can be
monitored
+through the reports described in :ref:`quota-reports`.
+
+
+.. _quota-reports:
+
+Quota Reports
-------------
-The quota credit (quotaCredit) API lets you add or remove quota currency
credits to
-an Account. With this API you can also control the quota enforcement policy at
-Account level. This will enable you to have some Accounts where the quota
policy is
-not enforced. The overall quota enforcement is controlled by the
quota.enable.enforcement
-global setting.
+The Quota Plugin provides reports that allow cloud operators and Account users
+to monitor quota consumption, Account balances, and credit addition history.
These
+reports are available under **Quota → Summary**.
+
+Consumption Tab
+~~~~~~~~~~~~~~~
+
+The **Consumption** tab shows how credits were consumed by cloud resources. The
+following reports are available:
+
+- **Summary**: Displays quota consumption grouped by usage type.
+
+.. figure:: /_static/images/quota-consumption-summary.png
+ :align: center
+ :alt: Consumption summary
+
+|
+
+- **Consumption by resources of a usage type**: Displays quota consumption
broken
+ down by individual resources within a usage type.
+
+.. figure:: /_static/images/quota-consumption-by-resources.png
+ :align: center
+ :alt: Consumption by usage type
+
+|
+
+- **Consumption of a given resource**: Displays detailed quota consumption for
a
+ specific resource.
+
+.. figure:: /_static/images/quota-consumption-of-a-resource.png
+ :align: center
+ :alt: Consumption of a given resource
+
+|
+
+Reports can be displayed in three different modes:
+
+- **Total**: Displays the accumulated consumption over the selected period.
+
+.. figure:: /_static/images/quota-summary-total.png
+ :align: center
+ :alt: Quota consumption reports in a total graph
-In addition to above the quota API lets you can fine tune the alert generation
by specifying
-the quota threshold for each Account. If not explicitly stated, the threshold
is taken as 80%
-of the last deposit.
+|
-Quota Balance
---------------
+- **History**: Displays non-cumulative consumption over time.
-Quota balance API states the start balance and end balance(optional) from a
start date
-to end date (optional).
-
-Quota Statement
-----------------
-
-Quota statement for a period consist of the quota usage under various quota
types for
-the given period from a start date to an end date.
+.. figure:: /_static/images/quota-summary-history.png
+ :align: center
+ :alt: Quota consumption reports in a non-cumulative history graph
-Quota Monthly Statement
-------------------------
+|
-Quota service emails the monthly quota statement for the last month at the
beginning of
-each month. For this service to work properly you need to ensure that the
usage server
-is running.
-
-Quota Alert Management
------------------------
+- **Cumulative History**: Displays cumulative consumption over time.
-Quota module also provides APIs to customize various email Templates that are
used to
-alert Account owners about quota going down below threshold and quota getting
over.
+.. figure:: /_static/images/quota-summary-history-cumulative.png
+ :align: center
+ :alt: Quota consumption reports in a cumulative history graph
+
+|
+
+Balance Tab
+~~~~~~~~~~~
+
+The **Balance** tab displays the quota balance history for an Account.
+
+.. figure:: /_static/images/quota-balance-report.png
+ :align: center
+ :alt: Quota balance report
+
+|
+
+Credits Tab
+~~~~~~~~~~~
+
+The **Credits** tab displays the history of credit additions for
+an Account.
+
+.. figure:: /_static/images/quota-credits-report.png
+ :align: center
+ :alt: Credit history report for an Account
+
+|
+
+Quota Emails
+------------
+
+Emails may be sent by the Quota Plugin to Accounts in three situations:
+
+1. **Low credits** (``QUOTA_LOW``): Sent when an Account's balance drops below
+ the configured minimum balance.
+
+2. **No credits** (``QUOTA_EMPTY``): Sent when an Account runs out of credits.
+
+3. **Account statement** (``QUOTA_STATEMENT``): Sent monthly to summarize the
+ Account's quota consumption.
+
+.. note::
+
+ Although a ``QUOTA_UNLOCK_ACCOUNT`` email type exists, it is not currently
+ implemented.
+
+
+SMTP Configuration
+~~~~~~~~~~~~~~~~~~
+
+.. cssclass:: table-striped table-bordered table-hover
++-----------------------------------------------+-------------------------------------------------------+
+| Global Setting | Description
|
++===============================================+=======================================================+
+| ``quota.usage.smtp.sender`` | Sender address for Quota
notification emails |
+| | (appears in the ``From``
header). |
++-----------------------------------------------+-------------------------------------------------------+
+| ``quota.usage.smtp.host`` | SMTP server host.
|
++-----------------------------------------------+-------------------------------------------------------+
+| ``quota.usage.smtp.port`` | SMTP server port.
|
++-----------------------------------------------+-------------------------------------------------------+
+| ``quota.usage.smtp.useAuth`` | Controls whether SMTP
authentication is used. |
++-----------------------------------------------+-------------------------------------------------------+
+| ``quota.usage.smtp.user`` | SMTP username (used only
when |
+| | ``quota.usage.smtp.useAuth``
is ``true``). |
++-----------------------------------------------+-------------------------------------------------------+
+| ``quota.usage.smtp.password`` | SMTP password (used only
when |
+| | ``quota.usage.smtp.useAuth``
is ``true``). |
++-----------------------------------------------+-------------------------------------------------------+
+| ``quota.usage.smtp.useStartTLS`` | Controls whether StartTLS is
used to secure |
+| | authenticated SMTP
connections. |
++-----------------------------------------------+-------------------------------------------------------+
+| ``quota.usage.smtp.enabledSecurityProtocols`` | Space-separated list of
enabled security |
+| | protocols (for example
``TLSv1 TLSv1.1``). |
+| | Supported values are
``SSLv2Hello``, ``SSLv3``, |
+| | ``TLSv1``, ``TLSv1.1``, and
``TLSv1.2``. |
++-----------------------------------------------+-------------------------------------------------------+
+| ``quota.usage.smtp.connection.timeout`` | SMTP connection timeout, in
seconds. |
++-----------------------------------------------+-------------------------------------------------------+
+
+Managing Email Templates
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Templates for all email types types can be configured through
+the ``quotaEmailTemplateUpdate`` API. This functionality is also available
+through the graphical interface.
+
+.. figure:: /_static/images/quota-email-template.png
+ :align: center
+ :alt: Email template configuration
+
+|
+
+Managing Email Subscriptions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To control whether an Account receives emails of a specific type, use
+the ``quotaConfigureEmail`` API. By default, Accounts that do not have an
+explicit configuration receive all emails.
+
+To list the email subscription settings configured through the API, use the
+``quotaListEmailConfiguration`` API.
-All the above functionality is also available via quota UI plugin.
