开发模板规范

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 作为用户执行自定义服务的展示内容,并进行国际化。