开发模板规范

OpenPitrix 开发包文件结构

开发者开发应用配置包需要包含以下几个文件：

文件名说明
package.json[必须] Json 格式文件记录应用详情
config.json[必须] Json 格式文件包含最终用户创建此应用实例时需设置的参数等信息，包括各种角色的节点配置、参数配置等
cluster.json.tmpl[必须] Tmpl 格式文件包含创建此应用实例时的基础架构、应用实例生命周期管理和自定义监控告警等信息
LICENSE[可选] 文本、Markdown、Link 格式的协议
README.md[可选] 应用介绍、使用说明
locale/en.json[可选] 英文语言包
locale/zh-cn.json[可选] 中文语言包

package.json 文件

字段名说明
apiVersion[必须] OpenPitrix 开发包 API 版本，可用值 v1
name[必须] 应用名称
version[必须] 应用版本，遵循 SemVer 2 标准
description[可选] 应用的简要描述
home[可选] 应用主页 URL
icon[可选] SVG 或者 PNG 格式的图片地址
screenshots[可选] SVG 或者 PNG 格式的应用截图地址列表
keywords[可选] 应用关键字列表
maintainers[可选] 运维人员列表: — [必须] name — [可选] email
sources[可选] 当前应用下载地址列表

样例：

  1. {
  2.   "apiVersion": "v1",
  3.   "name": "kafka",
  4.   "version": "0.2.7",
  5.   "description": "Apache Kafka is publish-subscribe messaging rethought as a distributed commit log.",
  6.   "home": "https://kafka.apache.org/",
  7.   "icon": "https://kafka.apache.org/images/logo.png",
  8.   "screenshots": [
  9.     "https://abc.png",
  10.     "https://def.png"
  11.   ],
  12.   "keywords": [
  13.     "kafka",
  14.     "zookeeper",
  15.     "kafka statefulset"
  16.   ],
  17.   "maintainers": [
  18.     {
  19.       "name": "Faraaz Khan",
  20.       "email": "faraaz@rationalizeit.us"
  21.     },
  22.     {
  23.       "name": "ben",
  24.       "email": "ben@spothero.com"
  25.     }
  26.   ],
  27.   "sources": [
  28.     "https://github.com/Yolean/kubernetes-kafka",
  29.     "https://github.com/confluentinc/cp-docker-images",
  30.     "https://github.com/apache/kafka"
  31.   ]
  32. }

config.json 文件

此配置文件定义用户在创建应用的时候需填入的参数信息，参数包括资源信息如 CPU、内存、节点数等，还包括应用本身配置参数以及外面依赖集群信息等。

这些信息有集群级别的全局设置，也有基于角色节点级别的信息设置。下面是对每个参数详细的解释：

