diff --git a/doc/source/articles/client.rst b/doc/source/articles/client.rst deleted file mode 100644 index b64879c2..00000000 --- a/doc/source/articles/client.rst +++ /dev/null @@ -1,220 +0,0 @@ -.. - Copyright 2015 Mirantis, Inc. - - Licensed 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. - -.. _client: - -============= -Murano client -============= - -Module python-muranoclient comes with CLI *murano* utility, that interacts with -Murano application catalog - -Installation -============ - -To install latest murano CLI client run the following command in your shell:: - - pip install python-muranoclient - -Alternatively you can checkout the latest version from -https://git.openstack.org/cgit/openstack/python-muranoclient - - -Using CLI client -================ - -In order to use the CLI, you must provide your OpenStack username, password, -project name or id, and auth endpoint. Use the corresponding arguments -(``--os-username``, ``--os-password``, ``--os-project-name`` or -``--os-project-id``, ``--os-auth-url`` and ``--murano-url``) or -set corresponding environment variables:: - - export OS_USERNAME=user - export OS_PASSWORD=password - export OS_TENANT_NAME=tenant - export OS_AUTH_URL=http://auth.example.com:5000/v2.0 - export MURANO_URL=http://murano.example.com:8082/ - -Once you've configured your authentication parameters, you can run ``murano -help`` to see a complete listing of available commands and arguments and -``murano help `` to get help on specific subcommand. - - -Bash completion -=============== - -To get the latest bash completion script download `murano.bash_completion`_ -from the source repository and add it to your completion scripts. - - -.. _murano.bash_completion: https://git.openstack.org/cgit/openstack/python-muranoclient/plain/tools/murano.bash_completion - - -Listing currently installed packages -==================================== - -To get list of currently installed packages run:: - - murano package-list - -To show details about specific package run:: - - murano package-show - -Importing packages in Murano -============================ - -``package-import`` subcommand can install packages in several different ways: - * from a local file - * from a http url - * from murano app repository - -When creating a package you can specify it's categories with -``-c/--categories`` and set it's publicity with ``--is-public`` - -To import a local package run:: - - murano package-import /path/to/package.zip - -To import a package from http url run:: - - murano package-import http://example.com/path/to/package.zip - -And finally you can import a package from Murano repository. To do so you have -to specify base url for the repository with ``--murano-repo-url`` or with the -corresponding ``MURANO_REPO_URL`` environment variable. After doing so, -running:: - - murano --murano-repo-url="http://example.com/" package-import io.app.foo - -would access specified repository and download app ``io.app.foo`` from it's -app directory. This option supports an optional ``--package-version`` -parameter, that would instruct murano client to download package of a -specific version. - -``package-import`` inspects package requirements specified in the package's -manifest under `Require` section and attempts to import them from -Murano Repository. -``package-import`` also inspects any image prerequisites, mentioned in the -`images.lst` file in the package. If there are any image requirements client -would inspect images already present in the image database. Unless image with -the specific name and hash is present client would attempt to download it. - -For more info about specifying images and requirements for the package see -package creation docs: :ref:`step-by-step`. - -If any of the packages, being installed is already registered in Murano, client -would ask you what do do with it. You can specify the default action with -``--exists-action``, passing `s` for skip, `u` for update, and `a` for abort. - -Importing bundles of packages in Murano -======================================= - -``bundle-import`` subcommand can install bundles of packages in several -different ways: - * from a local file - * from a http url - * from murano app repository - -When creating a bundle you can set it's publicity with ``--is-public`` - -To import a local bundle run:: - - murano bundle-import /path/to/bundle - -To import a bundle from http url run:: - - murano bundle-import http://example.com/path/to/bundle - -To import a bundle from murano repository run:: - - murano bundle-import bundle_name - -.. note:: - - When importing from a local file packages would first be searched in a - directory, relative to the directory containing the bundle file itself. - This is done to facilitate installing bundles in an environment with no - access to the repository itself. - -Deleting packages from murano -============================= - -To delete a package run:: - - murano package-delete - - -Downloading package file -======================== - -Running:: - - murano package-download > file.zip - -would download the zip archive with specified package - -Creating a package -================== - -Murano client is able to create application packages from package source -files/directories. To find out more about this command run:: - - murano help package-create - -This command is useful, when application package files are spread across -several directories, and for auto-generating packages from heat templates. -For more info about package composition please see package creation docs: -:ref:`step-by-step`. - - -Managing Environments -===================== - -It is possible to create/update/delete environments with following commands:: - - murano environment-create - murano environment-delete - murano environment-list - murano environment-rename - murano environment-show - -You can get list of deployments for environment with:: - - murano deployment-list - -Managing Categories -=================== - -It is possible to create/update/delete categories with following commands:: - - murano category-create - murano category-delete [ ...] - murano category-list - murano category-show - -Managing environment templates -============================== - -It is possible to manage environment templates with following commands:: - - murano env-template-create - murano env-template-add-app - murano env-template-del-app - murano env-template-delete - murano env-template-list - murano env-template-show - murano env-template-update diff --git a/doc/source/articles/policy_enf.rst b/doc/source/articles/policy_enf.rst deleted file mode 100644 index 82308f22..00000000 --- a/doc/source/articles/policy_enf.rst +++ /dev/null @@ -1,93 +0,0 @@ -================================= -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 create rules that prohibit creating VM instances with flavor with more than 2048 MB ram. - -Prior creating rules your OpenStack installation has to be configured as described in :ref:`policyenf_setup`. - -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, pid, type), - murano:objects(eid, tid, "io.murano.Environment"), - murano:connected(eid, pid), - 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, pid, type), murano:objects(eid, tid, \"io.murano.Environment\"), murano:connected(eid, pid), 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 \ No newline at end of file diff --git a/doc/source/articles/policy_enf_dev.rst b/doc/source/articles/policy_enf_dev.rst deleted file mode 100644 index 19bde568..00000000 --- a/doc/source/articles/policy_enf_dev.rst +++ /dev/null @@ -1,191 +0,0 @@ -=========================================== -Murano Policy Enforcement - Developer Guide -=========================================== - -.. _policyenf_dev: - -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(object_id, parent_id, type_name)`` -- ``murano:properties(object_id, property_name, property_value)`` -- ``murano:relationships(source, target, name)`` -- ``murano:connected(source, target)`` -- ``murano:parent_types(object_id, parent_type_name)`` -- ``murano:states(environment_id, state)`` - -``murano:objects(object_id, parent_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", "tenant_id", "io.murano.Environment")`` -- ``murano:objects+("83bff5ac", "e7a13d3c", "io.murano.databases.MySql")`` - -.. note:: The owner of the environment is a project - - -``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")`` - -``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")`` - -There are special relationships "services" from the environment to its applications: - -- ``murano:relationships+("env_id", "app_id", "services")`` - - -``murano:connected(source, target)`` -"""""""""""""""""""""""""""""""""""" - -This table stores both direct and indirect connections between instances. It is derived from the ``murano:relationships``: - -.. code-block:: yaml - - applications: - - '?': - id: 0aafd67e - type: io.murano.databases.MySql - instance: - '?': {id: ed8df2b0, type: io.murano.resources.LinuxMuranoInstance} - - '?': - id: 50fa68ff - type: io.murano.apps.WordPress - database: 0aafd67e -.. - -Transformed to rules: - -- ``murano:connected+("50fa68ff", "0aafd67e")`` # WordPress to MySql -- ``murano:connected+("50fa68ff", "ed8df2b0")`` # WordPress to LinuxMuranoInstance -- ``murano:connected+("0aafd67e", "ed8df2b0")`` # MySql to LinuxMuranoInstance - - -``murano:parent_types(object_id, parent_name)`` -""""""""""""""""""""""""""""""""""""""""""""""" - -Each object in murano has a 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")`` diff --git a/doc/source/articles/policy_enf_index.rst b/doc/source/articles/policy_enf_index.rst deleted file mode 100644 index a819e8fb..00000000 --- a/doc/source/articles/policy_enf_index.rst +++ /dev/null @@ -1,11 +0,0 @@ -========================= -Murano Policy Enforcement -========================= - -.. toctree:: - :maxdepth: 2 - - policy_enf - policy_enf_modify - policy_enf_setup - policy_enf_dev \ No newline at end of file diff --git a/doc/source/articles/policy_enf_modify.rst b/doc/source/articles/policy_enf_modify.rst deleted file mode 100644 index cd51d058..00000000 --- a/doc/source/articles/policy_enf_modify.rst +++ /dev/null @@ -1,74 +0,0 @@ -======================================================= -Murano Policy Based Modification of Environment Example -======================================================= - -Introduction -============ -Goal is to be able to define modification of an environment by Congress policies prior -deployment. This allows to add components (for example monitoring), change/set properties -(for example to enforce given zone, flavors, ...) and relationships into environment, -so modified environment is after that deployed. - -Example Use Cases: - -* install monitoring agent on each VM instance (adding component with the agent and creating relationship between - agent and instance) -* all Apache server instances must have given certified version (version property is set on all Apache applications - within environment to given version) - -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 needs to be modified. In case that modifications of deployed environment are needed congress returns -list of actions which needs to be performed on given environment prior the deployment. Actions and its parameters are returned -from congress in YAML format. - -Example of action specification returned from congress: - -* set ``keyname`` property on instance identified by ``object_id`` to value ``production-key`` - - .. code-block:: yaml - - set-property: {object_id: c46770dec1db483ca2322914b842e50f, prop_name: keyname, value: production-key} - .. - -Administrator can use above one line action specification as output of congress rules. This action specification -is parsed in murano. Given action class is loaded. Action instance is created. Parsed parameters are supplied to action -``__init__`` method. Then action is performed on given environment (``modify`` method). - -Example -======= -In this example assume that we are in production environment. Administrator needs to enforce that all VM instances -will be deployed with secure key pair used for production environment. - -Prior creating rules your OpenStack installation has to be configured as described in :ref:`policyenf_setup`. - -Example rules -------------- - -#. Create ``predeploy_modify`` rule - - Policy validation engine checks rule ``predeploy_modify`` and rules referenced inside this rule are evaluated by congress engine. - - .. code-block:: console - - predeploy_modify(eid, obj_id, action) :- - murano:objects(obj_id, pid, type), - murano:objects(eid, tid, "io.murano.Environment"), - murano:connected(eid, pid), - murano:properties(obj_id, "keyname", kn), - concat("set-property: {object_id: ", obj_id, first_part), - concat(first_part, ", prop_name: keyname, value: production-key}", action) - .. - - Use this command to create the rule: - - .. code-block:: console - - congress policy rule create murano_system 'predeploy_modify(eid, obj_id, action):-murano:objects(obj_id, pid, type), murano_env_of_object(obj_id, eid), murano:properties(obj_id, "keyname", kn), concat("set-property: {object_id: ", obj_id, first_part), concat(first_part, ", prop_name: keyname, value: production-key}", action)' - .. - - Key pair ``production-key`` must exists or change it to any existing key pair. - -#. Deploy environment and check modification - - Deploy any environment and check that instances within the environment were deployed with the key pair specified above. diff --git a/doc/source/articles/policy_enf_setup.rst b/doc/source/articles/policy_enf_setup.rst deleted file mode 100644 index 7aa349b1..00000000 --- a/doc/source/articles/policy_enf_setup.rst +++ /dev/null @@ -1,123 +0,0 @@ -===================================== -Murano Policy Enforcement Setup Guide -===================================== - -.. _policyenf_setup: - -Introduction ------------- - -Before policy enforcement feature will be used, it has to be configured. It has -to be enabled in Murano configuration, and Congress has to have created policy -and rules used during policy evaluation. - -This document does not cover Murano and Congress configuration options useful -for Murano application deployment (e.g., DNS setup, floating IPs, ...). - -Setup ------ - -This setup uses *openstack* command. You can use copy-paste for commands. - -If you are using DevStack installation, you can setup environment using -following command. - - .. code-block:: ini - - source devstack/openrc admin admin - .. - -#. **Murano** - - Enable policy enforcement in Murano: - - - edit */etc/murano/murano.conf* to enable **enable_model_policy_enforcer** - option: - - .. code-block:: ini - - [engine] - # Enable model policy enforcer using Congress (boolean value) - enable_model_policy_enforcer = true - .. - - - restart murano-engine - -#. **Congress** - - Policy enforcement uses following policies: - - - **murano** policy - - Policy is created by Congress' murano datasource driver, which is part of - Congress. It has to be configured for the OpenStack project (tenant) where - Murano application will be deployed. Datasource driver retrieves deployed - Murano environments and populates Congress' murano policy tables - (:ref:`policyenf_dev`). - - Following commands removes existing **murano** policy, and creates new - **murano** policy configured for project *demo*. - - .. code-block:: console - - . ~/devstack/openrc admin admin # if you are using devstack, otherwise you have to setup env manually - - # remove default murano datasource configuration, because it is using 'admin' project. We need 'demo' project to be used. - openstack congress datasource delete murano - openstack congress datasource create murano murano --config username="$OS_USERNAME" --config tenant_name="demo" --config password="$OS_PASSWORD" --config auth_url="$OS_AUTH_URL" - .. - - - **murano_system** policy - Policy holds user defined rules for policy enforcement. Rules typically - uses tables from other policies (e.g., murano, nova, keystone, ...). - Policy enforcement expects *predeploy_errors* table here which is created - by creating **predeploy_errors** rules. - - Following command creates **murano_system** rule - - .. code-block:: console - - # create murano_system policy - openstack congress policy create murano_system - - # resolves objects within environment - openstack congress policy rule create murano_system 'murano_env_of_object(oid,eid):-murano:connected(eid,oid), murano:objects(eid,tid,"io.murano.Environment")' - .. - - - **murano_action** policy with internal management rules - Following rules are used internally in policy enforcement request. - These rules are stored in dedicated **murano_action** policy which is - created here. - They are important for case when an environment is deployed again. - - .. code-block:: console - - # create murano_action policy - openstack congress policy create murano_action --kind action - - # register action deleteEnv - openstack congress policy rule create murano_action 'action("deleteEnv")' - - # states - openstack congress policy rule create murano_action 'murano:states-(eid, st) :- deleteEnv(eid), murano:states( eid, st)' - - # parent_types - openstack congress policy rule create murano_action 'murano:parent_types-(tid, type) :- deleteEnv(eid), murano:connected(eid, tid),murano:parent_types(tid,type)' - openstack congress policy rule create murano_action 'murano:parent_types-(eid, type) :- deleteEnv(eid), murano:parent_types(eid,type)' - - # properties - openstack congress policy rule create murano_action 'murano:properties-(oid, pn, pv) :- deleteEnv(eid), murano:connected(eid, oid), murano:properties(oid, pn, pv)' - openstack congress policy rule create murano_action 'murano:properties-(eid, pn, pv) :- deleteEnv(eid), murano:properties(eid, pn, pv)' - - # objects - openstack congress policy rule create murano_action 'murano:objects-(oid, pid, ot) :- deleteEnv(eid), murano:connected(eid, oid), murano:objects(oid, pid, ot)' - openstack congress policy rule create murano_action 'murano:objects-(eid, tnid, ot) :- deleteEnv(eid), murano:objects(eid, tnid, ot)' - - # relationships - openstack congress policy rule create murano_action 'murano:relationships-(sid, tid, rt) :- deleteEnv(eid), murano:connected(eid, sid), murano:relationships( sid, tid, rt)' - openstack congress policy rule create murano_action 'murano:relationships-(eid, tid, rt) :- deleteEnv(eid), murano:relationships(eid, tid, rt)' - - # connected - openstack congress policy rule create murano_action 'murano:connected-(tid, tid2) :- deleteEnv(eid), murano:connected(eid, tid), murano:connected(tid,tid2)' - openstack congress policy rule create murano_action 'murano:connected-(eid, tid) :- deleteEnv(eid), murano:connected(eid,tid)' - .. diff --git a/doc/source/index.rst b/doc/source/index.rst index 0b536066..dc251faf 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -122,7 +122,6 @@ Miscellaneous :maxdepth: 1 articles/workflow - articles/policy_enf_index **Tutorials** @@ -133,12 +132,6 @@ Miscellaneous image_builders/index articles/test_docs -**Client** - -.. toctree:: - :maxdepth: 1 - - articles/client **Guidelines**