更新时间:2023-07-03 GMT+08:00

更新指定的集群

功能介绍

该API用于更新指定的集群。

集群管理的URL格式为:https://Endpoint/uri。其中uri为资源路径,也即API访问的路径。

URI

PUT /api/v3/projects/{project_id}/clusters/{cluster_id}

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

项目ID,获取方式请参见如何获取接口URI中参数

cluster_id

String

集群ID,获取方式请参见如何获取接口URI中参数

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

Content-Type

String

消息体的类型(格式)

X-Auth-Token

String

调用接口的认证方式分为Token和AK/SK两种,如果您使用的Token方式,此参数为必填,请填写Token的值,获取方式请参见获取token

表3 请求Body参数

参数

是否必选

参数类型

描述

spec

ClusterInformationSpec object

具体集群参数

metadata

ClusterMetadataForUpdate object

集群基本信息,包含与名称相关的字段

表4 ClusterInformationSpec

参数

是否必选

参数类型

描述

description

String

集群的描述信息。

  1. 字符取值范围[0,200]。不包含~$%^&*<>[]{}()'"#\等特殊字符。

  2. 仅运行和扩容状态(Available、ScalingUp、ScalingDown)的集群允许修改。

customSan

Array of strings

集群的API Server服务端证书中的自定义SAN(Subject Alternative Name)字段,遵从SSL标准X509定义的格式规范。

  1. 不允许出现同名重复。

  2. 格式符合IP和域名格式。

示例:

SAN 1: DNS Name=example.com
SAN 2: DNS Name=www.example.com
SAN 3: DNS Name=example.net
SAN 4: IP Address=93.184.216.34

containerNetwork

ContainerNetworkUpdate object

容器网络参数,包含容器网段的信息。

eniNetwork

EniNetworkUpdate object

云原生网络2.0网络配置,包含CCE Turbo集群的容器子网信息。

hostNetwork

hostNetwork object

节点网络参数,包含了Node节点默认安群组设置

表5 ContainerNetworkUpdate

参数

是否必选

参数类型

描述

cidrs

Array of ContainerCIDR objects

容器网络网段列表。1.21及新版本集群,当集群网络类型为vpc-router时,支持增量添加容器网段。

此参数在集群更新后不可更改,请谨慎选择。

表6 ContainerCIDR

参数

是否必选

参数类型

描述

cidr

String

容器网络网段,建议使用网段10.0.0.0/12~19,172.16.0.0/16~19,192.168.0.0/16~19。

表7 EniNetworkUpdate

参数

是否必选

参数类型

描述

subnets

Array of NetworkSubnet objects

IPv4子网ID列表。1.19.10及以上版本的CCE Turbo集群支持多容器子网,同时支持增量更新容器子网列表。 只允许新增子网,不可删除已有子网,请谨慎选择。

请求体中需包含所有已经存在的subnet。

表8 NetworkSubnet

参数

是否必选

参数类型

描述

subnetID

String

用于创建控制节点的subnet的IPv4子网ID(暂不支持IPv6)。获取方法如下:

  • 方法1:登录虚拟私有云服务的控制台界面,单击VPC下的子网,进入子网详情页面,查找IPv4子网ID。

  • 方法2:通过虚拟私有云服务的查询子网列表接口查询。

表9 hostNetwork

参数

是否必选

参数类型

描述

SecurityGroup

String

集群默认Node节点安全组需要放通部分端口来保证正常通信, 修改后的安全组只作用于新创建的节点和新纳管的节点,存量节点的安全组需手动修改。

表10 ClusterMetadataForUpdate

参数

是否必选

参数类型

描述

alias

String

集群显示名。

命名规则:以小写字母开头,由小写字母、数字、中划线(-)组成,长度范围4-128位,且不能以中划线(-)结尾。

显示名和其他集群的名称、显示名不可以重复。

为空时表示不进行修改。

响应参数

状态码: 200

表11 响应Body参数

参数

参数类型

描述

kind

String

API类型,固定值“Cluster”或“cluster”,该值不可修改。

apiVersion

String