注：role_name, common.param名称自定义，右上角带3个星号(*)表示该项有 sibling (兄弟)节点，开发者提交的时候也要去掉这个标记。cluster 的 name 和 description 不需要自定义。另外，env 表示集群的环境变量，每一个变量的 key 会作为配置名直接展示给用户(key不能包含空格)，它的 label 属性可以是空字符串 ““。

  1. {
  2.     "type": "array",
  3.     "properties": [{
  4.         "key": "cluster",
  5.         "description": "cluster properties",
  6.         "type": "array",
  7.         "properties": [{
  8.             "key": "name",
  9.             "label": "Name",
  10.             "description": "The name of the application",
  11.             "type": "string",
  12.             "default": "",
  13.             "required": false
  14.         }, {
  15.             "key": "description",
  16.             "label": "Description",
  17.             "description": "The description of the application",
  18.             "type": "string",
  19.             "default": "",
  20.             "required": false
  21.         }, {
  22.             "key": "vxnet",
  23.             "label": "VxNet",
  24.             "description": "The vxnet that the application will join",
  25.             "type": "string",
  26.             "default": "",
  27.             "required": true
  28.         }, {***
  29.             "key": "role_name",
  30.             "description": "role-based node properties",
  31.             "label": "Role Name",
  32.             "type": "array",
  33.             "properties": [{
  34.                 "key": "cpu",
  35.                 "label": "CPU",
  36.                 "description": "CPUs of each node",
  37.                 "type": "integer",
  38.                 "default": 1,
  39.                 "range": [1, 2, 4, 8, 16],
  40.                 "required": true
  41.             }, {
  42.                 "key": "memory",
  43.                 "label": "Memory",
  44.                 "description": "Memory of each node (in MiB)",
  45.                 "type": "integer",
  46.                 "default": 2048,
  47.                 "range": [2048, 8192, 16384, 32768, 49152],
  48.                 "required": true
  49.             }, {
  50.                 "key": "count",
  51.                 "label": "Count",
  52.                 "description": "Number of nodes for the cluster to create",
  53.                 "type": "integer",
  54.                 "default": 3,
  55.                 "max": 100,
  56.                 "min": 1,
  57.                 "required": true
  58.             }, {
  59.                 "key": "volume_size",
  60.                 "label": "Volume Size",
  61.                 "description": "The volume size for each instance",
  62.                 "type": "integer",
  63.                 "default": 10,
  64.                 "min": 10,
  65.                 "max": 1000,
  66.                 "step": 10,
  67.                 "required": true
  68.             }]
  69.         }]
  70.     }, {
  71.         "key": "env",
  72.         "description": "application configuration properties",
  73.         "type": "array",
  74.         "properties": [{***
  75.             "key": "common.param",
  76.             "label": "Common Param",
  77.             "description": "The common.param1 for all nodes",
  78.             "type": "string",
  79.             "changeable": true,
  80.             "default": "value1,value11",
  81.             "separator": ",",
  82.             "range": ["value1", "value11", "value111"],
  83.             "multichoice": true,
  84.             "required": true
  85.         }, {***
  86.             "key": "role_name",
  87.             "description": "The role configuration properties of the application",
  88.             "type": "array",
  89.             "properties": [{***
  90.                 "key": "param",
  91.                 "label": "Role Param",
  92.                 "description": "The param for all slave nodes",
  93.                 "type": "string",
  94.                 "changeable": true,
  95.                 "default": "value1",
  96.                 "range": ["value1", "value11"],
  97.                 "required": true
  98.             }]
  99.         }]
  100.     }, {
  101.         "key": "service_params",
  102.         "description": "Custom service configuration properties",
  103.         "type": "array",
  104.         "properties": [{***
  105.             "key": "common.param",
  106.             "label": "Common Param",
  107.             "description": "The common.param1 for all nodes",
  108.             "type": "string",
  109.             "default": "value1,value11",
  110.             "separator": ",",
  111.             "range": ["value1", "value11", "value111"],
  112.             "multichoice": true,
  113.             "required": true
  114.         }, {***
  115.             "key": "role_name",
  116.             "description": "Custom service the role (role_name) configuration properties",
  117.             "type": "array",
  118.             "properties": [{***
  119.                 "key": "param",
  120.                 "label": "Role Param",
  121.                 "description": "The param for all slave nodes",
  122.                 "type": "string",
  123.                 "pattern": "^value.+",
  124.                 "default": "value1",
  125.                 "range": ["value1", "value11"],
  126.                 "required": true
  127.             }]
  128.         }]
  129.     }]
  130. }

json 配置项中的每一项，都是一个含有 key、label、description、type、range 等参数的 object。配置项支持嵌套，若 type 为 array，则该项的 properties 填写一个有序列表，在用户部署应用的时候填写配置使用，因此需要注意配置项的顺序。配置项中各参数的解释如下：

