开发模板规范

    package.json 文件

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

    样例：

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

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

    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 定义的变量的输入，每个字段的具体描述如下：

    • name 新建应用的名称，必填项，但值可以为空。
    • description 新建应用描述，必填项，但值可以为空。
    • subnet 新建应用所在私有网络 ID，必填项。
    • role 多角色节点应用必填项，单角色应用可以无此项。角色名称自定义，但必须和 config.json 里定义的名字一致。

    • container 镜像信息，必填项。

    • 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，非必填项。
    • stop　停止服务命令，具体参数参考初始化命令 init。

    • scale_out　加节点时在非新加节点上需执行的命令，具体参数参考初始化命令 init。

      参数描述
      pre_check删除节点时在非删除节点上执行的预检查命令，若返回非0值表示不可删除节点。此项是 scale_in 和 scale_out 独有。

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

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

      参数描述
      allow_force是否允许强制删除, 默认值为 true 表示允许强制删除该节点, 强制删除时即使 destroy 的 cmd 返回非 0 值也会继续将节点删除。

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

    • custom_service 用户自定义命令，具体参数参考备份命令 backup，除此之外自定义的服务参数还有：
      参数描述
      typetype = custom 表示这个服务是自定义的， 自定义的名字 (即 key，此处为 custom_service) 开发者自行定义。
    • 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 内容示例如下：

    • cluster.json.tmpl 文件中 type 为 custom 的 service，会使用 service 的 key 作为用户执行自定义服务的展示内容，并进行国际化。