有奖捉虫:云通信与企业服务文档专题,速来> HOT
说明:

当前页面接口为旧版 API,未来可能停止维护。容器服务 API 3.0 版本接口定义更加规范,访问时延下降显著,建议使用 容器服务 API 3.0

1. 接口描述

本接口(CreateClusterService)用于创建服务。
接口请求域名:ccs.api.qcloud.com

2. 输入参数

以下请求参数列表仅列出了接口请求参数,其它参数见 公共请求参数

参数名称 描述 类型 必选
clusterId 集群 ID,请填写 查询集群列表 接口中返回的 clusterId 字段 String
serviceName 服务名,服务名称由小写字母、数字和 - 组成,由小写字母开头,小写字母或数字结尾, 且长度不超过63个字符 String
serviceDesc 服务描述 String
replicas 实例副本数 Int
portMappings.n 端口映射信息,当 accessType 为 None 时,不提供网络访问 Object Array
accessType 服务访问方式,不填默认 ClusterIP
LoadBalancer:为服务创建一个外网负载均衡,访问该负载均衡的 IP 和端口时,会把流量转发到该服务
SvcLBTypeInner:为服务创建一个内网负载均衡,在 VPC 内访问,需要指定 subnetId,该方式会占用该子网下的一个 IP
ClusterIP:不提供集群外访问该服务,只提供集群内其它服务访问,默认为 ClusterIP
None:不提供网络访问该服务,这种方式不用传参数 portMappings.n
String
labels.n 服务的标签定义 Map
containers.n 容器数组,一个服务必须定义一个或多个容器,服务创建时会启动定义的容器 Object Array
volumes.n 容器卷定义,如果 volumes.n 不填,容器对象里的 volumeMounts.n 字段也必须不填 Object Array
subnetId 子网 ID,请填写 查询子网列表 接口中返回的 unSubnetId(子网统一 ID)字段,accessType 为 SvcLBTypeInner 时必须传参数 String
namespace 命名空间,请填写 查询集群命名空间 接口中返回的 namespaces 字段,默认为 default String
nodeAffinity 节点亲和性,不支持1.4.6集群,节点亲和性调度使用 kubernetes 的 nodeAffinity 硬调度(requiredDuringSchedulingIgnoredDuringExecution)方式调度,当 Pod 发现没有满足条件的节点可以供调度使用时,会出现调度失败的情况 Object Array
podAffinity Pod亲和性,不支持1.4.6集群,指定该服务下的实例(pod)与其他实例(pod)的部署依赖,Pod 亲和性调度使用 kubernetes 的 podAffinity 硬调度(requiredDuringSchedulingIgnoredDuringExecution)方式调度,当Pod发现没有满足条件的节点可以供调度使用时,会出现调度失败的情况 Object Array
dispersePods 是否开启强制打散,1为是,0为否 Int
scaleType 伸缩类型,可选 manualScale 和 autoScale,不填写默认为 manualScale 类型 String
maxReplica 最大副本数(仅当 scaleType 为 autoScale 生效) Int
minReplica 最小副本数(仅当 scaleType为 autoScale 生效) Int
hpaMetricss hpa 相关控制指标 Object Array

portMappings 参数详细说明:

字段 描述 类型 必选
lbPort 当 accessType 为 LoadBalancer 和 SvcLBTypeInner :负载均衡监听端口和服务的监听端口
当 accessType 为 ClusterIP :服务的监听端口
Int
containerPort 容器监听的端口 Int
nodePort Node 上开启的端口,当 accessType 为 LoadBalancer 和 SvcLBTypeInner,如果省略,系统将自动分配一个 nodePort Int
protocol 协议,必须是 TCP 或者 UDP String

volumes 参数详细说明,详细解释可参考 数据卷挂载说明

