Skip to content

Latest commit

 

History

History
317 lines (227 loc) · 17.9 KB

README.md

File metadata and controls

317 lines (227 loc) · 17.9 KB
Raw

Getting Started Solution Template

This page describes the project structure used to set and update a Murano Solution. Murano templates can be used to publish it as template element on the Murano Exchange marketplace to make it available from other Murano businesses. Learn more about Murano Exchange here.

Template directories structure

getting-started-solution-template/
├── assets/index.html
├── endpoints/example.lua
├── modules/example.lua
├── services/<service_event>.lua | <service>.yaml
├── init.lua
└── murano.yaml

Template format murano.yaml

murano.yaml is the only required component of a template and defines the solution resources.

Required sections for the template

Section name Format Example Description
formatversion string formatversion: 1.0.0 The format version of this file. Must be "1.0.0".
info object See in the info section Metadata about this project.

Optional sections for the template

Following sections are optional and their order is not enforced. If not specified related source files will be ignored. The different section sub-items are themself optional and default values are provided.

Section name Format Example Description
options object See in the options section Template general settings.
env_schema object See in the options section Environment schema settings.
assets object See in the assets section Target source files of the front-end Web application.
endpoints object See in the endpoints section Target source files of the webservice back-end endpoints.
modules object See in the modules section Target reusable module source files.
services object See in the services section Target source files of internal services event handlers.
init_script string ./init.lua Relative Path of the solution initialization script file. This script will be executed once at the end of the template setup and allow to initialize the solution configuration and data. The file must contain valid lua script and may includes calls to other Lua Modules.

Info section

This section contains meta-information relative to the project.

info:
  name: <template_name>
  summary: One line summary of <template_name>
  description: |
    In depth description of <template_name>
    With lots of details.
  authors: ['Someone <[email protected]> (http://someone.local/)']
  version: 1.0.0
Fieldname Format Example Description
name string (/^[\s-]+$/) myTemplate Nice short and easy. This is the template name which do not relate to the solution name.
summary string One line summary of template Short one line summary of this template.
description string In depth description of template with lots of details. Longer, multiple paragraph explanation.
authors List of string in format: 'Full name <email.com> (link)' Each elements being optional ['Someone <[email protected]> (http://someone.local/)'] Who made this project.
version string 1.0.0 The version of the project.

Options section

General template options, including deployment strategy when applying the template to a solution.

Note: Deployment strategy options currently only apply to Webservice/Websocket endpoints, Asset files & Modules. Service configuration & Eventhandler always follow a merge behavior.

options:
  merge: true
  safeNamespace: vendor
  safeConfigs:
    - device2
    - interface.name
    - config.auto_update
    - webservice.documented_endpoints
  abort_threshold: 4
  abort_ratio: 0.5
Fieldname Format Default value Description
merge boolean false Indicates if existing items need to be removed (default) or kept, overlapping will be updated
safeNamespace string Indicates a namespace prefix where existing items remains un-touched (no update or deletion)
safeConfigs string[] Indicates which service configuration settings, defined in the .yaml files from the /services folder, would not overload existing value during updates and allow user to customize it. This is needed for any 'default' configuration value meant to be changed by user.
abort_threshold positive integer 4 Number of starting failed solution deployments before aborting a release. (If the first 4 solutions fail to deploy: abort)
abort_ratio positive number 0.5 Ratio of failed solution deployments to cancel the release, starting from abort_threshold * 2. (With 10 solutions successfully deployed, if 6 solutions failed: abort.)

Env Schema section

You can define env_schema to add descriptions to environment variables accessed through os.getenv("loglevel") when viewed in the UI.

env_schema:
  description: my custom description
  loglevel:
    description: a loglevel

Assets section

This section declares static files (Such as front-end javascript code and images) served by the Solution public API powered by the Asset service.

assets:
  location: assets
  include: '**/*'
  exclude: ['**/.*']
  default_page: index.html
Fieldname Format Example Description Default value
location string assets Root folder name containing the files. assets
include string/list '**/*' Pattern (or list of patterns) to select files in the location directory. The pattern search is relative to the location folder. '**/*'
exclude list ['**/.*'] Pattern allowing to ignore files from the selection. ['**/.*']
default_page string index.html Default asset to serve on the root path of the API /. index.html

Note: If you want to allow instances of the solution to add/modify files, define & use the safeNamespace option. All files starting with the namespace will not be replace during template updates.

Endpoints section

This section declares the different endpoint and backend logic for the solution public API powered by the Webservice service.

endpoints:
  location: endpoints
  include: '**/*.lua'
  exclude: ['*_test.lua', '*_spec.lua']
  cors: {'origin': ['http://localhost:*']}
Fieldname Format Example Description Default value
location string endpoints Root folder name containing the files. endpoints
include string/list '**/*.lua' Pattern (or list of patterns) to select files in the location directory. The pattern search is relative to the location folder. '**/*.lua'
exclude list ['*_test.lua', '*_spec.lua'] Pattern allowing to ignore files from the selection. []
cors object {'origin': ['http://localhost:*']} Cross origin resource sharing permission setting. {}

