Welcome to Murano Documentation¶

From a zip file¶

Perform the following steps to import an application package from a .zip file:

1. In OpenStack dashboard, navigate to Murano > Manage > Packages.

2. Click the Import Package button on the top right of the page.

   

3. From the Package source drop-down list choose File, then click Browse to select a .zip file you want to import, and then click Next.

   

4. At this step, the package is already uploaded. Choose a category from the Application Category menu. You can select multiple categories while holding down the Ctrl key. If necessary, verify and update the information about the package, then click the Create button.

   

From a repository¶

Perform the following steps to import an application package from murano applications repository:

1. In dashboard, navigate to Murano > Manage > Packages.

2. Click the Import Package button on the top right of the page.

   

3. From the Package source drop-down list, choose Repository, enter the package name, and then click Next. Note that you may also specify the version of the package.

   

4. At this step, the package is already uploaded. Choose a category from the Application Category menu. You can select multiple categories while holding down the Ctrl key. If necessary, verify and update the information about the package, then click the Create button.

   

From a bundle of applications¶

Perform the following steps to import a bundle of applications:

1. In dashboard, navigate to Murano > Manage > Packages.

2. Click the Import Bundle button on the top right of the page.

   

3. From the Package Bundle Source drop-down list, choose Repository, enter the bundle name, and then click Create.

   

From environment details page¶

1. In OpenStack dashboard, navigate to Murano > Application catalog > Environments.
2. Find the environment you want to manage and click Manage Components, or simply click on the environment’s name.
3. Procced with the Drop Components here field or the Add Component button.

Use of Drop Components here field

1. On the Environment Components page, drag and drop a desired application into the Drop Components here field under the Application Components section.

   

2. Configure the application. Note that the settings may vary from app to app and are predefined by the application author. When done, click Next, then click Create.

Now the application appears in the Component List section on the Environment Components page.

Use of Add Component button

1. On the Environment Components page, click Add Component.

   

2. Find the application you want to add and click Add to Env.

   

3. Configure the application and click Next. Note that the settings may vary from app to app and are predefined by the application author.

4. To add more applications, check Add more applications to the environment, then click Create and repeat the steps above. Otherwise, just click Create.

   

   Now the application appears in the Component List section on the Environment Components page.

From applications catalog page¶

1. In OpenStack dashboard, navigate to Murano > Application catalog > Applications.
2. On the Applications catalog page, use one of the following methods:
   • Quick deploy. Automatically creates an environment, adds the selected application, and redirects you to the page with the environment components.
   • Add to Env. Adds an application to an already existing environment.

Quick Deploy button

1. Find the application you want to add and click Quick Deploy. Let’s add Apache Tomcat, for example.

   

2. Configure the application. Note that the settings may vary from app to app and are predefined by the application author. When done, click Next, then click Create. In the example below we assign a floating IP address.

   

Now the Apache Tomcat application is successfully added to an automatically created quick-env-1 environment.

Add to Env button

1. From the Environment drop-down list, select the required environment.

   

2. Find the application you want to add and click Add to Env. Let’s add Apache Tomcat, for example.

   

3. Configure the application and click Next. Note that the settings may vary from app to app and are predefined by the application author. In the example below we assign a floating IP address.

   

4. To add more applications, check Add more applications to the environment, then click Create and repeat the steps above. Otherwise, just click Create.

   

Browse component details¶

You can browse component details to find the following information about a component:

• Name
• ID
• Type
• Instance name (available only after deployment)
• Heat orchestration stack name (available only after deployment)

To browse a component details, perform the following steps:

1. In OpenStack Dashboard, navigate to Murano > Application Catalog > Environments.

2. Click the name of the required environment.

3. In the Component List section, click the name of the required component.

   

   The links redirect to corresponding horizon pages with the detailed information on instance and heat stack.

Application topology¶

Once you add an application to your environment, the application topology of this environment becomes available in a separate tab. The topology represents an elastic diagram showing the relationship between a component and the infrastructure it runs on. To view the topology:

1. In OpenStack Dashboard, navigate to Murano > Application Catalog > Environments.
2. Click the name of the necessary environment.
3. Click the Topology tab.

The topology is helpful to visually display complex components, for example Kubernetes. The red icons reflect errors during the deployment while the green ones show success.

The following elements of the topology are virtual machine and an instance of dependent MuranoPL class:

Element	Meaning
	Virtual machine
	Instance

Position your mouse pointer over an element to see its name, ID, and other details.

Deployment logs¶

To get detailed information on a deployment, use:

• Deployment history, which contains logs and deployment structure of an environment.
• Latest deployment log, which contains information on the latest deployment of an environment.
• Component logs, which contain logs on a particular component in an environment.

Deployment history

To see the log of a particular deployment, proceed with the steps below:

1. In OpenStack Dashboard, navigate to Murano > Application Catalog > Environments.

2. Click the name of the required environment.

3. Click the Deployment History tab.

4. Find the required deployment and click Show Details.

5. Click the Logs tab to see the logs.

   

Latest deployment log

To see the latest deployment log, proceed with the steps below:

1. In OpenStack Dashboard, navigate to Murano > Application Catalog > Environments.
2. Click the name of the required environment.
3. Click the Latest Deployment Log tab to see the logs.

Component logs

To see the logs of a particular component of an environment, proceed with the steps below:

1. In OpenStack Dashboard, navigate to Murano > Application Catalog > Environments.

2. Click the name of the required environment.

3. In the Component List section, click the required component.

