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

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