参数描述
key对应 cluster.json.tmpl 文件索引的值，例如 {{cluster.name}} 表示 config.json 中 cluster 内 key=name 的项用户所填写的值。
label用户部署应用时，填写配置项的名称。如果提供了国际化的配置文件，会进行国际化。
description用户部署应用时，填写配置项的描述。如果提供了国际化的配置文件，会进行国际化。
type该配置项的类型，请参考 数据类型。
changeable如果为 false 表示该项用户在创建应用实例时候需要赋值，创建完毕以后则不能修改，比如数据库实例用户名和密码等类型的参数，默认值为 true。
range限定配置项的取值范围，是一个可枚举的数组。
multichoice和 range 配合使用，定义为 true 则为多选，默认是 false 为单选。
separator定义 multichoice 为 true 时有效，多选后多个值连接所使用的分隔符，默认值为逗号。
min若配置项 type 为 integer 或 number(浮点数)，指定该项的最小值。
max若配置项 type 为 integer 或 number(浮点数)，指定该项的最大值。
step若配置项是 volume_size，指定硬盘每次调整的最小步长单位。在每个主机挂多块盘时，通常需要指定该项。
pattern正则表达式，可用该值规范填写内容。
required是否为必填项
default该项的默认取值，若 required 设为 "false"，default 值必须提供。

一些系统预留(即必须提供)的项含义如下：

参数描述
name创建应用时用户填入的名称
description创建应用时用户填入描述信息
vxnet创建应用时所在网络ID

cluster.json.tmpl 文件

该文件是在用户创建应用时需要传给 OpenPitrix API 的参数，这些信息的具体值是来自用户在 UI 上根据 config.json 定义的变量的输入，每个字段的具体描述如下：

注： 右上角带3个星号(*)表示该项有 sibling (兄弟)节点，开发者提交的时候也要去掉这个标记。advanced_actions 的内容可以添加在国际化中，在控制台用户操作时展示。

  1. {
  2.     "name": "{{.cluster.name}}",
  3.     "description": "{{.cluster.description}}",
  4.     "vxnet": "{{.cluster.vxnet}}",
  5.     "nodes": [{***
  6.         "role": "role_name",
  7.         "container": {
  8.             "type": "docker",
  9.             "image": "gcr.io/google_samples/k8szk:v2"
  10.         },
  11.         "count": "{{.cluster.role_name.count}}",
  12.         "cpu": "{{.cluster.role_name.cpu}}",
  13.         "memory": "{{.cluster.role_name.memory}}",
  14.         "volume": {
  15.             "size": "{{.cluster.role_name.volume_size}}",
  16.             "mount_point": "/data",
  17.             "mount_options": "defaults,noatime",
  18.             "filesystem": "ext4"
  19.         },
  20.         "passphraseless": "ssh-dsa",
  21.         "services": {
  22.             "init": {
  23.                 "nodes_to_execute_on": 1,
  24.                 "post_start_service": false,
  25.                 "cmd": "mkdir -p /bigdata1/myapp;/opt/myapp/bin/init-cluster.sh"
  26.             },
  27.             "start": {
  28.                 "order": 1,
  29.                 "cmd": "/opt/myapp/bin/start-server.sh"
  30.             },
  31.             "stop": {
  32.                 "cmd": "/opt/myapp/bin/stop-server.sh"
  33.             },
  34.             "scale_out": {
  35.                 "pre_check": "/opt/myapp/sbin/scale-out-pre-check.sh",
  36.                 "cmd": "/opt/myapp/sbin/scale-out.sh"
  37.             },
  38.             "scale_in": {
  39.                 "pre_check": "/opt/myapp/sbin/scale-in-pre-check.sh",
  40.                 "cmd": "/opt/myapp/sbin/scale-in.sh",
  41.                 "timeout": 86400
  42.             },
  43.             "restart": {
  44.                 "cmd": "/opt/myapp/sbin/restart-server.sh"
  45.             },
  46.             "destroy": {
  47.                 "allow_force": true,
  48.                 "nodes_to_execute_on": 1,
  49.                 "post_stop_service": true,
  50.                 "cmd": "/opt/myapp/sbin/destroy-server.sh"
  51.             }
  52.         },
  53.         "server_id_upper_bound": 255,
  54.         "env": {
  55.             "param"***: "{{.env.role_name.param}}"
  56.         },
  57.         "custom_metadata": {
  58.             "cmd": "/opt/myapp/sbin/get_token.sh"
  59.         }
  60.     }],
  61.     "env": {
  62.         "common.param"***: "{{.env.common_param}}"
  63.     },
  64.     "endpoints": {
  65.         "client": {
  66.             "port": 2181,
  67.             "protocol": "tcp"
  68.         }
  69.     }
  70. }
  • name 新建应用的名称，必填项，但值可以为空。
  • description 新建应用描述，必填项，但值可以为空。
  • subnet 新建应用所在私有网络 ID，必填项。
  • nodes 新建应用节点信息，必填项。一个应用的节点可能是无角色区分的，这个时候 nodes 只有一种角色的信息；也可能是多角色组成的复杂应用，这个时候 nodes 就是这些角色节点信息组成的一个数组。
  • role 多角色节点应用必填项，单角色应用可以无此项。角色名称自定义，但必须和 config.json 里定义的名字一致。
  • container 镜像信息，必填项。