API版本,固定值“v3”,该值不可修改。

metadata

ClusterMetadata object

集群的基本信息,为集合类的元素类型,包含一组由不同名称定义的属性。

spec

ClusterSpec object

spec是集合类的元素类型,您对需要管理的集群对象进行详细描述的主体部分都在spec中给出。CCE通过spec的描述来创建或更新对象。

status

ClusterStatus object

集合类的元素类型,用于记录对象在系统中的当前状态信息,包含了集群状态和本次创建集群作业的jobID

表12 ClusterMetadata

参数

参数类型

描述

name

String

集群名称。

命名规则:以小写字母开头,由小写字母、数字、中划线(-)组成,长度范围4-128位,且不能以中划线(-)结尾。

uid

String

集群ID,资源唯一标识,创建成功后自动生成,填写无效

alias

String

集群显示名,用于在 CCE 界面显示,该名称创建后可修改。

命名规则:以小写字母开头,由小写字母、数字、中划线(-)组成,长度范围4-128位,且不能以中划线(-)结尾。

显示名和其他集群的名称、显示名不可以重复。

在创建集群、更新集群请求体中,集群显示名alias未指定或取值为空,表示与集群名称name一致。在查询集群等响应体中,集群显示名alias将必然返回,未配置时将返回集群名称name。

annotations

Map<String,String>

集群注解,由key/value组成:

"annotations": {
   "key1" : "value1",
   "key2" : "value2"
}
说明:
  • Annotations不用于标识和选择对象。Annotations中的元数据可以是small或large,structured或unstructured,并且可以包括标签不允许使用的字符。

  • 该字段不会被数据库保存,当前仅用于指定集群待安装插件。

  • 可通过加入"cluster.install.addons.external/install":"[{"addonTemplateName":"icagent"}]"的键值对在创建集群时安装ICAgent。

labels

Map<String,String>

集群标签,key/value对格式。

说明:

该字段值由系统自动生成,用于升级时前端识别集群支持的特性开关,用户指定无效。

creationTimestamp

String

集群创建时间

updateTimestamp

String

集群更新时间

表13 ClusterSpec

参数

参数类型

描述

category

String

集群类别:

  • CCE:CCE集群 CCE集群支持虚拟机与裸金属服务器混合、GPU、NPU等异构节点的混合部署,基于高性能网络模型提供全方位、多场景、安全稳定的容器运行环境。

type

String

集群Master节点架构:

  • VirtualMachine:Master节点为x86架构服务器

flavor

String

字段默认值:创建CCE集群时,如果是非专属云为cce.s1.small,专属云则为cce.dec.s1.small;

集群规格,集群创建完成后规格不可再变更,请按实际业务需求进行选择:

  • cce.s1.small: 小规模单控制节点CCE集群(最大50节点)

  • cce.s1.medium: 中等规模单控制节点CCE集群(最大200节点)

  • cce.s2.small: 小规模多控制节点CCE集群(最大50节点)

  • cce.s2.medium: 中等规模多控制节点CCE集群(最大200节点)

  • cce.s2.large: 大规模多控制节点CCE集群(最大1000节点)

  • cce.s2.xlarge: 超大规模多控制节点CCE集群(最大2000节点)

说明:
  • s1:单控制节点CCE集群。

  • s2:多控制节点CCE集群。

  • dec:专属CCE集群规格。如cce.dec.s1.small为小规模单控制节点专属CCE集群(最大50节点)。

  • 最大节点数:当前集群支持管理的最大节点规模,请根据业务需求选择。

  • 单控制节点集群:普通集群是单控制节点,控制节点故障后,集群将不可用,但已运行工作负载不受影响。

  • 多控制节点集群:即高可用集群,当某个控制节点故障时,集群仍然可用。

version

String

集群版本,与Kubernetes社区基线版本保持一致,建议选择最新版本。

在CCE控制台支持创建两种最新版本的集群。可登录CCE控制台创建集群,在“版本”处获取到集群版本。 其它集群版本,当前仍可通过api创建,但后续会逐渐下线,具体下线策略请关注CCE官方公告。

