云应用开发指南

 

基本介绍

如果想快速了解规范可以先阅读应用开发模板规范 - 基础版。

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

• config.json

  该文件包含最终用户创建此应用实例时需设置的参数等信息，包括各种角色的节点配置、参数配置等。

• cluster.json.mustache

  该文件包含创建此应用实例时的基础架构、应用实例生命周期管理和自定义监控告警等信息，这是一个改进版的 mustache 文件。

• replace_policy.json

  类型替换策略

config.json 定义用户在 QingCloud 控制台部署应用时需要填写的表单。控制台支持语言国际化，默认情况下，所有语言都会按配置项中的 label 和 description 展示表单。另外，cluster.json.mustache 文件中的 custom service、监控项等，会使用 key 作为国际化展示。如果您想要适应不同的语言，需要在提交的应用中包含一个 locale 文件夹，并添加对应语言的翻译文件，如：

• locale/en.json

  英文翻译文件

• locale/zh-cn.json

  中文翻译文件

具体的翻译文件格式，请参考 国际化

注：以上文件不支持 “UTF-8 Unicode (with BOM) text” 文本格式，windows下的编辑器编辑文件默认是此格式，可通过 “格式-> 以utf-8无BOM格式编码” 进行转换。

规范

config.json

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

对于弹性裸金属服务器BM(BareMetal)类型的应用，不需要在 config.json 中配置CPU、内存、硬盘大小等信息，只需要配置弹性裸金属服务器的类型 instance_type 即可。

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

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

