错误码
5.2.4 更新指定的集群
功能介绍
该API用于更新指定的集群。
说明
集群管理的URL格式为：https://Endpoint/uri。其中uri为资源路径，也即API访问的路径。
调试
您可以在API Explorer中调试该接口。
URI
PUT /api/v3/projects/{project_id}/clusters/{cluster_id}
表5-71 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 项目ID，获取方式请参见如何获 取接口URI中参数
cluster_id 是 String 集群 ID，获取方式请参见如何 获取接口URI中参数
正则匹配：^[0-9a-z]{8}-[0-9a- z]{4}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{12}$
请求参数
表5-72 请求 Header 参数
参数 是否必选 参数类型 描述
Content-Type 是 String 消息体的类型（格式）
缺省值：application/json
API 参考 5 API
参数 是否必选 参数类型 描述
X-Auth-Token 是 String "调用接口的认证方式分为 Token和AK/SK两种，如果您使 用的Token方式，此参数为必 填，请填写Token的值，获取方 式请参见获取token。"
最大长度：16384
表5-73 请求 Body 参数
参数 是否必选 参数类型 描述
spec 是 ClusterInfor
mationSpec object
具体集群参数
表5-74 ClusterInformationSpec
参数 是否必选 参数类型 描述
description 否 String 集群的描述信息。
1. 字符取值范围[0,200]。不包 含~$%^&*<>[]{}()'"#\等特 殊字符。
2. 仅运行和扩容状态
（Available、ScalingUp、
ScalingDown）的集群允许 修改。
最大长度：200
正则匹配：[^\~\$\%\^\&\*\<\>
\[\]\{\}\(\)\'\"\#\\]
customSan 否 Array of
strings 集群的API Server服务端证书中 的自定义SAN（Subject
Alternative Name）字段，遵从 SSL标准X509定义的格式规范。
1. 不允许出现同名重复。
2. 格式符合IP和域名格式。
example: SAN 1: DNS Name=example.com SAN 2:
DNSName=www.example.com SAN 3: DNS
Name=example.net SAN 4: IP Address=93.184.216.34
API 参考 5 API
参数 是否必选 参数类型 描述 containerNet
work 否 ContainerNet
workUpdate object
容器网络参数，包含容器网段的 信息。
表5-75 ContainerNetworkUpdate
参数 是否必选 参数类型 描述
cidrs 否 Array of
ContainerCID R objects
容器网络网段列表。1.21及新版
表5-76 ContainerCIDR
参数 是否必选 参数类型 描述
kind String API类型，固定值“Cluster”或“cluster”，该 值不可修改。
缺省值：Cluster
apiVersion String API版本，固定值“v3”，该值不可修改。
缺省值：v3 metadata ClusterMetad
ata object 集群的基本信息，为集合类的元素类型，包含一
组由不同名称定义的属性。
spec ClusterSpec
object spec是集合类的元素类型，您对需要管理的集群 对象进行详细描述的主体部分都在spec中给出。
CCE通过spec的描述来创建或更新对象。
API 参考 5 API
参数 参数类型 描述 status ClusterStatus
object 集合类的元素类型，用于记录对象在系统中的当 前状态信息，包含了集群状态和本次创建集群作 业的jobID
表5-78 ClusterMetadata
参数 参数类型 描述
name String 集群名称。
命名规则：以小写字母开头，由小写字母、数 字、中划线(-)组成，长度范围4-128位，且不能 以中划线(-)结尾。
最小长度：4 最大长度：128
uid String 资源唯一标识，创建成功后自动生成，填写无效 正则匹配：^[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]
{4}-[0-9a-z]{4}-[0-9a-z]{12}$
annotations Map<String,St
ring> 集群注解，由key/value组成：
"annotations": { "key1" : "value1", "key2" : "value2"
} 说明
● Annotations不用于标识和选择对象。Annotations 中的元数据可以是small 或large，structured 或 unstructured，并且可以包括标签不允许使用的字 符。
● 该字段不会被数据库保存，当前仅用于指定集群待 安装插件。
labels Map<String,St
ring> 集群标签，key/value对格式。
说明
该字段值由系统自动生成，用于升级时前端识别集群支 持的特性开关，用户指定无效。
creationTimes
tamp String 集群创建时间
updateTimest
amp String 集群更新时间
API 参考 5 API
表5-79 ClusterSpec
参数 参数类型 描述
category String 集群类别：
● CCE：CCE集群
CCE集群支持虚拟机与裸金属服务器混合、
GPU、NPU等异构节点的混合部署，基于高性 能网络模型提供全方位、多场景、安全稳定的 容器运行环境。
● Turbo: CCE Turbo集群
全面基于云原生基础设施构建的云原生2.0的 容器引擎服务，具备软硬协同、网络无损、安 全可靠、调度智能的优势，为用户提供一站 式、高性价比的全新容器服务体验。
枚举值：
● CCE
● Turbo
type String 集群管控面节点架构：
● VirtualMachine：管控面节点为x86架构服务 器
● ARM64: 管控面节点为鲲鹏（ARM架构）服务 器
枚举值：
● VirtualMachine
● ARM64
API 参考 5 API
参数 参数类型 描述
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社区基线版本保持一 致，建议选择最新版本。
参数 参数类型 描述 platformVersi
on String CCE集群平台版本号，仅供查看，不支持创建指 定，集群创建时自动选择对应集群版本的最新平 台版本。
description String 集群描述，对于集群使用目的的描述，可根据实 际情况自定义，默认为空。集群创建成功后可通
customSan Array of
strings 集群的API Server服务端证书中的自定义SAN
（Subject Alternative Name）字段，遵从SSL标 准X509定义的格式规范。
1. 不允许出现同名重复。
2. 格式符合IP和域名格式。
example: 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是集群内节点之间的通信依赖，
所以是必选的参数集。
containerNet
work ContainerNet
work object 容器网络参数，包含了容器网络类型和容器网段
的信息。
eniNetwork EniNetwork
object 云原生网络2.0网络配置，创建CCE Turbo集群
（公测中）时指定。
authenticatio
n Authenticati
on object 集群认证方式相关配置。
billingMode Integer 集群的计费方式。计费方式为“按需计费”时，
取值为“0”；计费方式为“包周期”时，取值为
“1”。若不填，则默认为“按需计费”。
缺省值：0 masters Array of
MasterSpec objects
控制节点的高级配置
kubernetesSvc
IpRange String 服务网段参数，kubernetes clusterIp取值范围，
1.11.7版本及以上支持。
API 参考 5 API
参数 参数类型 描述 clusterTags Array of
ResourceTag objects
集群资源标签
kubeProxyMo
de String 服务转发模式，支持以下两种实现：
● iptables：社区传统的kube-proxy模式，完全 以iptables规则的方式来实现service负载均 衡。该方式最主要的问题是在服务多的时候产 生太多的iptables规则，非增量式更新会引入 一定的时延，大规模情况下有明显的性能问 题。
● ipvs：主导开发并在社区获得广泛支持的 kube-proxy模式，采用增量式更新，吞吐更 高，速度更快，并可以保证service更新期间连 接保持不断开，适用于大规模场景。
枚举值：
● iptables
● ipvs
az String 可用区（仅查询返回字段）, CCE支持的可用区请 参考地区和终端节点获取。
extendParam ClusterExten dParam object
集群扩展字段，可配置多可用区集群、专属CCE 集群，以及将集群创建在特定的企业项目下等。
supportIstio Boolean 支持Istio
API 参考 5 API
表5-80 HostNetwork
参数 参数类型 描述
vpc String 用于创建控制节点的VPC的ID。该值在创建VPC 和子网中获取。
获取方法如下：
● 方法1：登录虚拟私有云服务的控制台界面，
在虚拟私有云的详情页面查找VPC ID。
● 方法2：通过虚拟私有云服务的API接口查询，
具体操作可参考查询VPC列表 说明
● 当前vpc-router容器网络模型不支持对接含拓展网段 的VPC。
● 若您的用户类型为企业用户，则需要保证vpc所属的 企业项目ID和集群创建时选择的企业项目ID一致。
集群所属的企业项目ID通过extendParam字段下的 enterpriseProjectId体现，该值默认为"0"，表示默 认的企业项目。
最小长度：0 最大长度：64
subnet String 用于创建控制节点的subnet的网络ID。获取方法 如下：
● 方法1：登录虚拟私有云服务的控制台界面，
单击VPC下的子网，进入子网详情页面，查找 网络ID。
方法2：通过虚拟私有云服务的API接口查询，具 体操作可参考查询子网列表
最小长度：0 最大长度：64
SecurityGroup String 节点安全组ID，创建时指定无效
API 参考 5 API
表5-81 ContainerNetwork
参数 参数类型 描述
mode String 容器网络类型（只可选择其一）
● overlay_l2：通过OVS（OpenVSwitch）为容 器构建的overlay_l2网络。
● vpc-router：使用ipvlan和自定义VPC路由为容 器构建的Underlay的l2网络。
● eni：云原生网络2.0，深度整合VPC原生ENI弹 性网卡能力，采用VPC网段分配容器地址，支 持ELB直通容器，享有高性能，创建CCE Turbo集群（公测中）时指定。
说明
● 容器隧道网络（Overlay）：基于VXLAN技术实现的 Overlay容器网络。VXLAN是将以太网报文封装成
● VPC网络：基于VPC网络的自定义路由，直接将容器 网络承载于VPC网络之中。每个节点将会被分配固
● overlay_l2
● vpc-router
● eni
cidr String 容器网络网段，建议使用网段10.0.0.0/12~19，
172.16.0.0/16~19，192.168.0.0/16~19，如存在 cidrs Array of
ContainerCID R objects
容器网络网段列表。1.21及新版本集群使用cidrs
表5-82 ContainerCIDR
参数 参数类型 描述
cidr String 容器网络网段，建议使用网段10.0.0.0/12~19，
172.16.0.0/16~19，192.168.0.0/16~19。
表5-83 EniNetwork
参数 参数类型 描述
eniSubnetId String 用于创建控制节点的subnet的IPv4网络ID(暂不支 持IPv6,废弃中)。获取方法如下：- 方法1：登录 虚拟私有云服务的控制台界面，单击VPC下的子 网，进入子网详情页面，查找IPv4子网ID。- 方法 2：通过虚拟私有云服务的API接口查询，具体操 作可参考查询子网列表
正则匹配：^[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]
{4}-[0-9a-z]{4}-[0-9a-z]{12}$
eniSubnetCID
R String ENI子网CIDR(废弃中) subnets Array of
NetworkSub net objects
IPv4子网ID列表
表5-84 NetworkSubnet
参数 参数类型 描述
subnetID String 用于创建控制节点的subnet的IPv4网络ID(暂不支 持IPv6)。获取方法如下：- 方法1：登录虚拟私有 云服务的控制台界面，单击VPC下的子网，进入 子网详情页面，查找IPv4子网ID。- 方法2：通过 虚拟私有云服务的API接口查询，具体操作可参考 查询子网列表
正则匹配：^[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]
{4}-[0-9a-z]{4}-[0-9a-z]{12}$
API 参考 5 API
表5-85 Authentication
参数 参数类型 描述
mode String 集群认证模式。
● kubernetes 1.11及之前版本的集群支持
“x509”、“rbac”和
“authenticating_proxy”，默认取值为
“x509”。
● kubernetes 1.13及以上版本的集群支持
“rbac”和“authenticating_proxy”，默认 取值为“rbac”。
authenticatin
gProxy Authenticati ngProxy object
authenticatingProxy模式相关配置。认证模式为 authenticating_proxy时必选。
表5-86 AuthenticatingProxy
参数 参数类型 描述
ca String authenticating_proxy模式配置的x509格式CA证 书(base64编码)。当集群认证模式为
authenticating_proxy时，此项必须填写。
最大长度：1M
cert String authenticating_proxy模式配置的x509格式CA证
cert String authenticating_proxy模式配置的x509格式CA证