说明:
  • 若不配置,默认创建最新版本的集群。

  • 若指定集群基线版本但是不指定具体r版本,则系统默认选择对应集群版本的最新r版本。建议不指定具体r版本由系统选择最新版本。

platformVersion

String

CCE集群平台版本号,表示集群版本(version)下的内部版本。用于跟踪某一集群版本内的迭代,集群版本内唯一,跨集群版本重新计数。不支持用户指定,集群创建时自动选择对应集群版本的最新平台版本。

platformVersion格式为:cce.X.Y

  • X: 表示内部特性版本。集群版本中特性或者补丁修复,或者OS支持等变更场景。其值从1开始单调递增。

  • Y: 表示内部特性版本的补丁版本。仅用于特性版本上线后的软件包更新,不涉及其他修改。其值从0开始单调递增。

description

String

集群描述,对于集群使用目的的描述,可根据实际情况自定义,默认为空。集群创建成功后可通过接口更新指定的集群来做出修改,也可在CCE控制台中对应集群的“集群详情”下的“描述”处进行修改。仅支持utf-8编码。

customSan

Array of strings

集群的API Server服务端证书中的自定义SAN(Subject Alternative Name)字段,遵从SSL标准X509定义的格式规范。

  1. 不允许出现同名重复。

  2. 格式符合IP和域名格式。

示例:

SAN 1: DNS Name=example.com
SAN 2: DNS Name=www.example.com
SAN 3: DNS Name=example.net
SAN 4: IP Address=93.184.216.34

ipv6enable

Boolean

集群是否使用IPv6模式,1.15版本及以上支持。

hostNetwork

HostNetwork object

节点网络参数,包含了虚拟私有云VPC和子网的ID信息,而VPC是集群内节点之间的通信依赖,所以是必选的参数集。

containerNetwork

ContainerNetwork object

容器网络参数,包含了容器网络类型和容器网段的信息。

authentication

Authentication object

集群认证方式相关配置。

billingMode

Integer

集群的计费方式。

  • 0: 按需计费

默认为“按需计费”。

masters

Array of MasterSpec objects

控制节点的高级配置

kubernetesSvcIpRange

String

服务网段参数,kubernetes clusterIP取值范围,1.11.7版本及以上支持。

clusterTags

Array of ResourceTag objects

集群资源标签

kubeProxyMode

String

服务转发模式,支持以下两种实现:

  • iptables:社区传统的kube-proxy模式,完全以iptables规则的方式来实现service负载均衡。该方式最主要的问题是在服务多的时候产生太多的iptables规则,非增量式更新会引入一定的时延,大规模情况下有明显的性能问题。

  • ipvs:主导开发并在社区获得广泛支持的kube-proxy模式,采用增量式更新,吞吐更高,速度更快,并可以保证service更新期间连接保持不断开,适用于大规模场景。

az

String

可用区(仅查询返回字段)。

extendParam

ClusterExtendParam object

集群扩展字段,可配置多可用区集群、专属CCE集群,以及将集群创建在特定的企业项目下等。

supportIstio

Boolean

支持Istio

configurationsOverride

Array of PackageConfiguration objects

覆盖集群默认组件配置

若指定了不支持的组件或组件不支持的参数,该配置项将被忽略。

当前支持的可配置组件及其参数详见

表14 HostNetwork

参数

参数类型

描述

vpc

String

用于创建控制节点的VPC的ID。

获取方法如下:

  • 方法1:登录虚拟私有云服务的控制台界面,在虚拟私有云的详情页面查找VPC ID。

  • 方法2:通过虚拟私有云服务的API接口查询。

说明:

当前vpc-router容器网络模型不支持对接含拓展网段的VPC。

subnet

String

用于创建控制节点的subnet的网络ID。获取方法如下:

  • 方法1:登录虚拟私有云服务的控制台界面,单击VPC下的子网,进入子网详情页面,查找网络ID。

  • 方法2:通过虚拟私有云服务的查询子网列表接口查询。

SecurityGroup

String

