说明:当前页面接口为旧版 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"
}