+++ /dev/null
-/*
- * Copyright 2011 GRNET S.A. All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or
- * without modification, are permitted provided that the following
- * conditions are met:
- *
- * 1. Redistributions of source code must retain the above
- * copyright notice, this list of conditions and the following
- * disclaimer.
- *
- * 2. Redistributions in binary form must reproduce the above
- * copyright notice, this list of conditions and the following
- * disclaimer in the documentation and/or other materials
- * provided with the distribution.
- *
- * THIS SOFTWARE IS PROVIDED BY GRNET S.A. ``AS IS'' AND ANY EXPRESS
- * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
- * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
- * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL GRNET S.A OR
- * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
- * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
- * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
- * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
- * POSSIBILITY OF SUCH DAMAGE.
- *
- * The views and conclusions contained in the software and
- * documentation are those of the authors and should not be
- * interpreted as representing official policies, either expressed
- * or implied, of GRNET S.A.
- */
-
-/**
- * @opt operations
- * @opt attributes
- * @opt operations
- * @hidden
- */
-class UMLOptions {}
-
-/**
- * @assoc 1 - n ServiceTemplate
- * @assoc 1 - n ServiceItem
- */
-public class Entity {
- public String name;
- public float credits;
-}
-
-public enum EntityType {
- User, Group
-}
-
-public class User extends Entity {
-}
-
-/**
- * @composed m - n User
- * @assoc 0 - n Group
- */
-public class Group extends Entity{}
-
-/**
- * @assoc m - n Group
- * @composed n - m User
- */
-public class Organization extends Entity {
-}
-
-/**
- * @assoc 1 - n ServiceItem
- * @has n - 1 ResourceType
- */
-public class ServiceTemplate {
- public String name;
-}
-
-public class ServiceItem {
- public String url;
-}
-
-/**
- * @assoc n - 1 ServiceTemplate
- */
-public class Action{}
-
-/**
- * @assoc n - 1 Action
- * @assoc n - 1 ServiceTemplate
- * @assoc n - 1 EntityType
- */
-public class DefaultPermission {}
-
-/**
- * @has n - 1 Entity
- * @composed n - 1 Action
- * @composed n - 1 ServiceItem
- */
-public class Permission{}
-
-
-/**
- * @assoc n - 1 Entity
- * @assoc n - 1 ServiceItem
- */
-public class Limit{
- public String value;
-}
-
-/**
- * @assoc n - 1 ServiceItem
- * @assoc n - 1 Entity
- */
-public class Bill {
- public float cost;
- public Date date;
-}
-
-public class SynnefoVM extends ServiceItem {}
-public class PithosFile extends ServiceItem{}
-public class SaaSVM extends SynnefoVM {}
-
-
-public enum ResourceType {
- CPU, RAM, DiskSpace, Bandwidth, License, Network
-}
-
-/**
- * @assoc n - 1 EntityType
- * @assoc n - 1 ServiceTemplate
- */
-public class DefaultLimit {
- public float limit;
-}
-
-
The development guide includes descriptions of the APIs and extention points
offered by Aquarium. It also includes design and development setup information.
+Overall architecture
+--------------------
+
+
+
The accounting system
----------------------
As with the rest of the Aquarium, the architecture is open-ended: the accounting
system does not know in advance which services it supports or what resources
are being offered. The configuration of the accounting system is done
-using a Domain Specific Language described below.
+using a Domain Specific Language (DSL) described below.
Data exchange with external systems is done through events, which are
persisted to an *immutable log*.
+The accounting system is a generic event-processing engine that is configured by a
+DSL. The DSL is mostly based on the
+`YAML <http://en.wikipedia.org/wiki/Yaml>`_
+format. The DSL supports limited algorithm definitions through integration of the Javascript language as defined below.
+
Glossary of Entities
^^^^^^^^^^^^^^^^^^^^
- *Credit*: A credit is the unit of currency used in Aquarium. It may or may not
correspond to real money.
-- *Raw Event*: A raw event is generated from an external source and are permanently
- appended in an immutable event log. A raw event carries information about changes
- in an external system that could affect the status of a user's wallet.
-- *AccountingEvent*: An accounting event is the result of processing one or more raw
- events, and is the sole input to the accounting system.
-- *AccountingEntry*: An accounting entry is the result of processing one accounting
- event and is what gets stored to the user's wallet.
- *Resource*: A resource represents an entity that can be charged for its usage. The
- currently charged resources are: Time of VM usage, bytes uploaded and downloaded and
- bytes used for storage
+ currently charged resources are: Time of VM usage, bytes uploaded and downloaded and bytes used for storage
+- *Resource Event*: A resource event is generated from an external source and are permanently appended in an immutable event log. A raw event carries information about changes in an external system that could affect the status of a user's wallet.
+- *AccountingEntry*: An accounting entry is the result of processing a resource event and is what gets stored to the user's wallet.
- *Price List*: A price list contains information of the cost of a resource.
A pricelist is only applied within a specified time frame.
-- *Policy*: A policy specifies the way the charging calculation is done. It can be vary
- depending on resource usage, time of raw event or other information.
-- *Agreement*: An agreement associates pricelists with policies. An agreement
- is assigned to one or more credit holders.
-
-Common syntax
-^^^^^^^^^^^^^
-
-The accounting system is a generic event-processing engine that is configured by a
-DSL. The DSL is split in two parts, one for configuring the crediting part
-of accounting and one for configuring who credits are debitted to user accounts.
-The DSL is mostly based on the
-`YAML <http://en.wikipedia.org/wiki/Yaml>`_ format. The DSL supports limited
-algorithm definitions through a simple imperative language as defined below.
-
-
-The following parts are the same for both languages, except if otherwise noted.
-
-Implicit variables
-~~~~~~~~~~~~~~~~~~
-
-Implicit variables are placeholders that are assigned a value at evaluation
-time. Variables are always bound to a resource declaration within a policy.
-The following implicit values are supported:
-
-- ``price``: Denotes the price for the designated resource in the applicable agreement
-- ``volume``: Denotes the runtime usage of the designated resource
-
-
-Operators
-~~~~~~~~~
-
-- Conditionals: ``if...then...elsif...else...end`` Conditional decisions.
-- Comparison: ``gt, lt``: ``>`` and ``<``
+- *Algorithm*: An algorithm specifies the way the charging calculation is done. It can be vary depending on resource usage, time of raw event or other information.
+- *Credit Plan*: Defines a periodic operation of refiling a user's wallet with a
+ configurable amount of credits.
+- *Agreement*: An agreement associates pricelists with algorithms and credit
+ plans. An agreement is assigned to one or more users/credit holders.
Time frames
-~~~~~~~~~~~
+^^^^^^^^^^^
Time frames allow the specification of applicability periods for policies,
pricelists and agreements. A timeframe is by default continuous and has a
start: "00 15 * * Sat"
end: "00 15 * * Sun"
+Resources
+^^^^^^^^^
-.. toctree::
+A resource represents an entity that can be charged for.
+
+The DSL does not assume a fixed set of resource types and is extensible to any
+number of resources. The default set of resources that the DSL supports
+are the following:
+
+- ``vmtime``: Time a specific VM is operating
+- ``diskspace``: Space on disk being used for storing data
+- ``bandwidthup``: Bandwidth used for uploading data
+- ``bandwidthdown``: Bandwidth used for downloading data
+
+Price lists
+^^^^^^^^^^^
+
+A price list defines the prices applicable for a resource within a validity
+period. Prices are attached to resource types and denote the policies that
+should be deducted from an entity's wallet in response to the entity's resource
+usage within a given charging period (currently, a month). The format is the
+following:
+
+.. code-block:: yaml
+
+ pricelist: # Pricelist structure definition
+ name: apricelist # Name for the price list, no spaces, must be unique
+ [extends: anotherpl] # [Optional] Inheritance operation: all optional fields
+ # are inherited from the named pricelist
+ bandwidthup: # Price for used upstream bandwidth per MB
+ bandwidthdown: # Price for used downstream bandwidth per MB
+ vmtime: # Price for time
+ diskspace: # Price for used diskspace, per MB
+ applicable:
+ [see Timeframe format]
+
+Algorithms
+^^^^^^^^^^
+
+An algorithm specifies the algorithm used to perform the cost calculation, by
+combining the reported resource usage with the applicable pricelist. As opposed
+to price lists, policies define behaviours (algorithms), which have certain
+validity periods. Algorithms can either be defined inline or referenced from
+the list of defined algorithms.
+
+.. code-block:: yaml
+
+ algorithm:
+ name: default
+ bandwidthup: {price} times {volume}
+ bandwidthdown: {price} times {volume}
+ vmtime: {price} times {volume}
+ diskspace: {price} times {volume}
+ applicable:
+ [see Timeframe format]
+
+
+Credit Plans
+^^^^^^^^^^^^
+
+
+
+Agreements
+^^^^^^^^^^
+
+An agreement is the result of combining a policy with a pricelist. As the
+accounting DSL's main purpose is to facilitate the construction of agreements
+(which are then associated to entities), the agreement is the centerpiece of
+the language. An agreement is defined in full using the following template:
+
+.. code-block:: yaml
+
+ agreement:
+ name: someuniqname # Unique name for
+ extends: other # [opt] name of inhereted agreement
+ pricelist: plname # Name of declared pricelist
+ resourse: value # [opt] Overiding of price for resource
+ policy: polname # Name of declared policy
+ resourse: value # [opt] Overiding of algorithm for resourse
+
+**Consistency requirements:**
+
+- If a ``pricelist`` or ``policy`` name has not been specified, all prices or
+ algorithms for the declared resources must be defined in either the processed
+ ``agreement`` or a parent ``agreement``.
+
+The charging algorithm
+^^^^^^^^^^^^^^^^^^^^^^
- debitdsl
- creditdsl
-Usage Examples
-^^^^^^^^^^^^^^
+Examples
+^^^^^^^^^
.. toctree::
unicase
Revision Description
================== ================================
0.1 (Nov 2, 2011) Initial release. Credit and debit policy descriptions
+0.2 (Feb 23, 2012) Update definitions, remove company use case
================== ================================
projects / aquarium / commitdiff