字段 描述 类型 必选
name 容器卷名称 String
volumeType 容器卷类型,目前支持 hostPath、cbsDisk、configMap 和 nfsDisk
(对于 cbsDisk 类型,服务的实例数目只能是 1,因为 cbs 盘不支持多个节点同时挂载)
String
hostPath 当 volumeType 为 hostPath 时必填。容器启动时,容器卷在宿主机上的目录会映射到容器内,如果不填,会为该容器卷在 Node 上分配一个临时目录,当容器销毁时临时目录会被删除,如果指定了 hostPath,容器销毁时,该目录以及数据会被保留 String
cbsDiskId 当 volumeType 为 cbsDisk 时必填。cbs 网盘的 ID,容器启动时,会把该 cbs 盘挂载到容器所在的宿主机上,并映射到容器内,容器销毁时,会把该盘从宿主机上解挂载。请填写 查询云硬盘信息 接口中返回的 storageId ( 云硬盘 ID )字段 String
nfsPath 当 volumeType 为 nfsDisk 时必填。此字段为挂载 NFS 盘的路径,例如:127.0.0.1:/exports String
configId 当 volumeType 为 configMap 时必填。此字段为需要挂载的配置项Id String
configVersion 当 volumeType 为 configMap 时必填。此字段为需要挂载的配置项版本 String
configKeys.n 当 volumeType 为 configMap 时必填。此字段为需要挂载的配置项的Key的数组 Object Array

containers 参数详细说明:

参数名称 描述 类型 必选
containerName 容器名,不超过 63 个字符 String
image 容器镜像 String
envs.n 容器环境变量数组,详见 envs 定义,变量名只能包含大小写字母、数字及下划线,并且不能以数字开头 Object Array
volumeMounts.n 容器卷挂载点 Object Array
healthCheck.n 容器健康检查 Object Array
CPU 容器需要分配的 CPU 量 ( 单位:mU (千分之一核) ),最小100,既0.1核
不传参数或传0则为不限制
详情请参考 服务资源限制设置
Int
cpuLimits 容器能使用 CPU 的最大量 ( 单位:mU (千分之一核) ),最小100,即0.1核
不传参数或传0则为不限制,在不为0的情况下必须满足 cpuLimits >= CPU
详情请参考 服务资源限制设置
Int
memory 容器需要分配内存的量 ( 单位:MiB ),建议最小为4MiB
不传参数或传0表示不做限制,在不为0的情况下必须满足 memoryLimits >= memory,如果未传递 memoryLimits,则需求量与最大使用量默认一致
详情请参考 服务资源限制设置
Int
memoryLimits 容器最大能使用内存的量 ( 单位:MiB ),最小为4MiB
不传参数或传0表示不做限制
详情请参考 服务资源限制设置
Int
command 容器启动命令
详情请参考 服务运行命令和参数设置
String
arguments.n 容器启动参数
详情请参考 服务运行命令和参数设置
String Array
privileged 容器启动参数,true 为开启,false 为关闭,区分大小写
详情请参考 服务运行命令和参数设置
Bool
workingDir 容器启动参数
详情请参考 服务运行命令和参数设置
String

envs 参数详细说明:

字段 描述 类型
name 环境变量的名称 String
value 环境变量的 value String

volumeMounts 参数详细说明,详情请参考 数据卷挂载说明

字段 描述 类型
volumeName 卷名称 String
mountPath 卷在容器中的挂载点 String
mode 容器对卷的访问方式,ro 为只读,rw 为读写 String

healthCheck 参数详细定义,详情请参考 服务健康检查设置

字段 描述 类型
type 取值为 liveCheck 或者 readyCheck。liveCheck 用于检查容器是否存活,如果检查失败会重启容器,readyCheck 用于检查容器是否就绪,检查失败会停止对该容器的请求转发 String
healthNum 检查成功阈值,范围: 1 - 10次,liveCheck 只能为1 。表示需要连续检测成功的次数,例如: type 为 liveCheck,healthNum 为1,那么需要连续1次检测返回成功,才认为容器存活 Int
unhealthNum 检查失败阈值,范围:1 - 10次,表示需要连续检测失败的次数,例如:type 为 liveCheck,unhealthNum 为3,那么需要连续3次检测都返回失败,才认为容器已经死掉 Int
intervalTime 健康检查间隔时间,表示多久执行一次健康检查操作。单位:秒,范围:2 - 300秒 Int
timeOut 健康检查操作超时时间,单位秒,范围:2 - 60秒 Int
delayTime 容器启动后,多长时间后执行健康检查,默认值:0(马上启动健康检查),单位:秒,范围:0 - 60秒。注意,如果 type 为 readyCheck,在容器启动后的 delayTime 这段时间内,容器被认为是 unready 的,访问对应的服务时,请求不会被转发到该容器 Int
checkMethod 检查类型:methodTcp,methodHttp,methodCmd String
port 端口,范围:1 - 65535,当 checkMethod 为 methodTcp 和 methodHttp 时有效。如果 checkType 是 methodTcp,执行检查操作时会对容器的端口进行连接探测,连接成功则探测成功,否则失败。如果 checkType 为 methodHttp,会对容器的该端口发起 HTTP 或者 HTTPS 请求,请求返回的 httpcode 的范围在 200 - 399 ,则认为探测成功,否则失败 Int
protocol 当 checkMethod 为 methodHttp 时有效。对容器进行 HTTP 探测时的协议,只支持 HTTP 和 HTTPS String
path 当 checkMethod 为 methodHttp 时有效。对容器进行 HTTP 探测时,会构建一个 url:protocol://containerIp:port/path,然后对这个 url 发起 GET 操作进行探测。protocol 和 port 就是上面指定的参数 String
cmd 当 checkMethod 为 methodCmd 是有效。探测时会对容器执行 cmd 这个命令,如果执行结果返回0,则探测操作成功,否则失败 String

