Documentation for policy enforcement

Partially Implements blueprint policy-enforcement-point

Change-Id: I10b9567d874812b775544904bd85906390b337d4

doc/source/articles/policy_enf.rst

@@ -0,0 +1,120 @@
+=================================
+Murano Policy Enforcement Example
+=================================
+
+Introduction
+============
+As a part of the policy guided fulfillment, we need to enforce policies on the Murano environment deployment.
+If the policy enforcement failed, deployment fails. Policies are defined and evaluated in the Congress_ project.
+The policy language for Congress is Datalog. The congress policy consists of Datalog rules and facts.
+The cloud administrator defines policies in Congress. Examples of such policies:
+
+* all VM instances must have at least 2GB of RAM
+* all Apache server instances must have given certified version
+* data placement policy: all DB instances must be deployed at given geo location (enforcing some law restriction on data placement)
+
+These policies are evaluated over data in the form of tables (Congress data structures). A deployed Murano environment must be
+decomposed to Congress data structures. The decomposed environment is sent to congress for simulation. Congress simulates
+whether the resulting state does not violate any defined policy. Deployment is aborted in case of policy violation.
+Murano uses two predefined policies in Congress:
+
+* *murano_system* contains rules and facts of policies defined by cloud admin.
+* *murano* contains only facts/records reflecting resulting state after deployment of an environment.
+
+Records in the *murano* policy are queried by rules from the *murano_system* policy. The congress simulation does not create any
+records in the *murano* policy. Congress will only give feedback on whether the resulting state violates the policy or not.
+
+.. _Congress: https://wiki.openstack.org/wiki/Congress
+
+Example
+=======
+In this example we will
+    #. Set-up murano to perform validation using congress engine.
+    #. Create rules that prohibit creating VM instances with flavor with more than 2048 MB ram.
+
+Setup
+-----
+#. Enable policy enforcement in murano
+
+    - edit */etc/murano/murano.conf*:
+
+    .. code-block:: ini
+
+        [engine]
+        # Enable model policy enforcer using Congress (boolean value)
+        enable_model_policy_enforcer = true
+    ..
+
+    - restart murano-engine
+
+#. Create **murano** and **murano_system** policies
+
+    - Check if policies **murano** and **murano_system** were created by datasource driver:
+        ``congress policy list``
+    - If there are no **murano** and **murano_system** policies then create them by performing following commands:
+
+    .. code-block:: console
+
+        (openstack) congress policy create murano
+        (openstack) congress policy create murano_system
+    ..
+
+    .. note:: Commands are performed in console started by ``openstack`` command
+
+Example rules
+-------------
+
+#. Create ``predeploy_errors`` rule
+
+    Policy validation engine checks rule ``predeploy_errors`` and rules referenced inside this rule are evaluated by congress engine.
+
+    We create example rule which references ``flavor_ram`` rule we create afterwards. It disables flavors with ram higher than 2048 MB and constructs message returned to the user in *msg* variable.
+
+    .. code-block:: console
+
+        predeploy_errors(eid, obj_id, msg) :-
+           murano:objects(obj_id, eid, type),
+           murano:properties(obj_id, "flavor", flavor_name),
+           flavor_ram(flavor_name, ram),
+           gt(ram, 2048),
+           murano:properties(obj_id, "name", obj_name),
+           concat(obj_name, ": instance flavor has RAM size over 2048MB", msg)
+    ..
+
+    Use this command to create the rule:
+
+    .. code-block:: console
+
+      congress policy rule create murano_system "predeploy_errors(eid, obj_id, msg) :- murano:objects(obj_id, eid, type), murano:properties(obj_id, \"flavor\", flavor_name), flavor_ram(flavor_name, ram), gt(ram, 2048), murano:properties(obj_id, \"name\", obj_name), concat(obj_name, \": instance flavor has RAM size over 2048MB\", msg)"
+    ..
+
+    In this example we used data from policy **murano** which is represented by ``murano:properties``. There are stored rows with decomposition of model representing murano application. We also used built-in functions of congress - ``gt`` - greater-than, and ``concat`` which joins two strings into variable.
+
+#. Create ``flavor_ram`` rule
+
+    We create the rule that resolves parameters of flavor by flavor name and returns *ram* parameter. It uses rule *flavors* from *nova* policy. Data in this policy is filled by *nova* datasource driver.
+
+    Use this command to create the rule:
+
+    .. code-block:: console
+
+        congress policy rule create murano_system "flavor_ram(flavor_name, ram) :- nova:flavors(id, flavor_name, cpus, ram)"
+    ..
+
+Example rules in murano app deployment
+--------------------------------------
+
+#. Create environment with simple application
+
+    - Choose Git application from murano applications
+    - Create with **"m1.medium"** instance flavor which uses 4096MB so validation will fail
+
+    .. image:: new-instance.png
+
+
+#. Deploy environment
+
+    - Environment is in Status: **Deploy FAILURE**
+    - Check deployment log:
+
+    .. image:: deployment-log.png

doc/source/articles/policy_enf_dev.rst