4. Click the Logs tab to see the component logs.

   

Format¶

Specifies the version of the format for manifest.yaml to track the syntax changes. Format key presents in each manifest file. Currently, 1.0 is the only available version:

Format: 1.0

Type¶

Specifies the type of the package:

Type: Application

FullName¶

Stands for the unique service application name. That name allows to easily recognize to which scope an application belongs. All other applications can address to the Apache application methods by this name.

To ensure the global uniqueness, the same naming convention as the naming convention of Java packages and classes is followed. The io.murano.apps.apache. part is the “package” part of the name, while ApacheHttpServer stands for the “class” part of the name:

FullName: io.murano.apps.apache.ApacheHttpServer

Name¶

Stands for the display name of the application. You will be able to reset a display name when you upload ApacheHTTPServer package to Murano:

Name: Apache HTTP Server

Description¶

Contains the application description rendered under the application title:

1
2
3
4
5
6
7
8

Description: |
  The Apache HTTP Server Project is an effort to develop and maintain an
  open-source HTTP server for modern operating systems including UNIX and
  Windows NT. The goal of this project is to provide a secure, efficient and
  extensible server that provides HTTP services in sync with the current HTTP
  standards.
  Apache httpd has been the most popular web server on the Internet since
  April 1996, and celebrated its 17th birthday as a project this February.

Let’s take a closer look at the syntax:

The vertical line | symbol comes from YAML syntax. The > symbol can be used interchangeably. These are the YAML block style indicators, which mean that all the leading indents and new line symbols should be preserved. This is very useful for long, multi-line descriptions, because this affects how they are displayed on the UI.

Author¶

Contains the name of the author of an application, it is only displayed in the application details and does not affect anything.

Author: Mirantis, Inc

Tags¶

Is an array of tags. You can search an application by its tag. You may want to specify several tags for one application:

Tags: [HTTP, Server, WebServer, HTML, Apache]

Besides, YAML allows tag specification using another syntax, which is an equivalent to the one given above:

Tags:
   - HTTP
   - Server
   - WebServer
   - HTML
   - Apache

Classes¶

Is a mapping between all classes present in ApacheHttpServer application and the file names where these classes are defined in. This is one-to-one relationship, which means that there is one and the only class per a single file.

The line io.murano.apps.apache.ApacheHttpServer: ApacheHttpServer.yaml says that the class io.murano.apps.apache.ApacheHttpServer is defined in the file ApacheHttpServer.yaml:

Classes:
 io.murano.apps.apache.ApacheHttpServer: ApacheHttpServer.yaml

Application¶

Defines the object model by which engine deploys the ApacheHTTPServer application, and includes YAQL expressions.

The section contains the reference to the Apache class, the one that is provided in the manifest, named with the ? symbol. This indicates system information:

1
2
3

 Application:
  ?:
    type: io.murano.apps.apache.ApacheHttpServer

For ApacheHTTPServer application it is defined that the user should input the application name, some instance parameters and decide whether PHP should be enabled or not:

enablePHP: $.appConfiguration.enablePHP

The instance section assumes that the value, entered by the user in the first form named appConfiguration is stored in an application object module. The same applies for the instance parameter. Providing the question mark with the defined type io.murano.resources.LinuxMuranoInstance indicates an instance of MuranoPl object.

1
2
3

instance:
   ?:
     type: io.murano.resources.LinuxMuranoInstance

Forms¶

Contains UI forms prototypes that are merged to the application creation wizard.

Each form field will be translated to the Django field and most of the parameters correspond to parameters in the Django form field. All fields are required by default. Hidden fields are used to print extra information in the form description.

After the upload, the section content will be browsed on the left side of the form and its description on the right.

Please take a look at the Configure Application: Apache HTTP Server dialog:

Here is how the second dialog looks like:

For more information about Dynamic UI, please refer to the main reference.

Namespaces¶

Can be named shortcuts since this is an additional section which enables short names instead of the long ones:

1
2
3
4
5

Namespaces:
  =: io.murano.apps.apache
  std: io.murano
  res: io.murano.resources
  sys: io.murano.system

Name¶

Contains the class name that is defined in this file. So full class name will be current namespace and name, provided by corresponding key: io.murano.apps.apache.ApacheHttpServer:

Name: ApacheHttpServer

Extends¶

Determines inheritance, and io.murano.Application should be a parent for all the murano applications.

This class has defined deploy method and only instances of that class can be used in Environment class. Environment class, in its turn, is responsible for the deployment configurations. Definition of both classes are located at meta/io.murano folder of murano repository.

Thus, if you want to have some modifications of ApacheHttpServer, you can set io.murano.apps.apache.ApacheHttpServer in the Extends section of a new Application class:

Extends: std:Application

Properties¶

Defines the dictionary. Apache HTTP Server application has three properties: name, enablePHP and instance. For each of them certain Contract is defined.

Only enablePHP is optional, and its default value equals to false.

Instance is the required parameter and should be an instance of the predefined in core library io.murano.resources.Instance class.

Methods¶

The initialize method is like __init__ in Python, and executes together with properties initialization.

It accesses the environment, which the application belongs to, and is used only for sending reports about the deployment state.

Private variable _environment is defined as follows:

1
2
3

initialize:
       Body:
         - $._environment: $.find(std:Environment).require()

The deploy method sets up instance spawning and configuration. This method should be executed only once. So in the first order deployed variable is checked to be false in the current scope.

It performs the following actions:

• configures securityGroups;
• initiates new virtual machine spawning: $.instance.deploy()
• loads the execution plan template, located in the Resources directory to the instance of resources class: $resources.yaml('DeployApache.template')
• updates the plan with parameters taken from the user: bind(dict(enablePHP => $.enablePHP))
• sends ready-to-execute-plan to murano agent: $.instance.agent.call($template, $resources)

Automatic package composing¶

Before uploading an application into the catalog, it should be prepared and archived. A Murano command line will do all preparation for you. Just choose the desired Heat Orchestration Template and perform the following command:

murano package-create –template wordpress/template.yaml

Note, that optional parameters could be specified:

As the result, an application definition archive will be ready for uploading.

Manual package composing¶

Application package could be composed manually. Follow the 5 steps below.

• Step 1. Choose the desired heat orchestration template

  For this example chef-server.yaml template will be used.

• Step 2. Rename it to template.yaml

• Step 3. Prepare an application logo (optional step)

  It could be any picture associated with the application.

• Step 4. Create manifest.yaml file

  All service information about the application is contained here. Specify the following parameters:

  Format:	defines an application definition format; should be set to Heat.HOT/1.0
  Type:	defines a manifest type, should be set to Application
  FullName:	a unique name which will be used to identify the application in Murano Catalog
  Description:	text information about an application
  Author:	a name of an application author or a company
  Tags:	keywords associated with the application
  Logo:	a name of a logo file for an application

  Take a look at the example:

  Format: Heat.HOT/1.0
  Type: Application
  FullName: io.murano.apps.Chef-Server
  Name: Chef Server
  Description: "Heat template to deploy Open Source CHEF server on a VM"
  Author: Kate
  Tags:
    - hot-based
  Logo: logo.png
  

• Step 5. Create a zip archive, containing the specified files: template.yaml, manifest.yaml, logo.png

Applications page looks like:

The configuration form, where you can enter template parameters, will be generated automatically and looks as follows:

After filling the form the application is ready to be deployed.

Class name¶

Class names are alphanumeric names of the classes. Traditionally, all class names begin with an upper-case letter symbol and are written in PascalCasing.

In MuranoPL all class names are unique. At the same time, MuranoPL supports namespaces. So, in different namespaces you can have classes with the same name. You can specify a namespace explicitly, like ns:MyName. If you omit the namespace specification, MyName is expanded using the default namespace =:. Therefore, MyName equals =:MyName if = is a valid namespace.

Namespaces¶

Namespaces declaration specifies prefixes that can be used in the class body to make long class names shorter.

Namespaces:
    =: io.murano.services.windows
    srv: io.murano.services
    std: io.murano

In the example above, the srv: Something class name is automatically translated to io.murano.services.Something.

= means the current namespace, so that MyClass means io.murano.services.windows.MyClass.

If the class name contains the period (.) in its name, then it is assumed to be already fully namespace qualified and is not expanded. Thus ns.Myclass remains as is.

Extends¶

MuranoPL supports multiple inheritance. If present, the Extends section shows base classes that are extended. If the list consists of a single entry, then you can write it as a scalar string instead of an array. If you do not specify any parents or omit the key, then the class extends io.murano.Object. Thus, io.murano.Object is the root class for all class hierarchies.

Properties¶

Properties are class attributes that together with methods create public class interface. Usually, but not always, properties are the values, and reference other objects that have to be entered in an environment designer prior to a workflow invocation.

Properties have the following declaration format:

propertyName:
    Contract: property contract
    Usage: property usage
    Default: property default

Namespaces:
  =: io.murano.apps.docker
  std: io.murano

Name: ApplicationPort

Properties:
  port:
    Contract: $.int().notNull().check($ > 0 and $ < 65536)

  scope:
    Contract: $.string().notNull().check($ in list(public, cloud, host, internal))
    Default: private

  protocol:
    Contract: $.string().notNull().check($ in list(TCP, UDP))
    Default: TCP

Methods:
  getRepresentation:
    Body:
      Return:
        port: $.port
        scope: $.scope
        protocol: $.protocol

p:
 Contract: $.class(MyClass)
 Default: {a: 12}

Workflow¶

Workflows are the methods that describe how the entities that are represented by MuranoPL classes are deployed.

In a typical scenario, the root object in an input data model is of the io.murano.Environment type, and has the deploy method. This method invocation causes a series of infrastructure activities (typically, a Heat stack modification) and the deployment scripts execution initiated by VM agents commands. The role of the workflow is to map data from the input object model, or a result of previously executed actions, to the parameters of these activities and to initiate these activities in a correct order.

Methods¶

Methods have input parameters, and can return a value to a caller. Methods are defined in the Workflow section of the class using the following template:

methodName:
    Usage: Action
    Arguments:
       - list
       - of
       - arguments
    Body:
       - list
       - of
       - instructions

Action is an optional parameter that specifies methods to be executed by direct triggering after deployment.

Arguments are optional too, and are declared using the same syntax as class properties, except for the Usage attribute that is meaningless for method parameters. For example, arguments also have a contract and optional default:

scaleRc:
  Arguments:
    - rcName:
        Contract: $.string().notNull()
    - newSize:
        Contract: $.int().notNull()

The Method body is an array of instructions that get executed sequentially. There are 3 types of instructions that can be found in a workflow body:

• expressions,
• assignments,
• block constructs.

Body:
  - If: predicate1()
    Then:
      - code
      - block
  - While: predicate2()
    Do:
      - code
      - block

Object model¶

