应用开发模版规范 - 基础版
此规范定义的是开发一个基于 AppCenter 2.0 云应用需要的基本元素,不包括国际化、监控告警和其它高级功能,旨在让开发者快速入门,详细的规范请参考完整版规范。
开发者提交一个应用需要包含以下几个文件:
- config.json
该文件定义最终用户在控制台部署应用实例时需要填写的表单; - cluster.json.mustache
该文件包含创建应用实例时需要用到的镜像、多少类节点、服务启动命令等信息文件。
注:以上文件不支持 "UTF-8 Unicode (with BOM) text" 文本格式,windows下的编辑器编辑文件默认是此格式,可通过 "格式-> 以utf-8无BOM格式编码" 进行转换。
config.json
此配置文件定义最终用户在创建应用实例的时候需填入的参数信息,参数包括资源信息如 CPU、内存、节点数等,还包括应用本身配置参数等。下面是对每个参数详细的解释:
注:role_name, common.param名称自定义,cluster 的 name 和 description 不需要自定义。右上角带3个星号(*)表示该项有 sibling (兄弟)节点,开发者提交的时候也要去掉这个标记。另外,env 表示集群的环境变量,是可选项,即可以不用定义此项,每一个变量的 key 会作为配置名直接展示给用户 (key 不能包含空格),它的 label 属性可以是空字符串 ""。
{
"type": "array",
"properties": [{
"key": "cluster",
"description": "cluster properties",
"type": "array",
"properties": [{
"key": "name",
"type": "string",
"label": "Name",
"description": "The name of the application",
"default": "",
"required": "no"
}, {
"key": "description",
"type": "string",
"label": "Description",
"description": "The description of the application",
"default": "",
"required": "no"
}, {
"key": "vxnet",
"label": "VxNet",
"description": "The vxnet that the application will join",
"type": "string",
"default": "",
"required": "yes"
}, {***
"key": "role_name",
"description": "role-based node properties",
"label": "Role Name",
"type": "array",
"properties": [{
"key": "cpu",
"label": "CPU",
"description": "CPUs of each node",
"type": "integer",
"default": 1,
"range": [1, 2, 4, 8, 16],
"required": "yes"
}, {
"key": "memory",
"label": "Memory",
"description": "Memory of each node (in MiB)",
"type": "integer",
"default": 2048,
"range": [2048, 8192, 16384, 32768, 49152],
"required": "yes"
}, {
"key": "instance_class",
"label": "Instance Class",
"description": "The instance type for the cluster to run,such as high performance,high performance plus",
"type": "integer",
"default": 0,
"range": [0, 1],
"required": "yes"
}, {
"key": "count",
"label": "Count",
"description": "Number of nodes for the cluster to create",
"type": "integer",
"default": 3,
"max": 100,
"min": 1,
"required": "yes"
}, {
"key": "volume_size",
"label": "Volume Size",
"description": "The volume size for each instance",
"type": "integer",
"default": 10,
"min": 10,
"max": 1000,
"step": 10,
"required": "yes"
}]
}]
}, {
"key": "env",
"description": "Application configuration properties",
"type": "array",
"properties": [{***
"key": "common.param",
"label": "Common Param",
"description": "The common.param1 for all nodes",
"type": "string",
"default": "value1,value11",
"range": ["value1", "value11", "value111"],
"required": "yes"
}]
}]
}
json 配置项中的每一项,都是一个含有 key、label、description、type、range 等参数的 object。配置项支持嵌套,若 type 为 array,则该项的 properties 填写一个有序列表,在用户部署应用的时候填写配置使用,因此需要注意配置项的顺序。配置项中各参数的解释如下:
- key
对应 cluster.json.mustache 文件索引的值,例如 {% raw %}{{cluster.name}}{% endraw %} 表示 config.json 中 cluster 内 key=name 的项用户所填写的值。 - label
用户部署应用时,填写配置项的名称。 - description
用户部署应用时,填写配置项的描述。 - type
该配置项的类型,请参考 数据类型。 - range
限定配置项的取值范围,是一个可枚举的数组。 - min
若配置项 type 为 integer 或 number (浮点数),指定该项的最小值。 - max
若配置项 type 为 integer 或 number (浮点数),指定该项的最大值。 - step
若配置项是 volume_size,指定硬盘每次调整的最小步长单位。在每个主机挂多块盘时,通常需要指定该项。 - required
是否为必填项 - default
该项的默认取值,若 required 设为 "no",default 值必须提供。
一些系统预留(即必须提供)的项含义如下:
- name
创建应用时用户填入的名称 - description
创建应用时用户填入描述信息 - vxnet
创建应用时所在网络ID
cluster.json.mustache
该文件是在用户创建应用时需要传给青云 API 的参数,这些信息的具体值是来自用户在 UI 上根据 config.json 定义的变量的输入,每个字段的具体描述如下:
注:role, vloume, services, env 和 advanced_actions 为可选项,如果不定义 role 则意味着这是个单角色的应用;不定义 volume 则表示该节点没有挂盘,只有系统盘;右上角带3个星号(*)表示该项有 sibling (兄弟)节点,开发者提交的时候也要去掉这个标记。
{
"name": {{cluster.name}},
"description": {{cluster.description}},
"vxnet": {{cluster.vxnet}},
"nodes": [{***
"role": "role_name",
"container": {
"type": "kvm",
"image": "img-skhdp16m",
"zone": "pek3a"
},
"count": {{cluster.role_name.count}},
"cpu": {{cluster.role_name.cpu}},
"memory": {{cluster.role_name.memory}},
"instance_class": {{cluster.role_name.instance_class}},
"volume": {
"size": {{cluster.role_name.volume_size}}
},
"services": {
"init": {
"order": 1,
"cmd": "mkdir -p /bigdata1/myapp;/opt/myapp/bin/init-cluster.sh"
},
"start": {
"cmd": "/opt/myapp/bin/start-server.sh"
},
"stop": {
"cmd": "/opt/myapp/bin/stop-server.sh"
},
"scale_out": {
"cmd": "/opt/myapp/sbin/scale-out.sh"
},
"scale_in": {
"cmd": "/opt/myapp/sbin/scale-in.sh"
},
"destroy": {
"cmd": "/opt/myapp/sbin/destroy-server.sh"
}
}
}],
"env": {
"common.param"***: {{env.common_param}}
},
"advanced_actions": ["change_vxnet", "scale_horizontal"]
}
- name
新建应用的名称,必填项,但值可以为空。 - description
新建应用描述,必填项,但值可以为空。 - vxnet
新建应用所在网络 ID,必填项。 nodes
新建应用节点信息,必填项。一个应用的节点可能是无角色区分的,这个时候 nodes 只有一种角色的信息;也可能是多角色组成的复杂应用,这个时候 nodes 就是这些角色节点信息组成的一个数组。- role
多角色节点应用必填项,单角色应用可以无此项。角色名称自定义,但必须和 config.json 里定义的名字一致。 - container
镜像信息,必填项。- type
镜像类型,目前支持 kvm,docker。 - image
镜像 ID,开发者根据镜像制作指南制作的以 img- 开头的镜像 ID,如果是 docker 则是 docker image name,包含 tag 部分。 - zone
镜像制作时所属区域 (如果是 docker 镜像,则无需填写该字段)
- type
- count
节点个数,必填项,可以为0,但集群节点总数必须大于0。 - cpu
每个节点 cpu 个数,可选值范围:1, 2, 4, 8, 12, 16。 - memory
每个节点内存大小,单位 MiB。可选值范围:1024, 2048, 4096, 6144, 8192, 12288, 16384, 24576, 32768, 40960, 49152, 65536, 131072。 - volume
每个节点数据盘信息,如果此类节点不需要数据盘,不需要填写此项。- size
每个节点数据容量大小,单位 GiB,必填项。单张容量盘最大5000G,单张性能盘和超高性能盘最大1000G,且步长大小需是10的整数倍。Linux 系统默认挂载在 /data 目录下。
- size
services
应用本身服务的初始化、启停等指令,青云 AppCenter 调度系统会发送这些命令到指定节点执行。非必填项。- init
初始化命令,在创建集群或者新加节点时会触发该命令的执行。- order
控制不同角色节点之间执行此命令顺序。比如主从节点,有时候需要主节点先启动服务,从节点后启动服务,非必填项。 - cmd
具体需执行的命令,默认在节点 start 服务之前执行,必填项。
- order
- start
服务启动命令,具体参数参考初始化命令 init。 - stop
停止服务命令,具体参数参考初始化命令 init。 - scale_out
加节点时在非新加节点上需执行的命令,具体参数参考初始化命令 init。 - scale_in
删除节点时在非删除节点上需执行的命令,在节点 stop 服务之前执行,具体参数参考初始化命令 init。 - destroy
销毁命令,在删除集群或者节点时会触发该命令的执行,默认在节点 stop 服务或 scale_in 服务之前执行,通常用作删除资源之前检查安全性,具体参数参考初始化命令 init。
这些命令在集群的生命周期中流程请见 应用实例生命周期。
- init
- role
- env
应用参数配置,比如 ZooKeeper 的 zoo.cfg 里的参数配置等。 - advanced_actions
集群支持高级操作,目前支持两类:变换网络 (change_vxnet) 和横向伸缩 (scale_horizontal) 即增加节点或删除节点,这是因为有些应用尤其传统应用并不适合云的弹性要求,因此如果您的应用支持切换网络则加上 change_vxnet,如果支持横向伸缩则加上 scale_horizontal。如果只有某一类角色需要切换网络或添加/删除节点,其它类型节点不支持,则可以只写到这个角色节点里。如果不支持此类操作则需去掉相应的定义,否则用户在界面看见有此功能而实际上是不支持的。