openstack/deb-murano
Code Issues Proposed changes

Merge "[Murano Docs] Remove articles"

Browse Source
This commit is contained in:
Jenkins 2016-04-17 20:02:13 +00:00 committed by Gerrit Code Review
commit a960148e91
7 changed files with 0 additions and 719 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

220
doc/source/articles/client.rst
View File

@ -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 <sub_command>`` 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 <PKG_ID>
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 <PKG_ID>
Downloading package file
========================
Running::
murano package-download <PKG_ID> > 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 <NAME>
murano environment-delete <NAME_OR_ID>
murano environment-list
murano environment-rename <OLD_NAME_OR_ID> <NEW_NAME>
murano environment-show <NAME_OR_ID>
You can get list of deployments for environment with::
murano deployment-list <NAME_OR_ID>
Managing Categories
===================
It is possible to create/update/delete categories with following commands::
murano category-create <NAME>
murano category-delete <ID> [<ID> ...]
murano category-list
murano category-show <ID>
Managing environment templates
==============================
It is possible to manage environment templates with following commands::
murano env-template-create <NAME>
murano env-template-add-app <NAME> <FILE>
murano env-template-del-app <NAME> <FILE>
murano env-template-delete <ID>
murano env-template-list
murano env-template-show <ID>
murano env-template-update <ID> <NEW_NAME>

93
doc/source/articles/policy_enf.rst
View File

@ -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

191
doc/source/articles/policy_enf_dev.rst
View File

@ -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")``

11
doc/source/articles/policy_enf_index.rst
View File

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

74
doc/source/articles/policy_enf_modify.rst
View File

@ -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.

123
doc/source/articles/policy_enf_setup.rst
View File

@ -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)'
..

7
doc/source/index.rst
View File

@ -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**