@@ -0,0 +1,161 @@
+===========================================
+Murano Policy Enforcement - Developer Guide
+===========================================
+
+This document describes internals of murano policy enforcement.
+
+Model Decomposition
+-------------------
+
+Models of Murano applications are transformed to set of rules that are processed by congress. This represent data for policy validation.
+
+There are several "tables" created in murano policy for different kind of rules:
+
+- ``murano:objects(environment_id, object_id, type_name)``
+- ``murano:properties(object_id, property_name, property_value)``
+- ``murano:relationships(source, target, name)``
+- ``murano:parent_types(object_id, parent_name)``
+- ``murano:states(environment_id, state)``
+
+``murano:objects(environment_id, object_id, type_name)``
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+This rule is used for representation of all objects in murano model (environment, applications, instances, ...).
+Value of property ``type`` is used as ``type_name`` parameter:
+
+.. code-block:: yaml
+
+    name: wordpress-env
+    '?': {type: io.murano.Environment, id: 83bff5ac}
+    applications:
+    - '?': {id: e7a13d3c, type: io.murano.databases.MySql}
+..
+
+Transformed to these rules:
+
+- ``murano:objects+("83bff5ac", "83bff5ac", "io.murano.Environment")``
+- ``murano:objects+("83bff5ac", "e7a13d3c", "io.murano.databases.MySql")``
+
+.. note:: In case of rule for environment ``environment_id``, ``object_id`` are the same.
+
+
+``murano:properties(object_id, property_name, property_value)``
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Each object can have properties. In this example we have application with one property:
+
+.. code-block:: yaml
+
+    applications:
+    - '?': {id: e7a13d3c, type: io.murano.databases.MySql}
+    database: wordpress
+..
+
+Transformed to this rule:
+
+- ``murano:properties+("e7a13d3c", "database", "wordpress")``
+
+Inner properties are also supported using dot notation:
+
+.. code-block:: yaml
+
+    instance:
+    '?': {id: 825dc61d, type: io.murano.resources.LinuxMuranoInstance}
+    networks:
+      useFlatNetwork: false
+..
+
+Transformed to this rule:
+
+- ``murano:properties+("825dc61d", "networks.useFlatNetwork", "False")``
+
+If model contains list of values it is represented as set of multiple rules:
+
+.. code-block:: yaml
+
+    instances:
+    - '?': {id: be3c5155, type: io.murano.resources.LinuxMuranoInstance}
+    networks:
+      customNetworks: [10.0.1.0, 10.0.2.0]
+..
+
+Transformed to these rules:
+
+- ``murano:properties+("be3c5155", "networks.customNetworks", "10.0.1.0")``
+- ``murano:properties+("be3c5155", "networks.customNetworks", "10.0.2.0")``
+
+There is one special property on environment for tenant_id:
+
+- ``murano:properties+("...", "tenant_id", "123")``
+
+``murano:relationships(source, target, name)``
+""""""""""""""""""""""""""""""""""""""""""""""
+
+Murano app models can contain references to other applications. In this example WordPress application references MySQL in property "database":
+
+.. code-block:: yaml
+
+    applications:
+    - '?':
+        id: 0aafd67e
+        type: io.murano.databases.MySql
+    - '?':
+        id: 50fa68ff
+        type: io.murano.apps.WordPress
+      database: 0aafd67e
+..
+
+Transformed to this rule:
+
+- ``murano:relationships+("50fa68ff", "0aafd67e", "database")``
+
+.. note:: For property "database" we do not create rule ``murano:properties+``.
+
+Also if we define inner object inside other object, they will have relationship between them:
+
+.. code-block:: yaml
+
+    applications:
+    - '?':
+        id: 0aafd67e
+        type: io.murano.databases.MySql
+      instance:
+        '?': {id: ed8df2b0, type: io.murano.resources.LinuxMuranoInstance}
+..
+
+Transformed to this rule:
+
+- ``murano:relationships+("0aafd67e", "ed8df2b0", "instance")``
+
+``murano:parent_types(object_id, parent_name)``
+"""""""""""""""""""""""""""""""""""""""""""""""
+
+Each object in murano has class type and these classes can inherit from one or more parents:
+
+e.g. ``LinuxMuranoInstance`` > ``LinuxInstance`` > ``Instance``
+
+So this model:
+
+.. code-block:: yaml
+
+    instances:
+    - '?': {id: be3c5155, type: LinuxMuranoInstance}
+..
+
+Transformed to these rules:
+
+- ``murano:objects+("...", "be3c5155", "LinuxMuranoInstance")``
+- ``murano:parent_types+("be3c5155", "LinuxMuranoInstance")``
+- ``murano:parent_types+("be3c5155", "LinuxInstance")``
+- ``murano:parent_types+("be3c5155", "Instance")``
+
+.. note:: Type of object is also repeated among parent types (``LinuxMuranoInstance`` in example) for easier handling of user-created rules.
+
+.. note:: If type inherits from more than one parent and those parents inherit from one common type, ``parent_type`` rule is included only once for common type.
+
+``murano:states(environment_id, state)``
+""""""""""""""""""""""""""""""""""""""""
+
+Currently only one record for environment is created:
+
+- ``murano:states+("uugi324", "PENDING")``

doc/source/articles/policy_enf_index.rst

@@ -0,0 +1,9 @@
+=========================
+Murano Policy Enforcement
+=========================
+
+.. toctree::
+   :maxdepth: 2
+
+   policy_enf
+   policy_enf_dev

doc/source/index.rst

@@ -64,6 +64,7 @@ contribute to the project.
    murano_pl/murano_pl_index
    articles/dynamic_ui
    articles/workflow
+   articles/policy_enf_index
 
 
 **Tutorials**