调用ModifyCluster接口修改ACK集群配置-容器服务 Kubernetes 版 ACK-阿里云-容器服务 Kubernetes 版 ACK(ACK)-阿里云帮助中心

您可以调用ModifyCluster接口修改ACK集群的配置。

接口说明

重要自 2026 年 07 月 04 日起，请求入参 instance_deletion_protection、ingress_loadbalancer_id、access_control_list 不再生效。变更详情请参见关于 ACK 集群管理相关的 OpenAPI 出入参变化及 OpenAPI 下线的公告。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

cs:ModifyCluster

update

*Cluster

acs:cs:{#regionId}:{#accountId}:cluster/{#ClusterId}

cs:EnableApiServerEip
cs:ApiServerEipId

无

请求语法

PUT /api/v2/clusters/{ClusterId} HTTP/1.1

路径参数

名称	类型	必填	描述	示例值
ClusterId	string	是	集群 ID。	cb95aa626a47740afbf6aa099b65****

请求参数

名称	类型	必填	描述	示例值
body	object	否	请求体参数。	true
api_server_eip	boolean	否	集群是否绑定 EIP，用于公网访问 API Server。取值： `true`：集群绑定 EIP。 `false`：集群不绑定 EIP。	true
api_server_eip_id	string	否	集群 API Server 绑定的 EIP 实例 ID，仅当`api_server_eip`取值为`true`时生效。	eip-wz9fnasl6dsfhmvci****
deletion_protection	boolean	否	集群删除保护，防止通过控制台或 API 误删除集群。取值： `true`：启用集群删除保护，将不能通过控制台或 API 删除集群。 `false`：不启用集群删除保护，则能通过控制台或 API 删除集群。默认值：`false`。	false
resource_group_id	string	否	集群资源组 ID。	rg-acfmyvw3wjm****
maintenance_window	maintenance_window	否	集群维护窗口，该功能只在 ACK 托管集群 Pro 版中生效。
enable_rrsa	boolean	否	启用或禁用 RRSA 功能（只有托管版集群支持配置该参数）。取值： `true`：启用。 `false`：禁用。	true
cluster_name	string	否	自定义集群名称。由数字、汉字、英文字符或短划线（-）组成，长度范围 1~63 个字符，且不能以短划线（-）开头。	cluster-new-name
cluster_spec	string	否	集群规格。取值： ack.pro.small ack.pro.xlarge ack.pro.2xlarge ack.pro.4xlarge	ack.pro.small
system_events_logging	object	否	系统事件存储配置。
enabled	boolean	否	是否开启系统事件存储。 true：开启系统事件存储。 false：不开启系统事件存储。	true
logging_project	string	否	系统事件存储的 LogProject 名称。	k8s-log-cb95aa626a47740afbf6aa099b65****
operation_policy	object	否	集群自动运维策略。
cluster_auto_upgrade	object	否	集群自动升级。
enabled	boolean	否	是否开启集群自动升级。 true：开启自动升级。 false：不开启自动升级。	true
channel	string	否	集群自动升级频次。更多信息，请参见升级频次。可取值： patch：最新补丁版本。 stable：次新次要版本。 rapid：最新次要版本。	patch
api_server_custom_cert_sans	object	否	自定义 API Server 证书 SAN（Subject Alternative Name）。用于在集群 API Server 服务端证书的 SAN 字段中添加自定义的 IP 或域名，以实现对客户端的访问控制。仅托管版集群支持配置该参数。
action	string	否	覆盖或追加 SAN 配置。取值： overwrite: 覆盖。 append: 追加。	append
subject_alternative_names	array	否	SAN 列表。
	string	否	SAN。支持自定义 IP 地址或域名，多个 IP 地址或域名以英文逗号（,）隔开。	aliyun.xxx.com,192.168.xx.xx
vswitch_ids	array	否	集群控制面虚拟交换机。专有集群变更后，将作用于新扩容的控制面节点。托管类集群变更控制面虚拟交换机，请注意以下事项：该参数为覆盖更新，需完全指定目标交换机列表。变更过程控制面组件会短暂重启，请谨慎操作。请确保集群所有安全组（包括控制面安全组、所有节点池的安全组、容器网络使用的安全组）的出入方向已放行新的虚拟交换机的 IP 网段，避免节点与容器无法连接 API server。如新的控制面交换机配置了 ACL 规则，请确保该 ACL 规则已经放行其与集群节点、容器网络等 IP 网段的通信。
	string	否	集群控制面虚拟交换机。	vsw-2ze4jvvvade1yk899****
control_plane_config	object	否	专有版集群控制面配置。
charge_type	string	否	控制面节点实例付费类型，取值： `PrePaid`：包年包月。 `PostPaid`：按量付费。默认值：`PostPaid`。	PostPaid
period	integer	否	控制面节点实例包年包月时长，当`charge_type`取值为`PrePaid`时才生效且为必选值。当`period_unit=Month`时，取值范围：{1, 2 , 3, 6, 12, 24, 36, 48, 60}。	1
period_unit	string	否	控制面节点实例付费周期，当`charge_type`取值为`PrePaid`时才生效。 `Month`：以月为计时单位，当前只支持以月为单位。	Month
auto_renew	boolean	否	控制面节点实例是否开启自动续费，当`charge_type`取值为`PrePaid`时才生效。取值： `true`：自动续费。 `false`：不自动续费。默认值：`false`。	false
auto_renew_period	integer	否	控制面节点实例单次自动续费的续费时长。取值范围：{1, 2, 3, 6, 12}，单位：月。默认值：1。	1
instance_types	array	否	实例规格。更多信息，请参见实例规格族。
	string	否	实例规格。	ecs.g6.large
image_type	string	否	操作系统镜像类型，取值范围： `AliyunLinux3`：Alinux3 镜像。 `Custom`：自定义镜像。	AliyunLinux3
image_id	string	否	自定义镜像 ID。自定义镜像时指定。	aliyun_3_x64_20G_alibase_20240819.vhd
key_pair	string	否	密钥对名称，和`login_password`二选一。	ack
login_password	string	否	SSH 登录密码，和`key_pair` 二选一。密码规则为 8~30 个字符，且至少同时包含三项（大小写字母、数字和特殊符号）。如需要使用密码登录，需在扩容时指定。	Ack@2000.
system_disk_category	string	否	节点系统盘类型，取值： `cloud_efficiency`：高效云盘。 `cloud_ssd`：SSD 云盘。 `cloud_essd`：ESSD 云盘。 `cloud_auto`：ESSD AutoPL 云盘。 `cloud_essd_entry`：ESSD Entry 云盘。	cloud_essd
system_disk_size	integer	否	节点系统盘大小，取值范围[40,500]，单位：GiB。	120
system_disk_snapshot_policy_id	string	否	节点系统盘采用的自动快照策略 ID。	sp-2zej1nogjvovnz4z****
system_disk_performance_level	string	否	节点系统盘磁盘性能等级，仅对 ESSD 磁盘生效。磁盘性能等级和磁盘大小有关。更多信息，请参见 ESSD 云盘。	PL1
system_disk_provisioned_iops	integer	否	节点系统盘预配置的读写 IOPS。可能值：0~min{50,000, 1000容量-基准性能}。基准性能=min{1,800+50容量, 50000}。当`system_disk_category`取值为`cloud_auto`时才支持设置该参数。更多信息，请参见ESSD AutoPL 云盘。	1000
system_disk_bursting_enabled	boolean	否	节点系统盘是否开启 Burst（性能突发）。取值： `true`：是。 `false`：否。当`system_disk_category` 取值为`cloud_auto`时才支持设置该参数。更多信息，请参见ESSD AutoPL 云盘。	true
deploymentset_id	string	否	部署集 ID。	ds-bp10b35imuam5amw****
cloud_monitor_flags	boolean	否	控制面节点是否安装云监控插件。取值： `true`：安装云监控插件。 `false`：不安装云监控插件。	true
soc_enabled	boolean	否	等保加固。更多信息，请参见 ACK 等保加固使用说明。取值： `true`：开启等保加固。 `false`：不开启等保加固。默认值：`false`。	false
security_hardening_os	boolean	否	阿里云 OS 安全加固。取值： `true`：开启阿里云 OS 安全加固。 `false`：不开启阿里云 OS 安全加固。默认值：`false`。	false
cpu_policy	string	否	节点 CPU 管理策略。当集群版本在 1.12.6 及以上时支持以下两种策略： `static`：允许为节点上具有某些资源特征 Pod 增强其 CPU 亲和性和独占性。 `none`：表示启用现有的默认 CPU 亲和性方案。默认值：`none`。	none
runtime	string	否	容器运行时名称，取值范围： `containerd`：推荐使用，支持所有集群版本。默认值：containerd。	containerd
node_port_range	string	否	节点服务端口范围。可选端口范围：[30000,65535]。默认值：30000-32767。	30000-32767
size	integer	否	控制面节点数量。如需扩容专有版控制面，该参数为目标控制面节点数，需大于当前控制面节点数量。	5
security_group_id	string	否	控制面安全组 ID。如您在安全组中配置了拦截规则，请确保安全组规则放行集群依赖的协议和端口，关于建议的安全组规则范围，请参见配置并管理集群安全组。对于非 ACK 专有集群，变更过程中，集群控制面及已安装的托管组件（例如 terway-controlplane 等）将短暂重启，建议您在业务低峰期操作。变更控制面安全组后，集群控制面及已安装的托管组件使用的弹性网卡 ENI 将自动加入到新的安全组中。对于 ACK 专有集群，变更控制面安全组后，新扩容的 Master 节点会自动应用新的控制面安全组，现有控制面节点不受影响。	sg-bp1h6rk3pgct2a08***
timezone	string	否	集群时区。请参见支持时区。变更时区后，集群巡检配置将采用新的时区设置。对于托管类集群，变更过程中，集群控制面及已安装的托管组件（例如 terway-controlplane 等）将短暂重启，建议您在业务低峰期操作。变更时区后，新扩容的节点会自动应用新的时区设置，现有节点不受影响，您可以通过节点池节点重置功能使现有节点生效。对于专有集群，变更时区后，新扩容的节点（包括控制面节点）会自动应用新的时区设置，现有节点（包括控制面节点）不受影响，您可以通过节点池节点重置功能使现有节点生效。对于控制面节点，您需要通过扩容后再缩容的方式使全量控制面节点生效。	Asia/Shanghai
control_plane_endpoints_config	object	否	集群连接配置。
internal_dns_config	object	否	集群内部域名配置，适用于 ACK 托管集群。集群内部域名用于 kubelet、kube-proxy 等节点侧系统组件访问 API Server；未开启集群内部域名访问时，节点侧系统组件将通过 CLB IP 方式访问。
bind_vpcs	array	否	集群内部域名记录解析生效的 VPC。
	string	否	集群内部域名记录解析生效的 VPC。	vpc-xxxx
enabled	boolean	否	是否开启集群内部域名访问。取值： true：开启集群内部域名访问，节点侧组件（kubelet、kube-proxy）将通过集群内部域名访问 API Server。	true
access_control_list `deprecated`	array	否	注册集群 API Server SLB 访问控制列表。
	string	否	注册集群 API Server SLB 访问控制列表。注意：不允许填写 0.0.0.0/0 网段。	192.168.XX.XX/24
instance_deletion_protection `deprecated`	boolean	否	实例删除保护，防止通过控制台或 API 误删除释放节点。取值： `true`: 不能通过控制台或 API 误删除节点。 `false`：能通过控制台或 API 误删除节点。默认值：`false`。	false
ingress_domain_rebinding `deprecated`	boolean	否	重新绑定集群测试域名。取值： `true`：重新绑定集群测试域名。 `false`：不重新绑定集群测试域名。默认值：`false`。	false
ingress_loadbalancer_id `deprecated`	string	否	被修改集群的 SLB 实例 ID。	lb-wz97kes8tnndkpodw****

返回参数

名称	类型	描述	示例值
	object	返回数据体。
cluster_id	string	集群 ID。	cb95aa626a47740afbf6aa09****
request_id	string	请求 ID。	687C5BAA-D103-4993-884B-C35E4314****
task_id	string	任务 ID。	T-5a54309c80282e39ea00****

示例

正常返回示例

JSON格式

{
  "cluster_id": "cb95aa626a47740afbf6aa09****",
  "request_id": "687C5BAA-D103-4993-884B-C35E4314****",
  "task_id": "T-5a54309c80282e39ea00****"
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。