{
    "type": "array",
    "properties": [{
        "key": "cluster",
        "description": "cluster properties",
        "type": "array",
        "properties": [{
            "key": "name",
            "label": "Name",
            "description": "The name of the application",
            "type": "string",
            "default": "",
            "required": "no"
        }, {
            "key": "resource_group",
            "label": "Resource Configuration",
            "description": "The resource configuration of the service",
            "type": "string",
            "customizable": true,
            "default": "Standard",
            "range": ["Standard", "Enterprise", "Enterprise Plus"]
        }, {
            "key": "description",
            "label": "Description",
            "description": "The description of the application",
            "type": "string",
            "default": "",
            "required": "no"
        }, {
            "key": "vxnet",
            "label": "VxNet",
            "description": "The vxnet that the application will join",
            "type": "string",
            "default": "",
            "required": "yes"
        }, {***
            "key": "external_service",
            "label": "External Service",
            "description": "Choose an external service to use",
            "type": "service",
            "limits": {
                "app-id"***: ["app-version"***]
            },
            "allowed_operations": ["add", "modify", "delete"],
            "default": "",
            "required": "yes"
        }, {***
            "key": "role_name",
            "description": "role-based node properties",
            "label": "Role Name",
            "type": "array",
            "properties": [{
                "key": "loadbalancer",
                "label": "Loadbalancer Service",
                "description": "Choose a loadbalancer service to use",
                "type": "loadbalancer",
                "port": 80,
                "default": [],
                "required": "yes"
            }, {
                "key": "cpu",
                "label": "CPU",
                "description": "CPUs of each node",
                "type": "integer",
                "default": 1,
                "range": [1, 2, 4, 8, 16],
                "required": "yes",
                "resource_group": [1, 4, 16]
            }, {
                "key": "cpu_model",
                "label": "CPU Microarchitecture",
                "description": "CPU Microarchitecture",
                "type": "string",
                "default": "Westmere",
                "changeable_when_create": false,
                "range": [
                    "",
                    "Westmere",
                    "SandyBridge",
                    "IvyBridge",
                    "Haswell",
                    "Broadwell",
                    "Skylake",
                    "CascadeLake"
                ],
                "required": "no"
            }, {
                "key": "memory",
                "label": "Memory",
                "description": "Memory of each node (in MiB)",
                "type": "integer",
                "default": 2048,
                "range": [2048, 8192, 16384, 32768, 49152],
                "required": "yes"
            }, {
                "key": "gpu",
                "label": "GPU",
                "description": "GPUs of each node",
                "type": "integer",
                "default": 1,
                "range": [0, 1, 2],
                "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",
                "auto_scale_step": 2,
                "resource_group": [3, 5, 7]
            }, {
                "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": "gpu_class",
                "label": "GPU Class",
                "description": "The gpu type for the cluster to run，such as high performance",
                "type": "integer",
                "default": 0,
                "range": [0, 2],
                "required": "yes"
            }, {
                "key": "volume_class",
                "label": "Volume Class",
                "description": "The volume type for each instance，such as high performance，high performance plus，high capacity",
                "type": "integer",
                "default": 100,
                "range": [100, 200, 5],
                "required": "yes"
            }, {
                "key": "volume_size",
                "label": "Volume Size",
                "description": "The volume size for each instance",
                "type": "integer",
                "default": 10,
                "min": 10,
                "step": 10,
                "auto_scale_step": 10,
                "required": "yes"
            }, {
                "key": "replica",
                "label": "Replica",
                "description": "The replica number for each node with this role",
                "type": "integer",
                "default": 1,
                "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",
            "changeable": true,
            "default": "value1,value11",
            "separator": ",",
            "range": ["value1", "value11", "value111"],
            "multichoice": true, 
            "system": false,
            "required": "yes",
            "expanded": true
        }, {***
            "key": "role_name",
            "description": "The role configuration properties of the application",
            "type": "array",
            "properties": [{***
                "key": "param",
                "label": "Role Param",
                "description": "The param for all slave nodes",
                "type": "string",
                "changeable": true,
                "default": "value1",
                "range": ["value1", "value11"],
                "required": "yes"
            }]
        }]
    }, {
        "key": "service_params",
        "description": "Custom service configuration properties",
        "type": "array",
        "properties": [{***
            "key": "common.param",
            "label": "Common Param",
            "description": "The common.param1 for all nodes",
            "type": "string",
            "default": "value1,value11",
            "separator": ",",
            "range": ["value1", "value11", "value111"],
            "multichoice": true,
            "required": "yes"
        }, {***
            "key": "role_name",
            "description": "Custom service the role (role_name) configuration properties",
            "type": "array",
            "properties": [{***
                "key": "param",
                "label": "Role Param",
                "description": "The param for all slave nodes",
                "type": "string",
                "pattern": "^value.+",
                "default": "value1",
                "range": ["value1", "value11"],
                "required": "yes"
            }]
        }]
    }]
}

对于弹性裸金属服务器 BM(BareMetal) 类型的应用，我们无需配置 CPU、内存、硬盘大小等参数，只需指定弹性裸金属服务器的类型即可，示例见 config.json，与 KVM 类型应用稍有不同。

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

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

一些特殊项含义如下：

cluster.json.mustache

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

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

对于弹性裸金属服务器 BM(BareMetal) 的应用，配置文件会稍有不同，具体是无需配置CPU、内存、硬盘大小，类型等信息，因为弹性裸金属服务器的这些信息是固定的。具体配置文件可以参见 cluster.json.mustache

{
    "name": {{cluster.name}},
    "description": {{cluster.description}},
    "vxnet": {{cluster.vxnet}},
    "need_tag": false,
    "links": {
        "external_service"***: {{cluster.external_service}}
    },
    "exclude_node_columns": ["private_ip"],
    "need_intranet_api_server": false,
    "backup_policy": "device",
    "incremental_backup_supported": false,
    "upgrade_policy": [
        "appv-xxxxxxxx",
        "appv-yyyyyyyy"
    ],
    "upgrading_policy": "parallel",
    "nodes": [{***
        "role": "role_name",
        "loadbalancer": {{cluster.role_name.loadbalancer}},
        "container": {
            "type": "kvm",
            "image": "img-skhdp16m",
            "zone": "pek3a"
        },       
        "cpu": {{cluster.role_name.cpu}},
        "cpu_model": {{cluster.role_name.cpu_model}},
        "memory": {{cluster.role_name.memory}},
        "instance_class": {{cluster.role_name.instance_class}},
        "gpu": {{cluster.role_name.gpu}},
        "gpu_class": {{cluster.role_name.gpu_class}},
        "count": {{cluster.role_name.count}},
        "volume": {
            "size": {{cluster.role_name.volume_size}},
            "mount_point": "/data",
            "mount_options": "defaults,noatime",
            "filesystem": "ext4",
            "class": {{cluster.role_name.volume_class}}
        },
        "replica": {{cluster.role_name.replica}},
        "extra_quota": {
            "cpu": 2,
            "memory": 8,
            "instance_class": 101,
            "gpu": 2,
            "gpu_class": 0,
            "count": 2,
            "volume": {
                "size": 20,
                "count": 2,
                "class": 100
            },
            "loadbalancer": 2,
            "bucket": 2,
            "security_group": 2
        },
        "reserved_ips": {
            "wvip": {
                "value": ""
            }
        },
        "passphraseless": "ssh-dsa",
        "vertical_scaling_policy": "parallel",
        "user_access": false,
        "eip_class": "base",
        "services": {
            "init": {
                "nodes_to_execute_on": 1,
                "post_start_service": false,
                "cmd": "mkdir -p /bigdata1/myapp;/opt/myapp/bin/init-cluster.sh"
            },
            "start": {
                "order": 1,
                "cmd": "/opt/myapp/bin/start-server.sh"
            },
            "stop": {
                "cmd": "/opt/myapp/bin/stop-server.sh"
            },
            "scale_out": {
                "pre_check": "/opt/myapp/sbin/scale-out-pre-check.sh",
                "cmd": "/opt/myapp/sbin/scale-out.sh"
            },
            "scale_in": {
                "pre_check": "/opt/myapp/sbin/scale-in-pre-check.sh",
                "cmd": "/opt/myapp/sbin/scale-in.sh",
                "timeout": 86400
            },
            "restart": {
                "cmd": "/opt/myapp/sbin/restart-server.sh"
            },
            "destroy": {
                "allow_force": true,
                "nodes_to_execute_on": 1,
                "post_stop_service": true,
                "cmd": "/opt/myapp/sbin/destroy-server.sh"
            },
            "upgrade": {
                "cmd": "/opt/myapp/sbin/upgrade.sh"
            },
            "rollback": {
                "cmd": "/opt/myapp/bin/rollback.sh"
            },
            "get_nodes_order": {
                "event": ["upgrade", "rollback", "scale_vertical"],
                "cmd": "/opt/myapp/bin/get-nodes-order.sh"
            },
            "backup": {
                "cmd": "/opt/myapp/sbin/backup.sh",
                "nodes_to_execute_on": 1,
                "with_replica": false,
                "order": 1,
                "service_params": {
                    "service_param"***: {{service_params.role_name.param}}
                },
                "timeout": 86400
            },
            "restore": {
                "cmd": "/opt/myapp/sbin/restore.sh",
                "nodes_to_execute_on": 1,
                "with_replica": false,
                "order": 1,
                "service_params": {
                    "service_param"***: {{service_params.role_name.param}}
                },
                "timeout": 86400,
            },
            "delete_snapshot": {
                "cmd": "/opt/myapp/sbin/delete_snapshot.sh",
                "nodes_to_execute_on": 1,
                "order": 1,
                "service_params": {
                    "service_param"***: {{service_params.role_name.param}}
                },
                "timeout": 86400
            },
            "custom_service"***: {
                "type": "custom",
                "cmd": "/opt/myapp/sbin/custom_service.sh",
                "timeout": 86400,
                "service_params": {
                    "service_param"***: {{service_params.role_name.param}}
                }
            }
        },
        "server_id_upper_bound": 255,
        "env": {
            "param"***: {{env.role_name.param}}
        },
        "agent_installed": true,
        "custom_metadata": {
            "cmd": "/opt/myapp/sbin/get_token.sh"
        },
        "health_check": {
            "enable": true,
            "interval_sec": 60,
            "timeout_sec": 10,
            "action_timeout_sec": 30,
            "healthy_threshold": 3,
            "unhealthy_threshold": 3,
            "check_cmd": "/opt/myapp/bin/check.sh",
            "action_cmd": "/opt/myapp/bin/action.sh"
        },
        "monitor": {
            "enable": true,
            "cmd": "/opt/myapp/bin/monitor.sh",
            "items": {
                "item_name_x"***: {
                    "unit": "",
                    "value_type": "str",
                    "statistics_type": "avg",
                    "scale_factor_when_display": 1,
                    "enums": ["value_y"***]
                }
            },
            "groups": {
                "group_name_z"***: ["item_name_x"***]
            },
            "display": ["group_name_z"***, "item_name_x"***],
            "alarm": ["item_name_x"***]
        }
    }],
    "env": {
        "common.param"***: {{env.common_param}}
    },
    "advanced_actions": ["change_vxnet", "scale_horizontal", "associate_eip"],
    "endpoints": {
        "client": {
            "port": 2181,
            "protocol": "tcp"
        },
        "reserved_ips": {
            "rvip": {
                "value": ""
            }
        }
    },
    "metadata_root_access": false,
    "health_check": {
        "enable": true,
        "interval_sec": 60,
        "timeout_sec": 10,
        "action_timeout_sec": 30,
        "healthy_threshold": 3,
        "unhealthy_threshold": 3,
        "check_cmd": "/opt/myapp/bin/check.sh",
        "action_cmd": "/opt/myapp/bin/action.sh"
    },
    "monitor": {
        "enable": true,
        "cmd": "/opt/myapp/bin/monitor.sh",
        "items": {
            "item_name_x"***: {
                "unit": "",
                "value_type": "str",
                "statistics_type": "avg",
                "scale_factor_when_display": 1,
                "enums": ["value_y"***]
            }
        },
        "groups": {
            "group_name_z"***: ["item_name_x"***]
        },
        "display": ["group_name_z"***, "item_name_x"***],
        "alarm": ["item_name_x"***]
    },
    "display_tabs": {
        "node_details_tab": {
            "cmd": "/opt/myapp/bin/node_details_tab.sh",
            "roles_to_execute_on": ["master", "slave"],
            "description": "More infomation about nodes",
            "timeout": 10
        }
    }
}

name

新建应用的名称，必填项，但值可以为空。

description

新建应用描述，必填项，但值可以为空。

vxnet

新建应用所在网络 ID，必填项。

need_tag

部署的集群内会创建一些其他资源，希望这些资源与集群同生命周期：随着集群销毁一并销毁。 need_tag 值为 true 时，会为集群绑定一个 tag_id，并注册到 metadata service， 参见Metadata 服务中的 cluster_tag， 所有集群内通过 api 创建的资源，需要调用 api 绑定上这个 tag_id, 这样创建的资源，会在集群详情页以列表形式展示给用户，支持的资源包括： volume、loadbalancer、eip、security_group、snapshot、nic。

need_intranet_api_server

部署的集群，是否需要依赖 intranet api server，进行云平台 api 的调用。若环境基础网络中未部署 intranet api server，会报错。

exclude_node_columns

部署后的集群详情页中，哪些列不需要展示，目前支持 private_ip 表示不展示 ip 列，非必填项。

links

新建应用可能会依赖外部应用，比如 Kafka 依赖 ZooKeeper，依赖名称可以任意命名，不一定是 external_service，比如命名为 zk_service；可以依赖多个外部应用，非必填项。

集群创建完成后，可对集群的依赖进行修改。用户可进行的操作在 config.json 外部依赖 allowed_operations 定义
add 表示用户可以在集群创建后添加外部依赖集群，即使现在仍然有集群，仍然可添加
modify 表示用户可以对集群中现有的依赖集群进行替换，替换成允许的应用版本的其它集群
delete 表示用户可以删除集群中现有的依赖集群，如果未定义 add 操作，则删除之后不能再添加回来

backup_policy

定义应用的备份策略，支持 “device” 和 “custom” 两种类型。“device” 表示对节点的挂盘做snapshot；“custom” 则是使用自定义的备份命令进行备份操作，比如备份到某个目录，或拷贝到某个节点。非必填项。

incremental_backup_supported

定义应用是否支持增量备份。备份分为全量备份和增量备份，全量备份每次创建新的备份链，而增量备份会在原有备份链上基于上一个备份点创建新的备份点，删除备份链上某一备份点后，其后的所有备份点都会被相应删除。默认值为 false 表示只支持全量备份，非必填项。

upgrade_policy

定义当前应用的哪些版本可以升级到当前版本，新老版本之间 role 必须相同，数据盘挂载位置必须一致。由于升级后会替换集群的镜像，所以在开发阶段_请仔细测试升级功能_。

upgrading_policy

定义版本升级的模式，支持parallel、sequential、in-place-parallel 和 in-place-sequential，默认是parallel，非必填项。

注：升级后再开启集群将会以新版本的镜像启动。对于 user_access 为 true 的节点也会使用新的镜像启动，请在使用说明中提醒用户自行备份 user_access 为 true 节点上的数据。

• parallel：并行升级，需要关闭集群才能执行，集群节点会同 时启动并执行升级，因此升级的过程中集群提供的服务会短时中断，升级失败时，需先关闭集群再降级或启动。
• sequential：滚动升级，需要集群在开机状态才能执行，集群节点会逐个重启并执行升级，这样集群提供的服务不会中断，滚动升级的流程参考集群升级，升级失败时，需先关闭集群再降级或启动。
• in-place-parallel：原地并行升级，不更新 image，所以不需要重启云服务器，定义方式可以参考：如何定义原地升级方式，拷贝数据完成后，按照 upgrade 的 order 顺序，并行执行 cmd。升级失败时，只支持集群活跃状态下再次升级或降级，降级时，按照 rollback 的 order 顺序，并行执行 cmd。升级完成后，关闭集群再启动集群会替换 image（只有在升级或降级成功后才会替换；升级失败，关闭启动，不会更新 image）。
• in-place-sequential：原地串行升级，不更新 image，所以不需要重启云服务器，定义方式可以参考：如何定义原地升级方式，拷贝数据完成后，按照 get_nodes_order 的执行结果，以及 upgrade 的 order 顺序，串行执行 cmd。升级失败时，只支持集群活跃状态下再次升级或降级，降级时，按照 get_nodes_order 的执行结果，以及 rollback 的 order 顺序，串行执行 cmd。升级完成后，关闭集群再启动集群会替换 image（只有在升级或降级成功后才会替换；升级失败，关闭启动，不会更新 image）。

nodes

新建应用节点信息，必填项。一个应用的节点可能是无角色区分的，这个时候 nodes 只有一种角色的信息；也可能是多角色组成的复杂应用，这个时候 nodes 就是这些角色节点信息组成的一个数组。

role

多角色节点应用必填项，单角色应用可以无此项。角色名称自定义，但必须和 config.json 里定义的名字一致。

loadbalancer

新建应用可能会依赖负载均衡器，不同角色 (role) 以依赖不同的负载均衡器。

container

镜像信息，必填项。

cpu

每个节点 cpu 个数，可选值范围：1, 2, 4, 8, 12, 16, 24, 32, 64。

cpu_model

节点的 CPU 体系结构，可选值范围：Westmere、SandyBridge、IvyBridge、Haswell、Broadwell、Skylake、CascadeLake。 查看对应的 CPU 指令集

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

节点类型，可选值范围：0, 1, 101, 201, 202, 301。其中 0 表示性能云服务器，1 表示超高性能云服务器，101 表示基础型云服务器，201 表示企业型 e1 云服务器，202 表示企业型 e2 云服务器，301 表示专业增强型云服务器。可选项，默认值为 0。

建议值：101, 202, 301。其中 0, 1, 201 这三种云服务器类型，会逐步做下架处理，故不建议使用。

gpu

每个节点 gpu 个数，可选值范围：0, 1, 2, 4, 8。目前仅在 北京3区-A(pek3a)，北京3区(pek3b，pek3c，pek3d) 和 上海1区(sh1a) 可创建带 gpu 的集群, 具体使用方式参考GPU 云服务器

gpu_class

节点 gpu 类型，可选值范围：0，2。其中 0 表示 NVIDIA GPU，2 表示 AMD GPU。可选项，默认值为0。

count

节点个数，必填项，可以为0，但集群节点总数必须大于0。

volume

每个节点数据盘信息，如果此类节点不需要数据盘，不需要填写此项。

建议值：100, 200。其中 0, 3 这两种云服务器类型，会逐步做下架处理，故不建议使用。

replica

此类节点每个节点的副本个数，这是给分片式 (即多主多从，如 redis cluster) 分布式系统使用的功能，定义每个分片的 master 有多少个 replica。 这类应用需要指定 role 名称比如 master，副本节点的 role 系统会自动在 master 添加 -replica 后缀，如 master-replica。 因此开发者在定义节点角色名称时不能定义后缀为 “-replica”，这是一个系统保留命名规则。replica 为非必填项。

extra_quota

除了集群内部资源以外，额外需要使用的资源列表。这些独立资源都有自己的配额限制，部署带有 extra_quota 的集群时，会对 extra_quota 中的资源进行额外的配额校验，校验失败会提示用户申请特定资源的配额，防止资源配额不足而导致的部署失败。

reserved_ips

表示集群要预留一些 IP 资源给当前角色节点，由应用自己来分配使用，如果无此需求可不定义。

passphraseless　

生成密钥信息，即提供此类节点能无密码登录其它节点的可能性，但青云调度系统只负责把此信息注册到 metadata service 中，开发者自行去获取密钥配置云服务器。目前支持 ssh-dsa, ssh-rsa，非必填项。

vertical_scaling_policy

配置纵向伸缩时的操作策略，目前支持：sequential 和 parallel，默认是 parallel 即并行操作，非必填项。比如 ZooKeeper 在扩容时希望不影响对外服务，可设置该值为 sequential，串行重启。

user_access　

是否允许用户访问，true 表示该角色节点允许用户通过 vnc 登录，默认值为 false， 该镜像的初始用户名和密码需要在“版本描述”中写清楚以便告知用户。 允许用户登录的节点在集群非活跃状态如关闭时不会销毁云服务器，所以用户可以往这类云服务器写入数据。 而其它云服务器是不会持久化数据，必须在挂盘上持久化数据， 参见制作 KVM 镜像。

eip_class

是否为节点绑定基础网络ip，只支持值为base，表示绑定基础网络ip。如果配置此项，则在集群创建时会自动为角色中的每个节点绑定基础网络ip，并给基础绑定上默认的防火墙。如果在集群横向扩容的过程中，配置了此项的角色节点数量为0，则会自动解绑集群防火墙。

server_id_upper_bound

节点的 index 的上限，从1开始记起，有些服务如 ZooKeeper 要求这个 index (myid) 必须控制在某一个范围内。缺省没有上限，非必填项。

services　

应用本身服务的初始化、启停等指令，青云 AppCenter 调度系统会发送这些命令到指定节点执行，非必填项。

init　

初始化命令，在创建集群或者新加节点时会触发该命令的执行。

start

服务启动命令，具体参数参考初始化命令 init。

stop　

停止服务命令，具体参数参考初始化命令 init。

scale_out　

加节点时在非新加节点上需执行的命令，具体参数参考初始化命令 init。 同时系统会捕获这个命令的非0返回值作为错误码, 参考执行操作失败时如何展示给用户错误提示。

scale_in

删除节点时在非删除节点上需执行的命令，具体参数参考初始化命令 init。 同时系统会捕获这个命令的非0返回值作为错误码, 参考执行操作失败时如何展示给用户错误提示。

restart

服务重启动命令，具体参数参考初始化命令 init。

destroy

销毁命令，在删除集群或者节点时会触发该命令的执行，通常用作删除资源之前检查安全性，具体参数参考初始化命令 init。

post_stop_service　

控制销毁命令是在 stop 命令执行完毕后执行还是之前执行，如果 post_stop_service 为 true 则表示 destroy 在 stop 后执行；默认 (即不加此项) 是之前执行。此项是 destroy 独有。

upgrade

升级集群后执行的命令，具体参数参考初始化命令 init。

get_nodes_order

在特定生命周期，以 cmd 的返回结果作为执行指令的顺序。具体参数参考初始化命令 init。 参考串行纵向扩容或滚动升级时，如何按照一定顺序进行操作。

rollback

升级失败，集群为活跃状态时进行降级操作，会被调用。具体参数参考初始化命令 init。

backup

定义该角色的备份操作，若不定义表示该角色不支持备份。若 “backup_policy” 定义为 “custom” 则必须定义 cmd；若 “backup_policy” 定义为 “device” 可不定义 cmd，具体参数参考初始化命令 init，除此之外自定义的服务参数还有：

注：提供手动备份的同时也会提供 “定时自动备份” 支持，手动备份时会以 json 形式传入用户填入具体 “service_params” 到 backup 的 cmd，而 “定时自动备份” 操作时不会传入参数。

restore

定义该角色的备份恢复操作。若该角色定义该服务，恢复时使用 restore 进行恢复；若该角色未定义该服务，恢复时使用 start 进行恢复。具体参数参考备份命令 backup。

注：若 “backup_policy” 定义为 “custom”，备份恢复操作会在当前集群完成；若 “backup_policy” 定义为 “device”，备份恢复操作会使用挂盘的 snapshot 创建一个新的集群。

delete_snapshot

定义备份删除操作。若 “backup_policy” 定义为 “custom” 则必须定义 cmd；若 “backup_policy” 定义为 “device” 可不定义 cmd。具体参数参考备份命令 backup。

这几个服务都是系统定义的；除了 post_start_service 是 init, upgrade 独有、post_stop_service 是 destroy 独有之外，其它配置项每个服务都可配置，比如控制 stop 服务 order 等。 这些命令的执行顺序请见 应用实例生命周期。

custom_service

用户自定义命令，具体参数参考备份命令 backup，除此之外自定义的服务参数还有：

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

env

特定角色节点的应用参数配置，每类应用有自身特有的可配置应用参数，每类节点也会有不同于应用全局级别的可配置参数。注意：节点之间或节点与集群全局之间的参数没有任何关系，都是独立的。

agent_installed

如果用户想利用这套框架管理纯云服务器集群，则可以不用装青云提供的 App agent，同时需要指定这个参数为 false，否则系统会提示错误，该参数默认为 true。

custom_metadata

节点通过脚本生成的 token (string 类型或返回 json 格式的 string) 需要注册到 metadata service 里供其它节点使用，例如开源容器集群管理系统 (Docker Swarm, Kuburnetes) 会用到此类信息。它是在 start service 之前执行，如果 start 之前有 init 则在 init 之后 start 之前执行。

health_check

特定角色节点的健康检查配置，每类应用有自身特有的可配置健康检查参数， 每类节点也会有不同于应用全局级别的可配置健康检查参数。详情请见 应用 health check。

env

应用参数配置，比如 ZooKeeper的 zoo.cfg 里的参数配置等。

advanced_actions

集群支持高级操作，分别为:

• 横向伸缩 (scale_horizontal) 即增加节点或删除节点，如果支持横向伸缩可以加上 scale_horizontal。
• 变换网络 (change_vxnet) 如果您的应用支持切换网络可以加上 change_vxnet。
• 绑定公网IP (associate_eip) 如果该角色的节点需要直接绑定公网IP可以加上 associate_eip，注意: 绑定公网IP会给这个集群绑定默认集群防火墙, 其他集群如果需要访问这个集群请在集群防火墙中添加对应放行规则。

如果只有某一类角色支持高级操作，其它类型节点不支持，则可以只写到这个角色节点里。如果不支持此类操作则需去掉相应的定义，否则用户在界面看见有此功能而实际上是不支持的。请仔细测试您在advanced_actions中定义的功能

endpoints

应用可定义 endpoints 供第三方使用，服务名称可以自定义，但建议使用通用的名称比如 client，manager 等，这样第三方应用使用的时候更方便一些，被第三方应用使用的可能性更大一些。详细的服务信息必须包括 port，但 protocol 非必须项，即可以不提供 protocol 信息。port 除可以是整数端口外，也可以是一个指向 env 的变量，如 “port”:“env.port"或 “port”:“role_name.env.port”，这样用户在更新这个变量的时候会自动更新其关联的 endpoint 端口。如果您的应用是一个大家熟知的且 enpoint 不会被修改，可以省略这一定义，比如 ZooKeeper，通用端口是 2181，所以可以省略掉。

reserved_ips

表示集群要预留一些 IP 资源，由应用自己来分配使用，如果无此需求可不定义。预留 IP 的成员名称由开发者指定，比如这里定义为 “rvip”，暂时不支持指定 IP，所以定义时 “value” 的值为空。然后系统会为该集群分配一个 IP 并更新到 “value” 中。比如系统预留了 192.168.0.250 这个地址给 “rvip”，则 reserved_ips 的信息为：

{
    "reserved_ips": {
        "rvip": {
            "value":"192.168.0.250"
        }
    }
}

metadata_root_access

有一些应用用来管理其它应用，因此需要通过 metadata service 获取其它应用实例的信息，默认情况下 (metadata_root_access 为 false) 本应用只能获取自身集群 (即 self) 的信息和通过 self 下的 links 获取外部集群信息，如果设置 metadata_root_access 为 true，则能获取 metadata service 下所有集群的信息。如果您的应用不属于此类管理型应用，则不用设置此项。

下例示范 tmpl 模板文件遍历所有集群节点 ip 地址 (假定都是无角色的节点)

{{range gets "/clusters/*/hosts/*/ip"}}{{.Value}}
{{end}}

下例示范 tmpl 模板文件遍历某一类 App 的所有集群

{{$appID := "app-pjkzvd1"}}
{{range gets"/clusters/*/cluster/app_id" | filter $appID}}
{{$string := split .Key "/"}}
{{$cluster_id := (index $string 2)}}
{{end}}

下例示范 tmpl 模板文件遍历某几类 App 的所有集群

{{$appID1 := "app-pjkzvd1"}}
{{$appID2 := "app-ascz121"}}
{{$appID3 := "app-mjkrm56"}}
{{$exp := printf "%s|%s|%s" $appID1 $appID2 $appID3}}
{{range gets"/clusters/*/cluster/app_id" | filter $exp}}
{{$string := split .Key "/"}}
{{$cluster_id := (index $string 2)}}
{{end}}

health_check

应用可以配置健康检查，详细的配置参数如下：

应用节点会继承应用的健康检查配置，当应用节点配置了相同的健康检查参数时，优先使用节点的配置。注明：前端在创建集群之后需要等大约５分钟左右服务检测才会展现出来。

monitor

应用可以配置可采集的监控数据，详细的配置参数如下：

enable

是否开启监控，默认值为 false。

cmd

监控数据采集脚本。脚本应保证在5秒内完成，采集的数据以 JSON Object 的方式输出，JSON Object 的 key 是监控项的名字 (item_name)，value 是监控项的值，例如： {“received”: 1200，“sent”: 1234，“connections”: 10}。如果 image 是基于 Windows 操作系统，目前仅支持 bat 脚本。

items

设置采集的监控项，监控项的个数不能超过50。“items” 对应的值是一个 JSON Object，该 JSON Object 的 key 是监控项的名字 (item_name)，value 是监控项配置，详细的监控项配置参数如下：

• unit : 监控项的计量单位，默认值为空字符串(”")。
• enums: 当 value_type 为 “str” 的时候才需要该字段，枚举出该监控项可能的 value 值(为了方便用户配置告警)。
• scale_factor_when_display: 指定在前端展示时，采集数据的放大倍数，默认值为1。该配置只支持值类型为 “int” (整型)的监控数据。
• value_type : 监控项的值类型,目前支持 “int” (整型)和 “str” (字符串型)，默认值为 “int”。对于浮点型数据，可以通过乘于一个倍数(例如100)将其转化成整型，并将 scale_factor_when_display 设为该倍数的倒数(例如0.01)来实现数据的采集。
• statistics_type : 指定监控项值的统计方式，目前支持如下方式：

值类型为 “int” (整型)的监控数据，支持以上所有类型的统计方式，默认的统计方式为 “avg”。 值类型为 “str” (字符串型)的监控数据，只支持 “mode” 和 “latest” 两种统计方式，默认的统计方式为 “latest”。

groups

设置监控组，每个监控组可以包含1～5个监控项。“groups” 对应的值是一个 JSON Object，该 JSON Object 的 key 是监控组的名字 (group_name)，value 是一个 JSON Array，该 Array 中的每个元素是一个监控项的名字 (item_name)。

display

指定监控数据的显示顺序，其值是一个 JSON Array，该 JSON Array 中的每个元素可以是一个监控组的名字 (group_name)，也可以是一个监控项的名字 (item_name)。item_name 和 group_name 会进行国际化，如果想要提供各语言环境下的监控项描述，请提供翻译文件。

alarm

告警指标，其值是一个 JSON Array，该 JSON Array 中的每个元素必须是上面某个监控项的名字 (item_name)，这里的每一项都会成为"控制台-管理-监控告警"下的一个告警指标。

应用节点会继承应用的监控配置，当应用节点配置了相同的监控参数时，优先使用节点的配置。注明：前端在创建集群之后需要等５分钟监控项才会展现出来。

display_tabs

自定义TAB页，TAB页中的信息会以表格的形式展现出来。开发者可以配置此项以在集群详情页显示更多的自定义信息。例如，集群发生主从切换后，节点新的主从信息，节点新的状态。配置应用于整个集群，不支持分角色定义。

• node_details_tab　必填项，需展示的TAB页标题，该key为自定义并且可定义多个，但最多不超过5个，该标题可定义国际化。

• cmd　必填项，开发者自定义的命令，调度系统会随机选择集群中的节点去执行。返回的结果需是完整的JSON格式字符串，表格标题以labels来标识，数据行以data，所以命令执行返回的JSON必须包含这两个键。标题的个数不能超过５个，数据的行数不能超过225行。例如

{
    "labels": ["node_id", "role"], 
    "data":
    [
        ["cln-xyzw1234", "master"], 
        ["cln-xyzw1235", "slave"]
    ]
}

• roles_to_execute_on 非必填项，如填写此项，则命令只会在指定的角色节点上执行，若集群创建完成时，没有指定角色的节点存在则会报错。不配置此项则会在所有的节点里随机选取节点执行。

• description 非必填项，显示在表格的顶部，起到描述表格的作用，帮助用户更好地理解表格的内容，该描述可以定义国际化。

• timeout 非必填项，命令执行的timeout时长，单位s，最大值和默认值为10，如果命令执行时长超过最大值将被终止。

replace_policy.json

此配置文件可以根据区域的不同，替换用户所能部署的资源情况。

{
    "pek3b": {
        "instance_class": [{
            "src": "0",
            "dst": 101
        }, {
            "src": "1",
            "dst": 202
        }],
        "volume_class": [{
            "src": "0",
            "dst": 100
        }, {
            "src": "3",
            "dst": 200
        }]
    },
    "gd2b": {
        "cpu_model": [{
            "src": "Broadwell",
            "dst": "CascadeLake"
        }]
    }
}

上述配置，在 pek3b 部署当前版本的集群时，配置包中 instance_class 为 0 值时，会自动替换为 101 展示和部署。

一般情况无需此文件

数据类型

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

国际化

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

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

{
    "Master": "主节点",
    "Slave": "从节点",
    "CPU": "CPU",
    "Memory": "内存",
    "VxNet": "私有网络",
    "The name of the service": "服务名称",
    "The description of the service": "服务描述",
    "CPUs of each node": "每个节点的 CPU 数量",
    "Memory of each node (in MiB)": "每个节点的内存大小（单位 MiB）",
    "The vxnet that the application will join": "应用运行的私有网络环境",
    "change_vxnet": "切换私有网络",
    "scale_horizontal": "横向扩容",
    "err_code1": "主从切换中，无法删除节点",
    "notice_when_upgrade": "此版本不兼容旧版 API"
}

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

• config.json 文件中，角色名称、节点配置、私有网络、外部依赖、环境变量 env 各配置项的 label 作为待填写项名称，description 作为待填项的描述。label 和 description 会进行国际化。
• cluster.json.mustache 文件中 type 为 custom 的 service，会使用 service 的 key 作为用户执行自定义服务的展示内容，并进行国际化。
• cluster.json.mustache 文件中 monitor 部分的 group_name，item_name，会在用户看到的监控视图中，作为监控项名称展示，并进行国际化。
• type 为 custom 的 service、新增节点、删除节点在执行 cmd 返回非 0 值时，视为操作失败，可以将 err_code 后面跟着退出码（err_code1）作为 key，value 为展示给用户的错误提示，样例参考：执行操作失败时如何展示给用户错误提示
• 升级操作时可给用户弹出提示，key 为 notice_when_upgrade，value 为提示内容。样例参考：升级操作时如何给用户弹出提示