Object model is a JSON serialized representation of objects and their properties. Everything you do in the OpenStack dashboard is reflected in an object model. The object model is sent to the Application catalog engine when the user decides to deploy the built environment. On the engine side, MuranoPL objects are constructed and initialized from the received Object model, and a predefined method is executed on the root object.

Objects are serialized to JSON using the following template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
    "?": {
        "id": "globally unique object ID (UUID)",
        "type": "fully namespace-qualified class name",

        "optional designer-related entries can be placed here": {
            "key": "value"
        }
    },

    "classProperty1": "propertyValue",
    "classProperty2": 123,
    "classProperty3": ["value1", "value2"],

    "reference1": {
        "?": {
            "id": "object id",
            "type": "object type"
        },

        "property": "value"
    },

    "reference2": "referenced object id"
}

Objects can be identified as dictionaries that contain the ? entry. All system fields are hidden in that entry.

There are two ways to specify references:

1. reference1 as in the example above. This method allows inline definition of an object. When the instance of the referenced object is created, an outer object becomes its parent/owner that is responsible for the object. The object itself may require that its parent (direct or indirect) be of a specified type, like all applications require to have Environment somewhere in a parent chain.
2. Referring to an object by specifying other object ID. That object must be defined elsewhere in an object tree. Object references distinguished from strings having the same value by evaluating property contracts. The former case would have $.class(Name) while the later - the $.string() contract.

Class: Object¶

A parent class for all MuranoPL classes. It implements the initialize, setAttr, and getAttr methods defined in the pythonic part of the Object class. All MuranoPL classes are implicitly inherited from this class.

Class: Application¶

Defines an application itself. All custom applications must be derived from this class.

Class: SecurityGroupManager¶

Manages security groups during an application deployment.

Class: Environment¶

Defines an environment in terms of the deployment process and groups all Applications and their related infrastructures. It also able to deploy them at once.

Environments is intent to group applications to manage them easily.

Class: Instance¶

Defines virtual machine parameters and manages an instance lifecycle: spawning, deploying, joining to the network, applying security group, and deleting.

Class: Network¶

The basic abstract class for all MuranoPL classes representing networks.

Class: Logger¶

Logging API is the part of core library since Liberty release. It was introduced to improve debuggability of MuranoPL programs.

You can get a logger instance by calling a logger function which is located in io.murano.system namespace. The logger function takes a logger name as the only parameter. It is a common recommendation to use full class name as a logger name within that class. This convention avoids names conflicts in logs and ensures a better logging subsystem configurability.

Logger class instantiation:

$log: logger('io.murano.apps.activeDirectory.ActiveDirectory')

There are several methods that fully correspond to the log levels you can use for logging events. They are debug, trace, info, warning, error, and critical.

Logging example:

$log.info('print my info message {message}', message=>message)

Logging methods use the same format rules as the YAQL format function. Thus the line above is equal to the:

$log.info('print my info message {message}'.format(message=>message))

To print an exception stacktrace, use the exception method. This method uses the ERROR level:

Try:
  - Throw: exceptionName
    Message: exception message
Catch:
With: exceptionName
As: e
Do:
  - $log.exception($e, 'something bad happen "{message}"', message=>message)

Version¶

The syntax and format of dynamic UI definitions may change over time, so the concept of format versions is introduced. Each UI definition file may contain a top-level section called Version to indicate the minimum version of Murano Dynamic UI platform which is capable to process it. If the section is missing, the format version is assumed to be latest supported.

The version consists of two non-negative integer segments, separated by a dot, i.e. has a form of MAJOR.MINOR. Dynamic UI platforms having the same MAJOR version component are compatible: i.e. the platform having the higher version may process UI definitions with lower versions if their MAJOR segments are the same. For example, Murano Dynamic UI platform of version 2.2 is able to process UI definitions of versions 2.0, 2.1 and 2.2, but is unable to process 3.0 or 1.9.

Currently, the latest version of Dynamic UI platform is 2.3. It is incompatible with UI definitions of Version 1.0, which were used in Murano releases before Juno.

Application and Templates¶

The Application section describes an application object model. This model will be translated into json, and an application will be deployed according to that json. The application section should contain all necessary keys that are required by the murano-engine to deploy an application. Note that the system section of the object model goes under the ?. So murano recognizes that instead of simple value, MuranoPL object is used. You can pick parameters you got from a user (they should be described in the Forms section) and pick the right place where they should be set. To do this YAQL is used. Below is an example of how two YAQL functions are used for object model generation:

• generateHostname is used for a machine hostname template generation; it accepts two arguments: name pattern (string) and index (integer). If ‘#’ symbol is present in name pattern, it will be replaced with the index provided. If pattern is not given, a random name will be generated.
• repeat is used to produce a list of data snippets, given the template snippet (first argument) and number of times it should be reproduced (second argument). Inside that template snippet current step can be referenced as $index.

Example:

Templates:
  primaryController:
     ?:
       type: io.murano.windows.activeDirectory.PrimaryController
     host:
       ?:
         type: io.murano.windows.Host
       adminPassword: $.appConfiguration.adminPassword
       name: generateHostname($.appConfiguration.unitNamingPattern, 1)
       flavor: $.instanceConfiguration.flavor
       image: $.instanceConfiguration.osImage

   secondaryController:
     ?:
       type: io.murano.windows.activeDirectory.SecondaryController
     host:
       ?:
         type: io.murano.windows.Host
       adminPassword: $.appConfiguration.adminPassword
       name: generateHostname($.appConfiguration.unitNamingPattern, $index + 1)
       flavor: $.instanceConfiguration.flavor
       image: $.instanceConfiguration.osImage