集群默认的Node节点安全组ID,不指定该字段系统将自动为用户创建默认Node节点安全组,指定该字段时集群将绑定指定的安全组。Node节点安全组需要放通部分端口来保证正常通信。

表15 ContainerNetwork

参数

参数类型

描述

mode

String

容器网络类型(只可选择其一)

  • overlay_l2:容器隧道网络,通过OVS(OpenVSwitch)为容器构建的overlay_l2网络。

  • vpc-router:VPC网络,使用ipvlan和自定义VPC路由为容器构建的Underlay的l2网络。

cidr

String

容器网络网段,建议使用网段10.0.0.0/12~19,172.16.0.0/16~19,192.168.0.0/16~19,如存在网段冲突,将会报错。

此参数在集群创建后不可更改,请谨慎选择。(已废弃,如填写cidrs将忽略该cidr)

cidrs

Array of ContainerCIDR objects

容器网络网段列表。1.21及新版本集群使用cidrs字段,当集群网络类型为vpc-router类型时,支持多个容器网段;1.21之前版本若使用cidrs字段,则取值cidrs数组中的第一个cidr元素作为容器网络网段地址。

此参数在集群创建后不可更改,请谨慎选择。

表16 ContainerCIDR

参数

参数类型

描述

cidr

String

容器网络网段,建议使用网段10.0.0.0/12~19,172.16.0.0/16~19,192.168.0.0/16~19。

表17 EniNetwork

参数

参数类型

描述

eniSubnetId

String

ENI所在子网的IPv4子网ID(暂不支持IPv6,废弃中)。获取方法如下:

  • 方法1:登录虚拟私有云服务的控制台界面,单击VPC下的子网,进入子网详情页面,查找IPv4子网ID。

  • 方法2:通过虚拟私有云服务的查询子网列表接口查询。

eniSubnetCIDR

String

ENI子网CIDR(废弃中)

subnets

Array of NetworkSubnet objects

IPv4子网ID列表

表18 NetworkSubnet

参数

参数类型

描述

subnetID

String

用于创建控制节点的subnet的IPv4子网ID(暂不支持IPv6)。获取方法如下:

  • 方法1:登录虚拟私有云服务的控制台界面,单击VPC下的子网,进入子网详情页面,查找IPv4子网ID。

  • 方法2:通过虚拟私有云服务的查询子网列表接口查询。

表19 Authentication

参数

参数类型

描述

mode

String

集群认证模式。

  • kubernetes 1.11及之前版本的集群支持“x509”、“rbac”和“authenticating_proxy”,默认取值为“x509”。

  • kubernetes 1.13及以上版本的集群支持“rbac”和“authenticating_proxy”,默认取值为“rbac”。

authenticatingProxy

AuthenticatingProxy object

authenticatingProxy模式相关配置。认证模式为authenticating_proxy时必选。

表20 AuthenticatingProxy

参数

参数类型

描述

ca

String

authenticating_proxy模式配置的x509格式CA证书(base64编码)。当集群认证模式为authenticating_proxy时,此项必须填写。

最大长度:1M

cert

String

authenticating_proxy模式配置的x509格式CA证书签发的客户端证书,用于kube-apiserver到扩展apiserver的认证。(base64编码)。当集群认证模式为authenticating_proxy时,此项必须填写。

privateKey

String

authenticating_proxy模式配置的x509格式CA证书签发的客户端证书时对应的私钥,用于kube-apiserver到扩展apiserver的认证。Kubernetes集群使用的私钥尚不支持密码加密,请使用未加密的私钥。(base64编码)。当集群认证模式为authenticating_proxy时,此项必须填写。

表21 MasterSpec

参数

参数类型

描述

availabilityZone

String

可用区

表22 ResourceTag

参数

参数类型

描述

key

String

Key值。

  • 不能为空,最多支持128个字符

  • 可用UTF-8格式表示的汉字、字母、数字和空格

  • 支持部分特殊字符:_.:/=+-@

  • 不能以"_sys_"开头

value

String

Value值。

  • 可以为空但不能缺省,最多支持255个字符

  • 可用UTF-8格式表示的汉字、字母、数字和空格

  • 支持部分特殊字符:_.:/=+-@

