Call the ModifyCluster API to modify cluster configurations - Container Service for Kubernetes - Alibaba Cloud - Container Service for Kubernetes

Call ModifyCluster to change an ACK cluster's configuration.

Operation description

Important Effective July 4, 2026, the request parameters instance_deletion_protection, ingress_loadbalancer_id, and access_control_list will have no effect. For more information, see Announcement on OpenAPI Request and Response Parameter Changes and OpenAPI Deprecation for ACK Cluster Management.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

cs:ModifyCluster

update

*Cluster

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

cs:EnableApiServerEip
cs:ApiServerEipId

None

Request syntax

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

Path Parameters

Parameter	Type	Required	Description	Example
ClusterId	string	Yes	The cluster ID.	cb95aa626a47740afbf6aa099b65****

Request parameters

Parameter	Type	Required	Description	Example
body	object	No	The request body parameters.	true
api_server_eip	boolean	No	Specifies whether to associate an EIP with the cluster API Server to allow public access. Valid values: `true`: Associates an EIP with the cluster. `false`: Does not associate an EIP with the cluster.	true
api_server_eip_id	string	No	The ID of the EIP instance associated with the cluster API Server. This parameter applies only when `api_server_eip` is set to `true`.	eip-wz9fnasl6dsfhmvci****
deletion_protection	boolean	No	Specifies whether to enable deletion protection for the cluster. Valid values: `true`: Enables deletion protection. You cannot delete the cluster from the console or by calling an API operation. `false`: Disables deletion protection. You can delete the cluster from the console or by calling an API operation. Default value: `false`.	false
resource_group_id	string	No	The ID of the resource group to which the cluster belongs.	rg-acfmyvw3wjm****
maintenance_window	maintenance_window	No	The maintenance window of the cluster. This setting applies only to ACK Pro managed clusters.
enable_rrsa	boolean	No	Specifies whether to enable the RAM Roles for Service Accounts (RRSA) feature. This setting applies only to managed clusters. Valid values: `true`: Enables the RRSA feature. `false`: Disables the RRSA feature.	true
cluster_name	string	No	The name of the cluster. The name must be 1 to 63 characters long, can contain digits, letters, Chinese characters, and hyphens (-), and cannot start with a hyphen.	cluster-new-name
cluster_spec	string	No	The specification of the cluster. This parameter applies only when `cluster_type` is set to `ManagedKubernetes` and the `profile` parameter is configured. Valid values: `ack.pro.small`: Pro Edition `ack.pro.xlarge`: Pro XL `ack.pro.2xlarge`: Pro 2XL `ack.pro.4xlarge`: Pro 4XL (Contact customer support to be added to the allowlist.) Pro XL, Pro 2XL, and Pro 4XL are three specifications provided by the ACK Pro provisioned control plane. This feature pre-allocates and fixes control plane resources to ensure a consistently high level of API concurrency and pod scheduling capabilities, which is suitable for AI training and inference, large-scale clusters, and mission-critical services. For information about the cluster management fee for Pro Edition and provisioned control plane clusters, see cluster management fee.	ack.pro.small
system_events_logging	object	No	The configuration for storing system events.
enabled	boolean	No	Specifies whether to enable system event logging. Valid values: true: Enables system event logging. false: Disables system event logging.	true
logging_project	string	No	The name of the Log Service project for storing system events.	k8s-log-cb95aa626a47740afbf6aa099b65****
operation_policy	object	No	The automatic O&M policy for the cluster.
cluster_auto_upgrade	object	No	The cluster auto-upgrade policy.
enabled	boolean	No	Specifies whether to enable cluster auto-upgrades. Valid values: true: Enables auto-upgrades. false: Disables auto-upgrades.	true
channel	string	No	The auto-upgrade channel. For more information, see Upgrade channels. Valid values: `patch`: upgrades to the latest patch version. `stable`: upgrades to the latest stable minor version. rapid: The latest minor version.	patch
api_server_custom_cert_sans	object	No	The custom Subject Alternative Names (SANs) for the API Server certificate. This parameter allows you to add custom IP addresses or domain names to the SAN field of the API Server certificate for client access control. This parameter is available only for managed clusters.
action	string	No	The modification method for the SANs. Valid values: overwrite: Overwrites the existing SANs. append: Appends to the existing SANs.	append
subject_alternative_names	array	No	The list of SANs.
	string	No	A single SAN, which can be an IP address or a domain name.	aliyun.xxx.com,192.168.xx.xx