Application:
  ?:
    type: io.murano.windows.activeDirectory.ActiveDirectory
  primaryController: $primaryController
  secondaryControllers: repeat($secondaryController, $.appConfiguration.dcInstances - 1)

Forms¶

This section describes markup elements for defining forms, which are currently rendered and validated with Django. Each form has a name, field definitions (mandatory), and validator definitions (optionally).

Note that each form is splitted into 2 parts:

• input area - left side, where all the controls are located
• description area - right side, where descriptions of the controls are located

Each field should contain:

• name - system field name, could be any
• type - system field type

Currently supported options for type attribute are:

• string - text field (no inherent validations) with one-line text input
• boolean - boolean field, rendered as a checkbox
• text - same as string, but with a multi-line input
• integer - integer field with an appropriate validation, one-line text input
• password - text field with validation for strong password, rendered as two masked text inputs (second one is for password confirmation)
• clusterip - specific text field, used for entering cluster IP address (validations for valid IP address syntax and for that IP to belong to a fixed subnet)
• databaselist - specific field, a list of databases (comma-separated list of databases’ names, where each name has the following syntax first symbol should be latin letter or underscore; subsequent symbols can be latin letter, numeric, underscore, at the sign, number sign or dollar sign), rendered as one-line text input
• image - specific field, used for filtering suitable images by image type provided in murano metadata in glance properties.
• flavor - specific field, used for selection instance flavor from a list
• keypair - specific field, used for selecting a keypair from a list
• azone - specific field, used for selecting instance availability zone from a list
• network - specific field, used to select a network and subnet from a list of the ones available to the current user
• any other value is considered to be a fully qualified name for some Application package and is rendered as a pair of controls: one for selecting already existing Applications of that type in an Environment, second - for creating a new Application of that type and selecting it

Other arguments (and whether they are required or not) depends on a field’s type and other attributes values. Most of them are standard Django field attributes. The most common attributes are the following:

• label - name, that will be displayed in the form; defaults to name being capitalized.

• description - description, that will be displayed in the description area. Use yaml line folding character >- to keep the correct formatting during data transferring.

• descriptionTitle - title of the description, defaults to label; displayed in the description area

• hidden whether field should be visible or not in the input area. Note that hidden field’s description will still be visible in the descriptions area (if given). Hidden fields are used storing some data to be used by other, visible fields.

• minLength, maxLength (for string fields) and minValue, maxValue (for integer fields) are transparently translated into django validation properties.

• regexValidator - regular expression to validate user input. Used with string field.

• errorMessages - dictionary with optional ‘invalid’ and ‘required’ keys that set up what message to show to the user in case of errors.

• validators is a list of dictionaries, each dictionary should at least have expr key, under that key either some YAQL expression is stored, either one-element dictionary with regexValidator key (and some regexp string as value). Another possible key of a validator dictionary is message, and although it is not required, it is highly desirable to specify it - otherwise, when validator fails (i.e. regexp doesn’t match or YAQL expression evaluates to false) no message will be shown. Note that field-level validators use YAQL context different from all other attributes and section: here $ root object is set to the value of field being validated (to make expressions shorter).

  - name: someField
    type: string
    label: Domain Name
    validators:
      - expr:
          regexpValidator: '(^[^.]+$|^[^.]{1,15}\..*$)'
        message: >-
             NetBIOS name cannot be shorter than 1 symbol and
             longer than 15 symbols.
      - expr:
         regexpValidator: '(^[^.]+$|^[^.]*\.[^.]{2,63}.*$)'
       message: >-
         DNS host name cannot be shorter than 2 symbols and
         longer than 63 symbols.
    helpText: >-
      Just letters, numbers and dashes are allowed.
      A dot can be used to create subdomains
  

• widgetMedia sets some custom CSS and JavaScript used for the field’s widget rendering. Note, that files should be placed to Django static folder in advance. Mostly they are used to do some client-side field enabling/disabling, hiding/unhiding etc.

• requirements is used only with flavor field and prevents user to pick unstable for a deployment flavor. It allows to set minimum ram (in MBs), disk space (in GBs) or virtual CPU quantity.

  Example that shows how to hide items smaller than regular small flavor in a flavor select field:

  - name: flavor
         type: flavor
         label: Instance flavor
         requirements:
             min_disk: 20
             min_vcpus: 2
             min_memory_mb: 2048
  

• include_subnets is used only with network field. True by default. If True, the field list includes all the possible combinations of network and subnet. E.g. if there are two available networks X and Y, and X has two subnets A and B, while Y has a single subnet C, then the list will include 3 items: (X, A), (X, B), (Y, C). If set to False only network names will be listed, without their subnets.

• filter is used only with network field. None by default. If set to a regexp string, will be used to display only the networks with names matching the given regexp.

• murano_networks is used only with network field. None by default. May have values None, exclude or translate. Defines the handling of networks which are created by murano. Such networks usually have very long randomly generated names, and thus look ugly when displayed in the list. If this value is set to exclude then these networks are not shown in the list at all. If set to translate the names of such networks are replaced by a string Network of %env_name%.

  Note

  This functionality is based on the simple string matching of the network name prefix and the names of all the accessible murano environments. If the environment is renamed after the initial deployment this feature will not be able to properly translate or exclude its network name.