Note: If you want to allow instances of the solution to add/modify endpoints, define & use the safeNamespace option. All endpoints starting with the namespace will not be replace during template updates.

File content

Selected files need to contains valid Lua script. Endpoints are defined using a Lua comment header as follows (The file name is not relevant):

--#ENDPOINT <method> <path>[ <content_type>]
-- Custom logic goes here

The content_type is optional and application/json is the default value.

In addition to --#ENDPOINT, we enable you to define the following optional attributes:

  • --#TAGS, followed by a list of tags which are separated by space. eg: --#TAGS public user.
  • --#SECURITY, defines the authentication token needed for this endpoint, it could be none, basic, bearer or apiKey.
  • --#RATELIMIT, defines the requests per minute for this endpoint. eg: --#RATELIMIT 1.
  • --#SUMMARY, describes this endpoint. eg: --#SUMMARY To get user name.
  • --#DESCRIPTION, describes this endpoint in details. eg: --#DESCRIPTION This api is used for users to get info.

Example: ./endpoints/example.lua

You can set global security and rate_limit in services/webservice.yaml file by add the following properties:

  • security_schemes, defines all the security schemes for this solution, we support basic, bearer and apiKey.
  • security, defines the authentication token needed for this solution, it could be basic, bearer or apiKey.
  • rate_limit, defines the rate limit for this solution, the unit is request per minute per token or per IP if token is not required.
--#ENDPOINT POST /api/user
print("Creating a new user")

--#ENDPOINT GET /api/user/{userId}
print("Fetch a given user" .. request.parameters.userId)

Find more information about endpoints in the Murano Scripting Reference.

Modules section

Reusable script code definitions

modules:
  location: modules
  include: '**/*.lua'
  exclude: ['*_test.lua', '*_spec.lua']
Fieldname Format Example Description Default value
location string modules Root folder name containing the files. modules
include string/list '**/*.lua' Pattern (or list of patterns) to select files in the location directory. The pattern search is relative to the location folder. '**/*.lua'
exclude list ['*_test.lua', '*_spec.lua'] Pattern allowing to ignore files from the selection. []

Note: If you want to allow instances of the solution to add/modify modules, define & use the safeNamespace option. All modules starting with the namespace will not be replace during template updates.

File content

Selected file needs to contain valid Lua script and should be structured as standard Lua modules.

Important notes & best practices:

  • All variables & functions should be tagged as local.
  • The trailing return statement is required.
  • To avoid confusion with Murano Services, module file name should start with a lower-case letter.
  • The module file relative path matters.
  • As convention name your module object after the module name.

Find more information regarding modules on the Murano Scripting Reference.

Example: ./modules/src/utils.lua

local utils = { variable = "World"}
function utils.hello()
  return utils.variable
end
return utils

Can be accessed in event handlers or other modules using the file full path inside the modules folder:

require("src.utils").hello() -- -> "World"

Note: If you want to allow instances of the solution to add/modify files, define & use the safeNamespace option.

Services section

Section defines Services configuration and related scripting logic for the Solution. Services defined with below section will get configured for the solution.

services:
  location: services
  include: '**/*.lua'
  exclude: ['*_test.lua', '*_spec.lua']
Fieldname Format Example Description Default value
location string services Root folder name containing the files. services
include string/list '**/*.lua' Pattern (or list of patterns) to select files in the location directory. The pattern search is relative to the location folder. '**/*.lua'
exclude list ['*_test.lua', '*_spec.lua'] Pattern allowing to ignore files from the selection. []
.lua Event logic files content

Selected file needs to contain valid Lua scripts used for service event handlers logic. Scripts are triggered when the relevant Murano event occurs. The service and event can be defined using the following Lua comment to define multiple event handlers in a single file:

There is 3 ways to defines event scripts:

File based

Each file contains a unique event script.

  1. The file name is composed as <service_alias>_<event_type>.lua

    Example: ./services/timer_timer.lua

  2. In nested folder: the parent is the service alias & the file name is the event type.

    Example: ./services/user/account.lua

Tag based

You can also set multiple event script in a single file by using the tag:

--#EVENT [<service_alias>] <event_type>

Example: ./services/default.lua

--#EVENT scripts echo
return data

If the <service_alias> is omitted, the file name is used.

Example: ./services/config.lua

--#EVENT fallback
print(context, event)
Using <script_key> instead of <service_alias>

If the <service_alias> value is not an existing service reference, the eventhandler will still be created using the provide value as 'script_key'. If a service is later added to the solution with a matching 'script_key' the eventhandler script will be automatically linked to the service.

Find more information regarding eventhandlers on the Murano Scripting Reference.

.yaml Service configuration files content

Specific configuration parameters can be defined per service using <service_alias>.yaml files in the defined location directory.

Content of the files needs to match the target service configuration parameters.

Examples: ./services/device2.yaml

protocol:
  name: onep
provisioning:
  auth_type: token

This method can also be used with an empty file to configured service which doesn't have any script logic or specific configuration parameters. Example: ./services/twilio.yaml.

Note: If you want to allow instances of the solution to modify a service configuration parameter defined in your template, use the safeConfigs option to white-list the service or service.parameter. All other configurations will overload user changes upon template updates.