vswitch_ids	array	No	The VSwitches for the cluster control plane. In dedicated clusters, changes apply only to newly added control plane nodes. When you change the control plane VSwitches in managed clusters, note the following: This parameter performs an overwrite update. You must specify the complete list of target VSwitches. The control plane components restart briefly during the change. Proceed with caution. Ensure that the inbound and outbound rules of all security groups (including the control plane security group, all node pool security groups, and the container network security group) allow traffic from the IP address CIDR blocks of the new VSwitches. Otherwise, nodes and containers may fail to connect to the API Server. If the new control plane VSwitches are associated with an ACL, ensure that the ACL rules allow communication with the IP address CIDR blocks of cluster nodes and the container network.
	string	No	A VSwitch for the cluster control plane.	vsw-2ze4jvvvade1yk899****
control_plane_config	object	No	The control plane configuration for a dedicated cluster.
charge_type	string	No	The billing method of the control plane nodes. Valid values: `PrePaid`: Subscription. `PostPaid`: Pay-As-You-Go. Default value: `PostPaid`.	PostPaid
period	integer	No	The subscription duration of the control plane nodes. This parameter is required only if `charge_type` is set to `PrePaid`. If `period_unit` is set to `Month`, valid values are: 1, 2, 3, 6, 12, 24, 36, 48, and 60.	1
period_unit	string	No	The billing cycle of the control plane nodes. This parameter applies only when `charge_type` is set to `PrePaid`. `Month`: A monthly billing cycle is used. Only monthly subscriptions are supported.	Month
auto_renew	boolean	No	Specifies whether to enable auto-renewal for the subscription control plane nodes. This parameter takes effect only when `charge_type` is set to `PrePaid`. Valid values: `true`: Enables auto-renewal. `false`: Disables auto-renewal. Default value: `false`.	false
auto_renew_period	integer	No	The auto-renewal period for the control plane nodes, in months. Valid values: 1, 2, 3, 6, and 12. Default value: `1`.	1
instance_types	array	No	The instance types. For more information, see Instance types.
	string	No	An instance type.	ecs.g6.large