• allow_auto is used only with network field. True by default. Defines if the default value of the dropdown (labeled “Auto”) should be present in the list. The default value is a tuple consisting of two None values. The logic on how to treat this value is up to application developer. It is suggested to use this field to indicate that the instance should join default environment network. For use-cases where such behavior is not desired, this parameter should be set to False.

Besides field-level validators, form-level validators also exist. They use standard context for YAQL evaluation and are required when there is a need to validate some form’s constraint across several fields.

Example

Forms:
  - appConfiguration:
      fields:
        - name: dcInstances
          type: integer
          hidden: true
          initial: 1
          required: false
          maxLength: 15
          helpText: Optional field for a machine hostname template
        - name: unitNamingPattern
          type: string
          label: Instance Naming Pattern
          required: false
          maxLength: 64
          regexpValidator: '^[a-zA-Z][-_\w]*$'
          errorMessages:
           invalid: Just letters, numbers, underscores and hyphens are allowed.
         helpText: Just letters, numbers, underscores and hyphens are allowed.
         description: >-
           Specify a string that will be used in a hostname instance.
           Just A-Z, a-z, 0-9, dash, and underline are allowed.


  - instanceConfiguration:
        fields:
          - name: title
            type: string
            required: false
            hidden: true
            descriptionTitle: Instance Configuration
            description: Specify some instance parameters based on which service will be created.
          - name: flavor
            type: flavor
            label: Instance flavor
            description: >-
              Select a flavor registered in OpenStack. Consider that service performance
              depends on this parameter.
            required: false
          - name: osImage
            type: image
            imageType: windows
            label: Instance image
            description: >-
              Select valid image for a service. Image should already be prepared and
              registered in glance.
          - name: availabilityZone
            type: azone
            label: Availability zone
            description: Select an availability zone, where service will be installed.
            required: false

Setting up your own repository¶

It is fairly easy to set up your own murano package repository. To do so you need a web server that would serve 3 directories:

• /apps/
• /bundles/
• /images/

When importing an application by name, the client appends any version info, if present to the application name, .zip file extension and searches for that file in the apps directory.

When importing a bundle by name, the client appends .bundle file extension to the bundle name and searches it in the bundles directory. A bundle file is a json or a yaml file with the following structure:

{"Packages":
    [
        {"Name": "io.murano.apps.ApacheHttpServer"},
        {"Version": "", "Name": "io.murano.apps.Nginx"},
        {"Version": "0.0.1", "Name": "io.murano.apps.Lighttpd"}
    ]
}

Glance images can be auto-imported by the client, when mentioned in images.lst inside the package. Please see Step-by-Step for more information about package composition. When importing images from the image.lst file, the client simply searches for a file with the same name as the name attribute of the image in the images directory of the repository.

Rename ‘Workflow’ to ‘Methods’¶

In stable/juno the name of section containing class methods is renamed to Methods, as the latter is more OOP and doesn’t cause confusion with Mistral. So, you need to change it in app.name/Classes in all classes describing workflow of your app.

For example:

Workflow:
  deploy:
    Body:
      - $._environment.reporter.report($this, 'Creating VM')

Should be changed to:

Methods:
  deploy:
    Body:
      - $._environment.reporter.report($this, 'Creating VM')

Change the Instance type in the UI definition ‘Application’ section¶

The Instance class was too generic and contained some dirty workarounds to differently handle Windows and Linux images, to bootstrap an instance in a number of ways, etc. To solve these problems more classes were added to the Instance inheritance hierarchy.

Now, base Instance class is abstract and agnostic of the desired OS and agent type. It is inherited by two classes: LinuxInstance and WindowsInstance.

• LinuxInstance adds a default security rule for Linux, opening a standard SSH port;
• WindowsInstance adds a default security rule for Windows, opening an RDP port. At the same time WindowsInstance prepares a user-data allowing to use Murano v1 agent.

LinuxInstance is inherited by two other classes, having different software config method:

• LinuxMuranoInstance adds a user-data preparation to configure Murano v2 agent;
• LinuxUDInstance adds a custom user-data field allowing the services to supply their own user data.

You need to specify the instance type which is required by your app. It specifies a field in UI, where user can select an image matched to the instance type. This change must be added to UI form definition in app.name/UI/ui.yaml.

For example, if you are going to install your application on Ubuntu, you need to change:

Application:
  ?:
  instance:
    ?:
      type: io.murano.resources.Instance

to:

Application:
  ?:
  instance:
    ?:
      type: io.murano.resources.LinuxMuranoInstance

1. Pluggable Pythonic classes for murano¶

Now you can create plug-ins for MuranoPL. A plug-in (extension) is an independent Python package implementing functionality which you want to add to the workflow of your application.

For a demo application demonstrating the usage of plug-ins, see the murano/contrib/plugins/murano_exampleplugin folder.

The application consist of the following components:

• An ImageValidatorMixin class that inherits the generic instance class (io.murano.resources.Instance) and adds a method capable of validating the instance image for having an appropriate murano metadata type. This class may be used as a mixin when added to inheritance hierarchy of concrete instance classes.
• A concrete class called DemoInstance that inherits from io.murano.resources.LinuxMuranoInstance and ImageValidatorMixin to add the image validation logic to a standard, murano-enabled and Linux-based instance.
• An application that deploys a single VM using the DemoInstance class if the tag on the user-supplied image matches the user-supplied constant.

The ImageValidatorMixin demonstrates the instantiation of plug-in provided class and its usage, as well as handling of exception which may be thrown if the plug-in is not installed in the environment.

2. Murano mistral integration¶

