Murano实践之package分析

曹涵润

2023-12-01

1、murano package概述

murano package 中包含Classes、Resources、UI三个文件夹和manifest.yaml、logo.png两个文件，其中manifest.yaml是必须包含的文件。
package解析的入口是manifest.yaml，概括的定义了这个package是什么和有什么样的用途；Classes中定义了这个package中各种运行的方法或者是应用初始化部署等的定义；Resources中主要是各种执行脚步和配置；UI定义了显示样式以及提交应用申请的参数；logo.png即为该应用的logo文件。
使用时，需要将这几个文件打包成**.zip文件，然后通过murano的接口上传上去即可。

2、manifest.yaml解析

2.1、manifest.yaml 定义

manifest.yaml 包含的如下几个部分

Format：package 版本标记
Type：package 类型。目前只有两种类型：Library 和 Application
FullName：pakcage名称，通常在定义Library时使用
Name：package名称，这个名称是一个人性化可读名称
Description：关于这个package的一段儿精简描述
Author：package的作者，可以是个人或者公司名称
Classes：MuranoPL class 列表，定义应用会用到的方法
Tags：可以说是关于这个package的关键字吧，为可选项
Logo：package logo名称，默认为logo.png，可选项

2.2、实例解释

如下，为默认基础库io.murano的manifest.yaml

Format: 1.0
Type: Library
FullName: io.murano
Name: Core library
Description: |
  Core MuranoPL library
Classes:
  io.murano.Object: Object.yaml
  io.murano.Environment: Environment.yaml
  io.murano.StackTrace: StackTrace.yaml
  io.murano.SharedIp: SharedIp.yaml
  io.murano.File: File.yaml

注： Classes仅截出一部分作为示例。根据上面的描述，我们可以这么立即，这个库版本是1.0，记作io.murano，包含有io.murano.Object等Classes，io.murano.Object在Classes/Object.yaml中定义的。

3、Class解析

3.1、Class定义

Class 包含如下几个部分，这个和java中定义一个类的形式是一样的，只不过没有没有接口等概念而已。

Namespaces：命名空间，这个可以将一些引用的package缩写
Name：Class名，完整的class名由namespace中=项加上name拼接而成
Extends：父Class，即继承的父Class
Properties：参数，包含如下几个项
Contract：参数限制
Usage：什么时候使用
Default：默认值
Workflow/Methods：可提供调用的方法方法
Argumentes：参数
Body：方法执行步骤定义，body由多条Express组成

注：
- Contract 详见http://muranotest.readthedocs.org/en/latest/articles/murano_pl.html#contract
- Usage 详见 http://muranotest.readthedocs.org/en/latest/articles/murano_pl.html#usage
- Expression 详见 http://muranotest.readthedocs.org/en/latest/articles/murano_pl.html#expressions
- Assignment详见 http://muranotest.readthedocs.org/en/latest/articles/murano_pl.html#assignment

3.2、实例解析

如下，为guacamole应用的Class定义

Namespaces:
  =: io.murano.apps
  std: io.murano
  sys: io.murano.system
  srv: io.murano.apps.apache

Name: Guacamole

Extends: std:Application

Properties:
  name:
    Contract: $.string().notNull()
  username:
    Contract: $.string().notNull()
  password:
    Contract: $.string().notNull()
  server:
    Contract: $.class(srv:Tomcat).notNull()

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

  deploy:
    Body:
      - If: not $.getAttr(deployed, false)
        Then:
          # Deploy Tomcat
          - $._environment.reporter.report($this, 'Ensuring Tomcat is deployed')
          - $.server.deploy()
          # Deploy Guacamole
          - $._environment.reporter.report($this, 'Deploying Guacamole')
          - $resources: new(sys:Resources)
          - $template: $resources.yaml('DeployGuacamole.template').bind(dict(
                username => $.username,
                password => $.password
             ))
          - $.server.instance.agent.call($template, $resources)
          - If: $.server.instance.assignFloatingIp
            Then:
              - $address: $.server.instance.floatingIpAddress
            Else:
              - $address: $.server.instance.ipAddresses[0]
          - $._environment.reporter.report($this, 'Guacamole {0} is available at http://{1}:{2}/guacamole'.format($.name, $address, 8080))
          - $.setAttr(deployed, true)