表23 ClusterExtendParam

参数

参数类型

描述

clusterAZ

String

集群控制节点可用区配置。

  • multi_az:多可用区,可选。仅使用高可用集群时才可以配置多可用区。

  • 专属云计算池可用区:用于指定专属云可用区部署集群控制节点。如果需配置专属CCE集群,该字段为必选。

dssMasterVolumes

String

用于指定控制节点的系统盘和数据盘使用专属分布式存储,未指定或者值为空时,默认使用EVS云硬盘。

如果配置专属CCE集群,该字段为必选,请按照如下格式设置:

<rootVol.dssPoolID>.<rootVol.volType>;<dataVol.dssPoolID>.<dataVol.volType>

字段说明:

  • rootVol为系统盘;dataVol为数据盘;

  • dssPoolID为专属分布式存储池ID;

  • volType为专属分布式存储池的存储类型,如SAS、SSD。

样例:c950ee97-587c-4f24-8a74-3367e3da570f.sas;6edbc2f4-1507-44f8-ac0d-eed1d2608d38.ssd

说明:

非专属CCE集群不支持配置该字段。

enterpriseProjectId

String

集群所属的企业项目ID。

说明:
  • 需要开通企业项目功能后才可配置企业项目。

  • 集群所属的企业项目与集群下所关联的其他云服务资源所属的企业项目必须保持一致。

kubeProxyMode

String

服务转发模式,支持以下两种实现:

  • iptables:社区传统的kube-proxy模式,完全以iptables规则的方式来实现service负载均衡。该方式最主要的问题是在服务多的时候产生太多的iptables规则,非增量式更新会引入一定的时延,大规模情况下有明显的性能问题

  • ipvs:主导开发并在社区获得广泛支持的kube-proxy模式,采用增量式更新,吞吐更高,速度更快,并可以保证service更新期间连接保持不断开,适用于大规模场景。

说明:

此参数已废弃,若同时指定此参数和ClusterSpec下的kubeProxyMode,以ClusterSpec下的为准。

clusterExternalIP

String

master 弹性公网IP

alpha.cce/fixPoolMask

String

容器网络固定IP池掩码位数,仅vpc-router网络支持。

该参数决定节点可分配容器IP数量,与创建节点时设置的maxPods参数共同决定节点最多可以创建多少个Pod, 具体请参见节点最多可以创建多少Pod

整数字符传取值范围: 24 ~ 28

decMasterFlavor

String

专属CCE集群指定可控制节点的规格。

dockerUmaskMode

String

集群默认Docker的UmaskMode配置,可取值为secure或normal,不指定时默认为normal。

kubernetes.io/cpuManagerPolicy

String

集群CPU管理策略。取值为none(或空值)或static,默认为none(或空值)。

  • none(或空值):关闭工作负载实例独占CPU核的功能,优点是CPU共享池的可分配核数较多

  • static:支持给节点上的工作负载实例配置CPU独占,适用于对CPU缓存和调度延迟敏感的工作负载。

upgradefrom

String

记录集群通过何种升级方式升级到当前版本。

表24 PackageConfiguration

参数

参数类型

描述

name

String

组件名称

configurations

Array of ConfigurationItem objects

组件配置项

表25 ConfigurationItem

参数

参数类型

描述

name

String

组件配置项名称

value

Object

组件配置项值

表26 ClusterStatus

参数

参数类型

描述

phase

String

集群状态,取值如下

  • Available:可用,表示集群处于正常状态。

  • Unavailable:不可用,表示集群异常,需手动删除。

  • ScalingUp:扩容中,表示集群正处于扩容过程中。

  • ScalingDown:缩容中,表示集群正处于缩容过程中。

  • Creating:创建中,表示集群正处于创建过程中。

  • Deleting:删除中,表示集群正处于删除过程中。

  • Upgrading:升级中,表示集群正处于升级过程中。

  • Resizing:规格变更中,表示集群正处于变更规格中。

  • RollingBack:回滚中,表示集群正处于回滚过程中。

  • RollbackFailed:回滚异常,表示集群回滚异常。

  • Hibernating:休眠中,表示集群正处于休眠过程中。

  • Hibernation:已休眠,表示集群正处于休眠状态。

  • Awaking:唤醒中,表示集群正处于从休眠状态唤醒的过程中。

  • Empty:集群无任何资源(已废弃)