The core library has a new system class for mistral client that allows to call Mistral APIs from the murano application model.

The system class allows you to:

• Upload a mistral workflow to mistral.
• Trigger the mistral workflow that is already deployed, wait for completion and return the execution output.

To use this feature, add some mistral workflow to Resources folder of your package. For example, create file TestEcho_MistralWorkflow.yaml:

version: '2.0'

test_echo:
  type: direct
  input:
    - input_1
  output:
    out_1: <% $.task1_output_1 %>
    out_2: <% $.task2_output_2 %>
    out_3: <% $.input_1 %>
 tasks:
   my_echo_test:
     action: std.echo output='just a string'
     publish:
       task1_output_1: 'task1_output_1_value'
       task1_output_2: 'task1_output_2_value'
     on-success:
       - my_echo_test_2

   my_echo_test_2:
     action: std.echo output='just a string'
     publish:
       task2_output_1: 'task2_output_1_value'
       task2_output_2: 'task2_output_2_value'

And provide workflow to use the mistral client:

Namespaces:
=: io.murano.apps.test
std: io.murano
sys: io.murano.system


Name: MistralShowcaseApp

Extends: std:Application

Properties:
  name:
    Contract: $.string().notNull()

  mistralClient:
    Contract: $.class(sys:MistralClient)
    Usage: Runtime


Methods:
  initialize:
    Body:
      - $this.mistralClient: new(sys:MistralClient)

  deploy:
    Body:
      - $resources: new('io.murano.system.Resources')
      - $workflow: $resources.string('TestEcho_MistralWorkflow.yaml')
      - $.mistralClient.upload(definition => $workflow)
      - $output: $.mistralClient.run(name => 'test_echo', inputs => dict(input_1 => input_1_value))
      - $this.find(std:Environment).reporter.report($this, $output.get('out_3'))

1. Versioning¶

2. YAQL¶

In Liberty, murano was updated to use yaql 1.0.0. The new version of yaql allows you to use a number of new functions and features that help to increase the speed of developing new applications.

Also, in Liberty you can change Format in the manifest of package from 1.0 to 1.1 or 1.2.

• 1.0 - supported by all versions of murano.
• 1.1 - supported by Liberty+. Specify it, if you want to use features from yaql 0.2 and yaql 1.0.0 at the same time in your application.
• 1.2 - supported by Liberty+. A number of features from yaql 0.2 do not work with this format (see the list below). We recommend you to use it for new applications where compatibility with Kilo is not required.

3. Simple software configuration¶

Previously, you always had to create execution plans even when some short scripts had to be executed on a VM. This process included creating a template file, creating a script, and describing the sending of the execution plan to the murano agent.

Now you can use a new class io.murano.configuration.Linux from murano core-library. This allows sending short commands to the VM and putting files from the Resources folder of packages to some path on the VM without the need of creating execution plans.

To use this feature you need to:

• Declare a namespace (for convenience)

  Namespaces:
    conf: io.murano.configuration
    ...
  

• Create object of io.murano.configuration.Linux class in workflow of your application:

  $linux: new(conf:Linux)
  

• Run one of the two feature methods: runCommand or putFile:

  # first agrument is agent of instance, second - your command
  $linux.runCommand($.instance.agent, 'service apache2 restart')
  

  or:

  # getting content of file from 'Resources' folder
  - $resources: new(sys:Resources)
  - $fileContent: $resources.string('your_file.name')
  # put this content to some directory on VM
  - $linux.putFile($.instance.agent, $fileContent, '/tmp/your_file.name')
  

4. UI network selection element¶

Since Liberty, you can provide users with the ability to choose where to join their VM: to a new network created during the deployment, or to an already existing network. Dynamic UI now has a new type of field - NetworkChoiseField. This field provides a selection of networks and their subnetworks as a dropdown populated with those which are available to the current tenant.

To use this feature, you should make the following updates in the Dynamic UI of an application:

• Add network field:

  fields:
    - name: network
      type: network
      label: Network
      description: Select a network to join. 'Auto' corresponds to a default environment's network.
      required: false
      murano_networks: translate
  

  To see the full list of the network field arguments, refer to the UI forms specification.

• Add template:

  Templates:
    customJoinNet:
      - ?:
          type: io.murano.resources.ExistingNeutronNetwork
        internalNetworkName: $.instanceConfiguration.network[0]
        internalSubnetworkName: $.instanceConfiguration.network[1]
  

• Add declaration of networks instance property:

  Application:
    ?:
      type: io.murano.apps.exampleApp
    instance:
      ?:
        type: io.murano.resources.LinuxMuranoInstance
    networks:
      useEnvironmentNetwork: $.instanceConfiguration.network[0]=null
      useFlatNetwork: false
      customNetworks: switch($.instanceConfiguration.network[0], $=null=>list(), $!=null=>$customJoinNet)
  

For more details about this feature, see use-cases

5. Remove name field from fields and object model in dynamic UI¶

Previously, each class of an application had a name property. It had no built-in predefined meaning for MuranoPL classes and mostly used for dynamic UI purposes.

Now you can create your applications without this property in classes and without a corresponding field in UI definitions. The field for app name will be automatically generated on the last management form before start of deployment. Bonus of deleting this - to remove unused property from muranopl class that is needed for dashboard only.

So, to update existing application developer should make 3 steps:

1. remove name field and property declaration from UI definition;
2. remove name property from class of application and make sure that it is not used anywhere in workflow
3. set version of UI definition to 2.2 or higher

External load-balancer¶