定义名称为Guacamole，命名空间是io.murano.apps，所以该Class的标示为io.murano.apps.Guacamole，该Class继承于io.murano.Application，包含参数name、username、password、server，其中server为一个Class实例，为io.murano.apps.apache.Tomet实例，且不能为空。提供了构造初始化方法和deploy方法。deploy方法定义如下：
如果Class实例未部署（deployed为false），则第一步，输出部署过程Ensuring Tomcat is deployed，接着调用server实例的deploy方法部署tomcat；第二步，输出部署过程Deploy Guacamole，接着新建实例传递部署模版DeployGuacamole.template到server的agent中，交给agent实现部署，完成之后，如果需要绑定floatingIP，绑定设置地址为floatingIp否则设置为server的第一个地址，最后输出结果Guacamole {0} is available at http://address:8080/guacamole。

4、Resource解析

4.1、Resource定义

Resource主要是一些执行的脚本和部署模版，提供给Class执行方法中调用，部署模版格式如下：

FormatVersion：语法版本
Version：版本
Name：执行任务的名称
Parameters：参数
Body：执行返回，以|开头，换行return Expression
Scripts：执行任务的主题，执行方法项中包含如下几项：
Type：部署平台的类型，为Application
Version：部署模版最小版本，可选
EntryPoint：执行文件路径
Files：需要的文件.
Options：可选输出项，captureStdout，captureStderr

4.2、实例解析

如下，为guacamole部署模版：

FormatVersion: 2.0.0
Version: 1.0.0
Name: Deploy Guacamole

Parameters:
  username: $username
  password: $password

Body: |
  return deploy('{0} {1}'.format(args.username, args.password)).stdout

Scripts:
  deploy:
    Type: Application
    Version: 1.0.0
    EntryPoint: deployGuacamole.sh
    Files: []
    Options:
      captureStdout: true
      captureStderr: true

定义部署的版本和Class调用传递的参数以及部署返回的输出

5、UI解析

5.1、UI定义

UI定义结构如下：

Version：语法版本，可选
Templates：辅助项，和Application一同工作，可选
Application：部署需要用到的项，传递的是自定义的应用参数
Forms：Web前端显示定义，form中项格式为：
- name：字段名称
- label：字段页面上显示的名称
- description：描述，用上>-来保证格式
- type：字段类型
- string：Django 字符串类型
- boolean：Django 布尔类型
- text：Django 文本类型
- integer：Django 数字类型
- password：秘密类型
- clusterip：集群IP
- floatingip：外网Ip
- domain：域名
- databaselist：
- table：表格
- flavor：规格
- keypair：密钥对
- image：镜像
- azone：availability zoom
- psqlDatabase：显示PostgreSQL databases字段
- imageType：仅为镜像提供的属性

5.2、实例解析

以guacamole显示的UI为例分析：

Version: 2

Application:
  ?:
    type: io.murano.apps.Guacamole
  name: $.appConfiguration.name
  username: $.appConfiguration.username
  password: $.appConfiguration.password
  server: $.appConfiguration.server

Forms:
  - appConfiguration:
      fields:
        - name: license
          type: string
          description: Apache License, Version 2.0
          hidden: true
          required: false
        - name: name
          type: string
          label: Application Name
          initial: Guacamole
          description: >-
            Enter a desired name for the application. Just A-Z, a-z, 0-9, dash and
            underline are allowed
        - name: username
          type: string
          label: Username
          initial: guac
          description: >-
            Please, provide a username that is going to be used to access Guacamole and ssh into the server instance to
            modify the Guacamole configuration
        - name: password
          type: password
          label: Password
          descriptionTitle: Password
          description: >-
            Please, provide a strong password that is going to be used to access Guacamole and ssh into the server instance to
            modify the Guacamole configuration
        - name: server
          type: io.murano.apps.apache.Tomcat
          label: Application Server
          description: >-
            Select an instance of Application Server to run the app

定义了UI显示的字段licese、name、username、password、server，其中server定义的是一个应用tomcat，也就是说依赖一个新的应用。
最终供部署使用的参数为name、username、password、server。

6、package定义的优缺点分析

6.1、package定义优点

结构非常的清新，引入了yaql（https://github.com/ativelkov/yaql），充分利用了yaml、yaql的特性
很好的解决了应用依赖定义的问题
提供Library package定义，很好的体现了封装的思想
提供Class 继承方法
提供package和Class的命名规范

6.2、package定义的缺点

虽然说murano的package具很多好的特性，但是依然存在着一些缺陷如：
模板测试，如果想要写好murano模版不是一件容易的事情，如果说去理解、弄明白murano的模板结构不算难的话，那么测试模板的正确性，可用性就是一个很大的痛点，目前在官方也没有找到模板测试相关的资料。