nodeAffinity 参数详细说明:

字段 描述 类型
key 指定节点亲和性的 Label 的 key 值 String
operator 亲和性的操作符,可为 In,NotIn,Exists,DoesNotExist,Gt,Lt String
values 指定节点亲和性 Label 的 value 值 String Array
说明:

例如 Node1 的 label 是:NodeType = S1.SMALL1, Node2 的 label 是:NodeType = S1.SMALL2, Node3 的 label 是:NodeType = S1.MEDIUM2. 创建服务是指定 nodeAffinity 参数是 NodeType In S1.SMALL1 那么该服务下的容器仅在 Node1下调度。

podAffinity 参数详细说明:

字段 描述 类型
key 指定 Pod 亲和性的 Label 的 key 值 String
operator 亲和性的操作符,可为 In,NotIn,Exists,DoesNotExist String
values 指定 Pod 亲和性 Label 的 value 值 String Array

hpaMetricss 参数详细说明:

字段 描述 类型
name HPA 触发策略名称 String
value HPA 触发策略的百分比值 Int

3. 输出参数

参数名称 描述 类型
code 公共错误码。0表示成功,其他值表示失败 Int
codeDesc 业务错误码。成功时返回 Success,错误时返回具体业务错误原因 String
message 模块错误信息描述,与接口相关 String

4. 示例

输入

  https://domain/v2/index.php?Action=CreateClusterService 
  ------------基础参数----------
  &clusterId=cls-xxxxx
  &serviceName=my-web-service
  &replicas=5
  &scaleType=autoScale
  ------------端口映射------------
  &accessType=LoadBalancer
  &portMappings.0.protocol=TCP
  &portMappings.0.containerPort=80
  &portMappings.0.lbPort=80
  &portMappings.0.nodePort=0
  ------------数据卷------------
  &volumes.0.name=vol
  &volumes.0.hostPath=
  &volumes.0.volumeType=hostPath
  ------------容器相关------------
  &containers.0.containerName=test
  &containers.0.image=nginx
  ------------资源限制------------
  &containers.0.cpu=200
  &containers.0.cpuLimits=300
  &containers.0.memory=128
  ------------环境变量------------
  &containers.0.envs.0.name=envkey1
  &containers.0.envs.0.value=envval1
  ------------挂载点------------
  &containers.0.volumeMounts.0.volumeName=vol
  &containers.0.volumeMounts.0.mountPath=/data
  &containers.0.volumeMounts.0.mode=rw
  ------------健康检查------------
  &containers.0.healthCheck.0.type=liveCheck
  &containers.0.healthCheck.0.checkMethod=methodHttp
  &containers.0.healthCheck.0.port=80
  &containers.0.healthCheck.0.protocol=HTTP
  &containers.0.healthCheck.0.path=/
  &containers.0.healthCheck.0.cmd=
  &containers.0.healthCheck.0.delayTime=0
  &containers.0.healthCheck.0.timeOut=2
  &containers.0.healthCheck.0.intervalTime=3
  &containers.0.healthCheck.0.healthNum=1
  &containers.0.healthCheck.0.unhealthNum=3
  ------------nodeAffinity------------
  &nodeAffinity.0.key=qcloud
  &nodeAffinity.0.operator=In
  &nodeAffinity.0.values.0=my-app
  ------------podAffinity------------
  &podAffinity.0.key=qcloud
  &podAffinity.0.operator=In
  &podAffinity.0.values.0=my-app
  ------------hpaMetricss------------
  &maxReplica=2
  &minReplica=1
  &hpaMetricss.0.name=cpuUtilization
  &hpaMetricss.0.value=20
  &其它公共参数

输出

  {
    "code": 0,
    "message": "", 
    "codeDesc": "Success"
}