云应用开发指南

 

开发模板规范 - 基础版

更新时间 2023-09-06

基本介绍

此规范定义的是开发一个 AppCenter 云应用需要的基本元素,不包括国际化、监控告警和其它高级功能, 旨在让开发者快速入门,详细的规范请参考云应用开发模板规范 - 完整版

开发者提交一个应用需要包含以下几个文件:

  • 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": 101,
				"range": [101, 202],
				"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 文件索引的值,例如 {{cluster.name}} 表示 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, volume, 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": "pek3"
		},
		"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 镜像,则无需填写该字段)
- count - 节点个数,必填项,可以为0,但集群节点总数必须大于0。
- cpu - 每个节点 cpu 个数,可选值范围:1, 2, 4, 8, 12, 16, 24, 32, 64。
- memory - 每个节点内存大小,单位 MiB。可选值范围:1024, 2048, 4096, 6144, 8192, 12288, 16384, 24576, 32768, 40960, 49152, 65536, 81920, 98304, 114688, 131072, 163840, 196608, 229376, 262144, 327680。
- instance_class - 每个节点云服务器类型,可选值范围:101,202,301。其中 101 表示基础型云服务器,202 表示企业型 e2 云服务器,301 表示专业增强型云服务器。
- volume - 每个节点数据盘信息,如果此类节点不需要数据盘,不需要填写此项。
- size - 每个节点数据容量大小,单位 GiB,必填项。单张容量盘最小 100G,最大 5000G;单张性能盘,超高性能盘,基础型盘,企业级盘最小 10G,最大 2000G,且步长大小需是 10 的整数倍。单张 NeonSAN 盘最小 100G,最大 50000G,且步长大小需是 100 的整数倍。Linux 系统默认挂载在 /data 目录下。
- services  - 应用本身服务的初始化、启停等指令,青云 AppCenter 调度系统会发送这些命令到指定节点执行。非必填项。
- - init  初始化命令,在创建集群或者新加节点时会触发该命令的执行。order 控制不同角色节点之间执行此命令顺序。比如主从节点,有时候需要主节点先启动服务,从节点后启动服务,非必填项。cmd 具体需执行的命令,默认在节点 start 服务之前执行,必填项。
- - start 服务启动命令,具体参数参考初始化命令 init。
- - stop  停止服务命令,具体参数参考初始化命令 init。
- - scale_out  加节点时在非新加节点上需执行的命令,具体参数参考初始化命令 init。
- - scale_in 删除节点时在非删除节点上需执行的命令,在节点 stop 服务之前执行,具体参数参考初始化命令 init。
- - destroy 销毁命令,在删除集群或者节点时会触发该命令的执行,默认在节点 stop 服务或 scale_in 服务之前执行,通常用作删除资源之前检查安全性,具体参数参考初始化命令 init。
- - - 这些命令在集群的生命周期中流程请见 应用实例生命周期
env - - 应用参数配置,比如 ZooKeeper 的 zoo.cfg 里的参数配置等。
advanced_actions - - 集群支持高级操作,目前支持两类:变换网络 (change_vxnet) 和横向伸缩 (scale_horizontal) 即增加节点或删除节点,这是因为有些应用尤其传统应用并不适合云的弹性要求,因此如果您的应用支持切换网络则加上 change_vxnet,如果支持横向伸缩则加上 scale_horizontal。如果只有某一类角色需要切换网络或添加/删除节点,其它类型节点不支持,则可以只写到这个角色节点里。如果不支持此类操作则需去掉相应的定义,否则用户在界面看见有此功能而实际上是不支持的。
这篇文档解决了您的问题吗?
0
0