jobID

String

任务ID,集群当前状态关联的任务ID。当前支持:

  • 创建集群时返回关联的任务ID,可通过任务ID查询创建集群的附属任务信息;

  • 删除集群或者删除集群失败时返回关联的任务ID,此字段非空时,可通过任务ID查询删除集群的附属任务信息。

说明:

任务信息具有一定时效性,仅用于短期跟踪任务进度,请勿用于集群状态判断等额外场景。

reason

String

集群变为当前状态的原因,在集群在非“Available”状态下时,会返回此参数。

message

String

集群变为当前状态的原因的详细信息,在集群在非“Available”状态下时,会返回此参数。

endpoints

Array of ClusterEndpoints objects

集群中 kube-apiserver 的访问地址。

deleteOption

Object

删除配置状态(仅删除请求响应包含)

deleteStatus

Object

删除状态信息(仅删除请求响应包含)

表27 ClusterEndpoints

参数

参数类型

描述

url

String

集群中 kube-apiserver 的访问地址

type

String

集群访问地址的类型

  • Internal:用户子网内访问的地址

  • External:公网访问的地址

请求示例

  • 仅更新集群描述

    {
      "spec" : {
        "description" : "new description"
      }
    }
  • 仅更新集群自定义证书SAN

    {
      "spec" : {
        "customSan" : [ "192.168.1.0", "example.com" ]
      }
    }
  • 同时更新集群描述和自定义证书SAN

    {
      "spec" : {
        "description" : "new description",
        "customSan" : [ "192.168.1.0", "example.com" ]
      }
    }
  • 1.21版本以上vpc-router网络类型集群添加容器网段

    {
      "spec" : {
        "containerNetwork" : {
          "cidrs" : [ {
            "cidr" : "10.10.0.0/16"
          }, {
            "cidr" : "10.11.0.0/16"
          } ]
        }
      }
    }
  • 修改集群默认Node节点安全组

    /api/v3/projects/{project_id}/clusters/{cluster_id}
    
    {
      "spec" : {
        "hostNetwork" : {
          "SecurityGroup" : "6ee29825-8f49-4796-b33a-fc76f84a59ae"
        }
      }
    }

响应示例

状态码: 200

表示更新指定集群成功。

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "metadata" : {
    "alias" : "mycluster",
    "name" : "mycluster",
    "uid" : "4d1ecb2c-229a-11e8-9c75-0255ac100ceb",
    "creationTimestamp" : "2018-08-02 03:48:58.968214406 +0000 UTC",
    "updateTimestamp" : "2018-08-02 06:39:36.844676088 +0000 UTC"
  },
  "spec" : {
    "type" : "VirtualMachine",
    "flavor" : "cce.s1.small",
    "version" : "v1.7.3-r13",
    "description" : "new description",
    "customSan" : [ "192.168.1.0", "example.com" ],
    "hostNetwork" : {
      "vpc" : "4d1ecb2c-229a-11e8-9c75-0255ac100ceb",
      "subnet" : "4d1ecb2c-229a-11e8-9c75-0255ac100ceb",
      "SecurityGroup" : "6ee29825-8f49-4796-b33a-fc76f84a59ae"
    },
    "containerNetwork" : {
      "mode" : "overlay_l2",
      "cidr" : "172.17.0.0/16"
    },
    "authentication" : {
      "mode" : "x509",
      "authenticatingProxy" : { }
    },
    "billingMode" : 0
  },
  "status" : {
    "phase" : "Available",
    "endpoints" : [ {
      "url" : "https://192.168.0.11:5443",
      "type" : "Internal"
    } ]
  }
}

状态码

状态码

描述

200

表示更新指定集群成功。

错误码

请参见错误码