image_type	string	No	The OS image type. Valid values: `AliyunLinux3`: Alinux3 image. `Custom`: Custom image.	AliyunLinux3
image_id	string	No	The ID of the custom image. Specify this parameter when you use a custom image.	aliyun_3_x64_20G_alibase_20240819.vhd
key_pair	string	No	The name of the key pair. You must specify either this parameter or`login_password`.	ack
login_password	string	No	The SSH logon password. You must specify either this parameter or `key_pair`. The password must be 8 to 30 characters long and contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. If a password is used, it will be applied to new control plane nodes during scale-out operations.	Ack@2000.
system_disk_category	string	No	The type of the node system disk. Valid values: `cloud_efficiency`: Ultra Disk. `cloud_ssd`: SSD. `cloud_essd`: ESSD. `cloud_auto`: ESSD AutoPL disk. `cloud_essd_entry`: ESSD Entry disk.	cloud_essd
system_disk_size	integer	No	The size of the node system disk, in GiB. The value must be between 40 and 500.	120
system_disk_snapshot_policy_id	string	No	The ID of the automatic snapshot policy to apply to the node system disks.	sp-2zej1nogjvovnz4z****
system_disk_performance_level	string	No	The performance level (PL) of the system disk. This parameter applies only to ESSDs. The PL depends on the disk size. For more information, see ESSDs.	PL1
system_disk_provisioned_iops	integer	No	The provisioned IOPS of the node system disk. Valid values: 0 to min{50,000, 1,000 × Capacity - Base IOPS}. Base IOPS = min{1,800 + 50 × Capacity, 50,000}. You can set this parameter only when `system_disk_category` is set to `cloud_auto`. For more information, see ESSD AutoPL disks.	1000
system_disk_bursting_enabled	boolean	No	Specifies whether to enable the performance burst feature for the system disk. Valid values: `true`: Enables the performance burst feature. `false`: Disables the performance burst feature. You can set this parameter only when `system_disk_category` is set to `cloud_auto`. For more information, see ESSD AutoPL disks.	true
deploymentset_id	string	No	The ID of the deployment set.	ds-bp10b35imuam5amw****
cloud_monitor_flags	boolean	No	Specifies whether to install the CloudMonitor agent on the control plane nodes. Valid values: `true`: Installs the CloudMonitor agent. `false`: Does not install the CloudMonitor agent.	true
soc_enabled	boolean	No	Specifies whether to enable MLPS-compliant security hardening. For more information, see Enable MLPS-compliant security hardening for ACK. Valid values: `true`: Enables MLPS-compliant security hardening. `false`: Disables MLPS-compliant security hardening. Default value: `false`.	false
security_hardening_os	boolean	No	Specifies whether to enable Alibaba Cloud OS Security Hardening. Valid values: `true`: Enables Alibaba Cloud OS Security Hardening. `false`: Disables Alibaba Cloud OS Security Hardening. Default value: `false`.	false
cpu_policy	string	No	The node CPU management policy. The following policies are supported for clusters of Kubernetes 1.12.6 or later: `static`: allows pods with specific resource characteristics to have enhanced CPU affinity and exclusivity on the node. `none`: uses the default CPU affinity scheme. Default value: `none`.	none
runtime	string	No	The container runtime. Valid values: `containerd`: Recommended. This runtime is supported in all cluster versions. Default value: `containerd`.	containerd
node_port_range	string	No	The NodePort range for the cluster. The range must be within 30000-65535. Default value: `30000-32767`.	30000-32767
size	integer	No	The number of control plane nodes. To scale out the control plane of a dedicated cluster, set this parameter to the target number of control plane nodes, which must be greater than the current number.	5
security_group_id	string	No	The ID of the control plane security group. If you configure deny rules in the security group, ensure that the security group rules allow traffic on the protocols and ports that are required by the cluster. For more information about the recommended security group rules, see Configure and manage cluster security groups. For managed clusters, the control plane and installed managed components, such as terway-controlplane, are briefly restarted during the change. We recommend that you perform this operation during off-peak hours. After you change the control plane security group, the elastic network interfaces (ENIs) used by the control plane and managed components are automatically added to the new security group. For dedicated clusters, after you change the control plane security group, the new security group is automatically applied to newly added control plane nodes. Existing control plane nodes are not affected.	sg-bp1h6rk3pgct2a08***
timezone	string	No	The time zone of the cluster. For more information, see Supported time zones. After you change the time zone, the cluster inspection configuration uses the new time zone setting. For managed clusters, the control plane and installed managed components, such as terway-controlplane, are briefly restarted during the change. We recommend that you perform this operation during off-peak hours. After you change the time zone, the new time zone is automatically applied to newly added nodes. Existing nodes are not affected. You can reset the nodes in a node pool to apply the new time zone to the existing nodes. For dedicated clusters, after you change the time zone, the new time zone is automatically applied to newly added nodes (including control plane nodes). Existing nodes (including control plane nodes) are not affected. You can reset the nodes in a node pool to apply the new time zone to existing worker nodes. To apply the new time zone to all control plane nodes, you must scale out and then scale in the control plane.	Asia/Shanghai
control_plane_endpoints_config	object	No	The cluster connection configuration.
internal_dns_config	object	No	The internal DNS configuration for the cluster. This parameter is applicable only to ACK managed clusters. Node-side system components, such as kubelet and kube-proxy, use the internal domain of the cluster to access the API Server. If this feature is disabled, they access the API Server by using its SLB IP address.
bind_vpcs	array	No	The VPCs in which the internal domain records of the cluster take effect.
	string	No	A VPC in which the internal domain records of the cluster take effect.	vpc-xxxx
enabled	boolean	No	Specifies whether to enable access to the cluster over an internal domain. Valid values: true: Enables access to the cluster over an internal domain. Node-side components such as kubelet and kube-proxy will access the API Server by using the internal domain of the cluster.	true
access_control_list `deprecated`	array	No	The access control list of the SLB instance for the API Server of a registered cluster.
	string	No	A CIDR block for the access control list. Note: Do not specify the 0.0.0.0/0 CIDR block.	192.168.XX.XX/24
instance_deletion_protection `deprecated`	boolean	No	Specifies whether to enable deletion protection for nodes. When enabled, nodes cannot be released from the console or by calling an API operation. Valid values: `true`: You cannot release nodes from the console or by calling an API operation. `false`: You can release nodes from the console or by calling an API operation. Default value: `false`.	false
ingress_domain_rebinding `deprecated`	boolean	No	Specifies whether to rebind the default Ingress domain name of the cluster. Valid values: `true`: Rebinds the default Ingress domain name of the cluster. `false`: Does not rebind the default Ingress domain name of the cluster. Default value: `false`.	false
ingress_loadbalancer_id `deprecated`	string	No	The ID of the SLB instance that is used for the cluster Ingress.	lb-wz97kes8tnndkpodw****

Response elements

Element	Type	Description	Example
	object	The data returned for the modification request.
cluster_id	string	The unique identifier of the cluster.	cb95aa626a47740afbf6aa09****
request_id	string	The unique identifier of the request. Include this ID in support tickets for troubleshooting.	687C5BAA-D103-4993-884B-C35E4314****
task_id	string	The unique identifier of the asynchronous modification task.	T-5a54309c80282e39ea00****

Examples

Success response

JSON format

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

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.