Suppose, you have powerful load-balancer on a real server. And you want to run the application on an OpenStack VM. Murano can set up new applications to be managed by that external load-balancer (LB). Let’s go into more details.

To implement this case the following apps are used:

• LbApp: its class methods call LB API
• WebApp: runs on the real LB

Several instances of WebApp are deployed with each of them calling two methods:

- $.loadBalancer.createPool()
- $.loadBalancer.addMember($instance)
# where $.loadBalancer is an instance of the LbApp class

The first method creates a pool and associates it with a virtual server. This happens once only. The second one registers a member in the newly created pool.

It is also possible to perform other modifications to the LB configuration, which are only restricted by the LB API functionality.

So, you need to specify the maximum instance number in the UI form related to the WebApp application. All of them are subsequently added to the LB pool. After the deployment, the LB virtual IP, by which an application is accessible, is displayed.

Using existing network as environment’s default¶

This option is available for users when they create a new environment in the Dashboard. A dropdown control is displayed next to the input field prompting for the name of environment. By default this control provides to create a new network, but the user may opt to choose some already existing network to be the default for the environment being created. If the network has more than one subnet, the list will include all the available options with their CIDRs shown. The selected network will be used as environment’s default, so no new network will be created.

Modifying the App UI to prompt user for network¶

The application package may be designed to ask user about the network they want to use for the VMs deployed by this particular application. This allows to override the default environment’s network setting regardless of its value.

To do this, application developer has to include a network field into the Dynamic UI definition of the app. The value returned by this field is a tuple of network_id and a subnet_id. This values may be passed as the input properties for io.murano.resources.ExistingNeutronNetwork object which may be in its turn passed to an instance of io.murano.resources.Instance as its network configuration.

The UI definition may look like this:

Templates:
  customJoinNet:
    - ?:
        type: io.murano.resources.ExistingNeutronNetwork
      internalNetworkName: $.instanceConfiguration.network[0]
      internalSubnetworkName: $.instanceConfiguration.network[1]
Application:
  ?:
    type: com.example.someApplicationName
  instance:
    ?:
      type: io.murano.resources.LinuxMuranoInstance
    networks:
      useEnvironmentNetwork: $.instanceConfiguration.network[0]=null
      useFlatNetwork: false
      customNetworks: switch($.instanceConfiguration.network[0], $=null=>list(), $!=null=>$customJoinNet)
Forms:
  - instanceConfiguration:
      fields:
        - name: network
          type: network
          label: Network
          description: Select a network to join. 'Auto' corresponds to a default environment's network.
          required: false
          murano_networks: translate

For more details on the Dynamic UI its controls and templates please refer to its specification.

Prerequisites:¶

• Install Python module, called nose performing one of the following commands easy_install nose or pip install nose This will install the nose libraries, as well as the nosetests script, which you can use to automatically discover and run tests.
• Install external Python libraries, which are required for Murano Web UI tests: testtools and selenium

Download and run tests:¶

First of all make sure that all additional components are installed.

• Clone murano-dashboard git repository:
  • git clone git://git.openstack.org/openstack/murano-dashboard*
• Change default settings:
  • Copy muranodashboard/tests/functional/config/config.conf.example to config.conf
  • Set appropriate urls and credentials for your OpenStack lab. Only admin users are appropriate.

[murano]

horizon_url = http://localhost/horizon
murano_url = http://localhost:8082
user = ***
password = ***
tenant = ***
keystone_url = http://localhost:5000/v2.0/

All tests are kept in sanity_check.py and divided into 5 test suites:

• TestSuiteSmoke - verification of Murano panels; check, that could be open without errors.
• TestSuiteEnvironment - verification of all operations with environment are finished successfully.
• TestSuiteImage - verification of operations with images.
• TestSuiteFields - verification of custom fields validators.
• TestSuitePackages - verification of operations with Murano packages.
• TestSuiteApplications - verification of Application Catalog page and of application creation process.

To specify which tests/suite to run, pass test/suite names on the command line:

• to run all tests: nosetests sanity_check.p
• to run a single suite: nosetests sanity_check.py:<test suite name>
• to run a single test: nosetests sanity_check.py:<test suite name>.<test name>

In case of SUCCESS execution, you should see something like this:

.........................

Ran 34 tests in 1.440s

OK

In case of FAILURE, folder with screenshots of the last operation of tests that finished with errors would be created. It’s located in muranodashboard/tests/functional folder.

There are also a number of command line options that can be used to control the test execution and generated outputs. For more details about nosetests, try:

nosetests -h

API Tests¶

Murano API tests are run on devstack gate and located at https://git.openstack.org/cgit/openstack/murano/tree/murano/tests/functional/api

• test_murano_envs.py contains test suite with actions on murano’s environments(create, delete, get and etc.)
• test_murano_sessions.py contains test suite with actions on murano’s sessions(create, delete, get and etc.)
• test_murano_services.py contains test suite with actions on murano’s services(create, delete, get and etc.)
• test_murano_repository.py contains test suite with actions on murano’s package repository

Engine Tests¶

Murano Engine Tests are run on murano-ci : https://git.openstack.org/cgit/openstack/murano/tree/murano/tests/functional/engine

• base.py contains base test class and tests with actions on deploy Murano services such as ‘Telnet’ and ‘Apache’.

Command Line Tests¶

Murano CLI tests case are currently in the middle of creation. The current scope is read only operations on a cloud that are hard to test via unit tests.

All tests have description and execution steps in there docstrings.