参数描述
type镜像类型，目前支持 docker。
imagedocker image name，包含 tag 部分。
  • count 节点个数，必填项，可以为0，但集群节点总数必须大于0。
  • cpu 每个节点 cpu 个数。
  • memory 每个节点内存大小，单位 MiB。
  • volume 每个节点数据盘信息，如果此类节点不需要数据盘，不需要填写此项。
参数描述
size每个节点挂盘容量大小，单位 GiB。
mount_point每个节点数据盘挂载路径。
mount_options描述数据盘的挂接方式，默认值 ext4 是 defaults,noatime，xfs 是 rw,noatime,inode64,allocsize=16m。
filesystem数据盘文件系统类型。如果 image 是基于 Linux 操作系统，目前支持 ext4 和 xfs，默认为 ext4。
  • passphraseless　生成密钥信息，即提供此类节点能无密码登录其它节点的可能性，但 QingCloud 调度系统只负责把此信息注册到 metadata service 中，开发者自行去获取密钥配置主机。目前支持 ssh-dsa, ssh-rsa，非必填项。
  • services　应用本身服务的初始化、启停等指令，OpenPitrix 调度系统会发送这些命令到指定节点执行，非必填项。
  • init　初始化命令，在创建集群或者新加节点时会触发该命令的执行。
参数描述
nodes_to_execute_on控制此命令在此类角色节点上某几个节点上执行，如果需要在所有此类节点上执行该命令可不填此项。
post_start_service控制初始化命令是在 start 命令执行完毕后执行还是之前执行，如果 post_start_service 为 true 则表示 init 在 start 后执行；默认 (即不加此项) 是之前执行。此项是 init 独有。
order控制不同角色节点之间执行此命令顺序。比如主从节点，有时候需要主节点先启动服务，从节点后启动服务，非必填项。
cmd具体需执行的命令，必填项。
timeout执行该命令 timeout 时间(单位秒)，系统默认10分钟，由于某些命令可能需要迁移数据而耗时比较长，这种情况下需要计算出最长可能时间，最大值是86400，非必填项。
  • start 服务启动命令，具体参数参考初始化命令 init。
  • stop　停止服务命令，具体参数参考初始化命令 init。
  • scale_out　加节点时在非新加节点上需执行的命令，具体参数参考初始化命令 init。
参数描述
pre_check删除节点时在非删除节点上执行的预检查命令，若返回非0值表示不可删除节点。此项是 scale_in 和 scale_out 独有。
  • scale_in 删除节点时在非删除节点上需执行的命令，具体参数参考初始化命令 init。
参数描述
pre_check删除节点时在非删除节点上执行的预检查命令，若返回非0值表示不可删除节点。此项是 scale_in 和 scale_out 独有。
  • restart 服务重启动命令，具体参数参考初始化命令 init。
  • destroy 销毁命令，在删除集群或者节点时会触发该命令的执行，通常用作删除资源之前检查安全性，具体参数参考初始化命令 init。
