说明:当前页面接口为旧版 API,未来可能停止维护。容器服务 API 3.0 版本接口定义更加规范,访问时延下降显著,建议使用 容器服务 API 3.0。
1. 接口描述
本接口 ( ModifyClusterService ) 用于修改服务。
接口请求域名:ccs.api.qcloud.com
。
2. 输入参数
以下请求参数列表仅列出了接口请求参数,其它参数见 公共请求参数。
注意:
· 修改服务和创建服务的参数除 strategy 和 minReadySeconds 以外,其余都一样。
·修改服务时,需要把服务所有的参数都传过来,如果新服务的部分参数跟原服务一样,这些参数也需要一并带上。
·如果只是调整服务的副本数和修改服务的描述,请使用修改服务副本数和修改服务的接口。
参数名称 | 描述 | 类型 | 必选 |
---|---|---|---|
clusterId | 集群 ID,请填写 查询集群列表 接口中返回的 clusterId 字段 | String | 是 |
serviceName | 服务名,服务名称由小写字母、数字和 - 组成,由小写字母开头,小写字母或数字结尾, 且长度不超过 63 个字符 | String | 是 |
serviceDesc | 服务描述 | String | 否 |
replicas | 实例副本数 | Int | 是 |
strategy | 服务更新策略:Recreate 或 RollingUpdate Recreate 方式在更新服务之前,kill 该服务下所有的容器,然后根据新的参数重新创建容器 RollingUpdate 方式对容器进行滚动升级,先 kill 部分容器,再根据新的参数创建部分新的容器,当新的容器启动后,重复 kill 旧容器和创建新容器,直至所有新容器都创建成功,旧容器都 kill 完,实现一个灰度发布的过程 |
String | 是 |
minReadySeconds | 单位秒。滚动升级时,部分新的容器启动后,接着启动新的容器的等待时间,例如 minReadySeconds 设置成 10,集群会先启动 1 个新的容器,如果新的容器起来了,将会等待 10s 后,再启动 1 个新的容器,直到新容器的数目达到 replicas 的数目 | Int | 否 |
accessType | 服务访问方式,不填默认为 ClusterIP LoadBalancer:为服务创建一个外网负载均衡,访问该负载均衡的 IP 和端口时,会把流量转发到该服务 SvcLBTypeInner:创建一个内网负载均衡,在 VPC 内访问,需要指定 subnetId ,会占用该子网下的一个 IP ClusterIP:该服务不提供集群外访问,只供集群内其它服务访问,默认为 ClusterIP None:不提供网络访问,这种方式不用传参数 portMappings.n |
String | 否 |
portMappings.n | 端口映射信息,当 accessType 为 None 时,不提供网络访问 | Object Array | 否 |
volumes.n | 容器卷定义,如果 volumes.n 不填,容器对象里的 volumeMounts.n 字段也必须不填。 | Object Array | 否 |
containers.n | 容器数组,一个服务必须定义一个或多个容器,服务创建时会启动定义的容器 | Object Array | 是 |
namespace | 命名空间,请填写 查询服务列表 接口中返回的 namespace 字段,默认为 default | String | 否 |
subnetId | 子网 ID,请填写 查询子网列表 接口中返回的 unSubnetId ( 子网统一 ID )字段, accessType 为 SvcLBTypeInner 时必须传参 | 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 | 否 |
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 会挂载到容器所在的宿主机上,并映射到容器内,容器销毁时,会将该盘从宿主机上解挂载。请填写 查询云硬盘信息 接口中返回的 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 | 容器环境变量数组,变量名只能包含大小写字母、数字及下划线,并且不能以数字开头 | 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 ),建议最小为 4 MiB 不传参数或传0表示不做限制,在不为 0 的情况下必须满足 memoryLimits >= memory,如果未传递memoryLimits,则需求量与最大使用量默认一致 详情请参考 服务资源限制设置 |
Int | 否 |
memoryLimits | 容器最大能使用内存的量 ( 单位:MiB ),最小为 4 MiB 不传参数或传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 次,表示需要连续检测成功的次数,例如: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 或者 HTTP 请求,请求返回的 httpcode 的在 200 ~ 399 范围,则认为探测成功,否则失败 | Int |
protocol | 当 checkMethod 为 methodHttp 时有效。对容器进行 HTTP 探测时的协议,只支持 HTTP 和 HTTPS | String |
path | 当 checkMethod 为 methodHttp 时有效。对容器进行 HTTP 探测时,会构建一个 url:protocol://containerIp:port/path ,然后对这个 url 发起 GET 操作 |
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 |
3. 输出参数
参数名称 | 描述 | 类型 |
---|---|---|
code | 公共错误码。0 表示成功,其他值表示失败 | Int |
codeDesc | 业务侧错误码。成功时返回 Success,错误时返回具体业务错误原因 | String |
message | 模块错误信息描述,与接口相关 | String |
4. 示例
输入
https://domain/v2/index.php?Action=ModifyClusterService
------------基础参数----------
&clusterId=cls-xxxxx
&serviceName=my-web-service
&replicas=1
&strategy=Recreate
&minReadySeconds=1
------------端口映射------------
&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
&其它公共参数
输出
{
"code": 0,
"message": "",
"codeDesc": "Success"
}