参数描述
allow_force是否允许强制删除, 默认值为 true 表示允许强制删除该节点, 强制删除时即使 destroy 的 cmd 返回非 0 值也会继续将节点删除。
  • post_stop_service　控制销毁命令是在 stop 命令执行完毕后执行还是之前执行，如果 post_stop_service 为 true 则表示 destroy 在 stop 后执行；默认 (即不加此项) 是之前执行。此项是 destroy 独有。
  • custom_service 用户自定义命令，具体参数参考备份命令 backup，除此之外自定义的服务参数还有：
参数描述
typetype = custom 表示这个服务是自定义的， 自定义的名字 (即 key，此处为 custom_service) 开发者自行定义。

注：用户可以自定义多个服务。自定义服务在用户使用时，展示的服务名就是该 service 的 key。如果想要对其进行国际化，可以在 locale 中添加它的翻译。

  • env 分特定角色节点的参数配置和应用级别的参数配置，每类应用有自身特有的可配置应用参数，比如 ZooKeeper的 zoo.cfg 里的参数配置等，每类节点也会有不同于应用全局级别的可配置参数。注意：节点之间或节点与集群全局之间的参数没有任何关系，都是独立的。
  • endpoints 应用可定义 endpoints 供第三方使用，服务名称可以自定义，但建议使用通用的名称比如 client，manager 等，这样第三方应用使用的时候更方便一些，被第三方应用使用的可能性更大一些。详细的服务信息必须包括 port，但 protocol 非必须项，即可以不提供 protocol 信息。port 除可以是整数端口外，也可以是一个指向 env 的变量，如 "port":"env.port"或 "port":"role_name.env.port"，这样用户在更新这个变量的时候会自动更新其关联的 endpoint 端口。如果您的应用是一个大家熟知的且 enpoint 不会被修改，可以省略这一定义，比如 ZooKeeper，通用端口是2181。

数据类型

config.json 文件里对每个变量需要定义其类型、取值范围、默认值等，其中类型和默认值为必填项。

参数参数描述
type-变量数据类型，支持：integer，boolean，string，number (浮点数)，array。
range-变量定值的取值范围，数组类型，如 "range": [1,3,5,7,9]。
max-变量取值的最大值，integer 和 number 类型有效。
min-变量取值的最小值，integer 和 number 类型有效。
default-变量默认值

国际化

config.json 中的 label 和 description 在控制台呈现时，默认使用配置文件中定义的内容。另外，一些自定义的服务、监控项也会直接展示到集群使用者的操作界面上。控制台的用户切换语言时，不改变该描述。如果您想让不同语言场景的用户能看到该语言的描述，请在提交的包中添加 locale 文件夹，并根据您希望国际化的语言提供翻译文件。

翻译文件是“语言名称.json”这样的格式，如 locale/en.json，locale/zh-cn.json。例如简体中文的翻译文件 zh-cn.json 内容示例如下：

  1. {
  2.     "Master": "主节点",
  3.     "Slave": "从节点",
  4.     "CPU": "CPU",
  5.     "Memory": "内存",
  6.     "Subnet": "私有网络",
  7.     "The name of the service": "服务名称",
  8.     "The description of the service": "服务描述",
  9.     "CPUs of each node": "每个节点的 CPU 数量",
  10.     "Memory of each node (in MiB)": "每个节点的内存大小（单位 MiB）",
  11.     "The subnet that the application will join": "应用运行的私有网络环境",
  12.     "scale_horizontal": "横向扩容"
  13. }

进行国际化的配置内容包括：

  • config.json 文件中，角色名称、节点配置、私有网络、环境变量 env 各配置项的 label 作为待填写项名称，description 作为待填项的描述。label 和 description 会进行国际化。
  • cluster.json.tmpl 文件中 type 为 custom 的 service，会使用 service 的 key 作为用户执行自定义服务的展示内容，并进行国际化。