Update Edge Cluster Config with ModifyCluster API - ACK Edge - Alibaba Cloud - Container Service for Kubernetes

Modifies the configuration of an ACK cluster.

Operation description

Important Starting from July 4, 2026, the request parameters instance_deletion_protection, ingress_loadbalancer_id, and access_control_list will no longer take effect. For more information about the changes, see Announcement on changes to ACK cluster management OpenAPI request and response parameters and OpenAPI deprecation.

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	Indicates whether an EIP is attached to the cluster for public network access to the API server. Valid values: `true`: An EIP is attached to the cluster. `false`: No EIP is attached to the cluster.	true
api_server_eip_id	string	No	The instance ID of the EIP attached to the cluster API server. This parameter takes effect only when `api_server_eip` is set to `true`.	eip-wz9fnasl6dsfhmvci****
deletion_protection	boolean	No	Specifies whether to enable deletion protection for the cluster to prevent accidental deletion through the console or API. Valid values: `true`: Enables cluster deletion protection. The cluster cannot be deleted through the console or API. `false`: Disables cluster deletion protection. The cluster can be deleted through the console or API. Default value: `false`.	false
resource_group_id	string	No	The resource group ID of the cluster.	rg-acfmyvw3wjm****
maintenance_window	maintenance_window	No	The O&M window configuration of the cluster. This feature takes effect only for ACK Pro clusters.
enable_rrsa	boolean	No	Specifies whether to enable or disable the RRSA feature. Only managed clusters support this parameter. Valid values: `true`: Enabled. `false`: Disabled.	true
cluster_name	string	No	The custom cluster name. The name can contain digits, Chinese characters, letters, and hyphens (-). It must be 1 to 63 characters in length and cannot start with a hyphen (-).	cluster-new-name
cluster_spec	string	No	The cluster specification when `cluster_type` is set to `ManagedKubernetes` and `profile` is configured. Valid values: `ack.pro.small`: Pro `ack.pro.xlarge`: Pro XL `ack.pro.2xlarge`: Pro 2XL `ack.pro.4xlarge`: Pro 4XL (contact customer service to add your account to the whitelist) Pro XL, Pro 2XL, and Pro 4XL are three tiers provided by ACK Pro Provisioned Control Plane. By pre-allocating and dedicating control plane resources, these tiers ensure that API concurrency and pod scheduling capabilities remain at a consistently high level. They are suitable for AI training and inference, ultra-large-scale clusters, and mission-critical workloads. For information about the cluster management fees for Pro and Provisioned Control Plane editions, see Cluster management fees.	ack.pro.small
system_events_logging	object	No	The system event storage configuration.
enabled	boolean	No	Specifies whether to enable system event storage. true: Enables system event storage. false: Disables system event storage.	true
logging_project	string	No	The name of the LogProject for system event storage.	k8s-log-cb95aa626a47740afbf6aa099b65****
operation_policy	object	No	The cluster automatic O&M policy.
cluster_auto_upgrade	object	No	The cluster auto upgrade configuration.
enabled	boolean	No	Whether to enable cluster automatic upgrade. true: Enable automatic upgrade. false: Disable automatic upgrade.	true
channel	string	No	Cluster automatic upgrade frequency. For more information, see Upgrade Frequency. Valid values: patch: Latest patch version. stable: Second latest minor version. rapid: Latest minor version.	patch
api_server_custom_cert_sans	object	No	The custom API server certificate SAN (Subject Alternative Name). This parameter adds custom IP addresses or domain names to the SAN field of the cluster API server certificate for client access control. Only managed clusters support this parameter.
action	string	No	Specifies whether to overwrite or append the SAN configuration. Valid values: overwrite: overwrites the existing configuration. append: appends to the existing configuration.	append
subject_alternative_names	array	No	The SAN list.
	string	No	The SAN. Custom IP addresses or domain names are supported. Separate multiple IP addresses or domain names with commas (,).	aliyun.xxx.com,192.168.xx.xx
vswitch_ids	array	No	The vSwitches for the cluster control plane. For dedicated clusters, the change applies to newly scaled-out control plane nodes. When changing control plane vSwitches for managed clusters, note the following: This parameter performs a full overwrite. Specify the complete list of target vSwitches. Control plane components will briefly restart during the change. Proceed with caution. Ensure that all security groups of the cluster (including the control plane security group, security groups of all node pools, and security groups used by the container network) allow inbound and outbound traffic for the IP CIDR blocks of the new vSwitches to prevent nodes and containers from being unable to connect to the API server. If ACL rules are configured for the new control plane vSwitches, ensure that the ACL rules allow communication with the CIDR blocks of cluster nodes and the container network.
	string	No	The vSwitch for the cluster control plane.	vsw-2ze4jvvvade1yk899****
control_plane_config	object	No	The dedicated cluster control plane configuration.
charge_type	string	No	The billing method of control plane node instances. Valid values: `PrePaid`: subscription. `PostPaid`: pay-as-you-go. Default value: `PostPaid`.	PostPaid
period	integer	No	The subscription duration of control plane node instances. This parameter takes effect and is required only when `charge_type` is set to `PrePaid`. When `period_unit=Month`, valid values are {1, 2, 3, 6, 12, 24, 36, 48, 60}.	1
period_unit	string	No	The billing cycle unit of control plane node instances. This parameter takes effect only when `charge_type` is set to `PrePaid`. `Month`: billed on a monthly basis. Currently, only monthly billing is supported.	Month
auto_renew	boolean	No	Specifies whether to enable auto-renewal for control plane node instances. 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 duration per cycle for control plane node instances. Valid values: {1, 2, 3, 6, 12}. Unit: months. Default value: 1.	1
instance_types	array	No	The instance types. For more information, see Instance families.
	string	No	The instance type.	ecs.g6.large
image_type	string	No	The operating system image type. Valid values: `AliyunLinux3`: Alinux3 image. `Custom`: custom image.	AliyunLinux3
image_id	string	No	The custom image ID. Specify this parameter when using a custom image.	aliyun_3_x64_20G_alibase_20240819.vhd
key_pair	string	No	The key pair name. Specify either this parameter or `login_password`.	ack
login_password	string	No	The SSH logon password. Specify either this parameter or `key_pair`. The password must be 8 to 30 characters in length and contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. To use password-based logon, specify this parameter during scale-out.	Ack@2000.
system_disk_category	string	No	The type of the node system cloud disk. Valid values: `cloud_efficiency`: ultra cloud disk. `cloud_ssd`: standard SSD. `cloud_essd`: ESSD. `cloud_auto`: ESSD AutoPL cloud disk. `cloud_essd_entry`: ESSD Entry cloud disk.	cloud_essd
system_disk_size	integer	No	The size of the node system cloud disk. Valid values: [40, 500]. Unit: GiB.	120
system_disk_snapshot_policy_id	string	No	The ID of the automatic snapshot policy applied to the node system cloud disk.	sp-2zej1nogjvovnz4z****
system_disk_performance_level	string	No	The performance level (PL) of the node system cloud disk. This parameter takes effect only for ESSD cloud disks. The performance level is related to the disk size. For more information, see standard SSDs.	PL1
system_disk_provisioned_iops	integer	No	The provisioned read/write IOPS of the node system cloud disk. Valid values: 0 to min{50,000, 1000 × capacity - baseline performance}. Baseline performance = min{1,800 + 50 × capacity, 50,000}. This parameter is supported only when `system_disk_category` is set to `cloud_auto`. For more information, see ESSD AutoPL cloud disks.	1000
system_disk_bursting_enabled	boolean	No	Specifies whether to enable burst (performance burst) for the node system cloud disk. Valid values: `true`: Enabled. `false`: Disabled. This parameter is supported only when `system_disk_category` is set to `cloud_auto`. For more information, see ESSD AutoPL cloud disks.	true
deploymentset_id	string	No	The deployment set ID.	ds-bp10b35imuam5amw****
cloud_monitor_flags	boolean	No	Specifies whether to install the CloudMonitor agent on 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 2.0 security hardening. For more information, see China-classified protection compliance for ACK. Valid values: `true`: Enables MLPS 2.0 security hardening. `false`: Disables MLPS 2.0 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 running version 1.12.6 or later: `static`: Allows pods with certain resource characteristics on the node to be granted enhanced CPU affinity and exclusivity. `none`: Uses the existing default CPU affinity scheme. Default value: `none`.	none
runtime	string	No	The container runtime name. Valid values: `containerd`: Recommended. Supported by all cluster versions. Default value: containerd.	containerd
node_port_range	string	No	The node service port range. Available port range: [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 control plane security group ID. If you have configured blocking rules in the security group, ensure that the security group rules allow the protocols and ports required by the cluster. For information about recommended security group rules, see Configure and manage cluster security groups. For non-ACK dedicated clusters, control plane components and installed managed components (such as terway-controlplane) will briefly restart during the change. Perform this operation during off-peak hours. After the control plane security group is changed, the network interface controllers (NICs) used by the control plane and installed managed components are automatically added to the new security group during the cluster management procedure. For ACK dedicated clusters, after the control plane security group is changed, newly scaled-out master nodes automatically use the new control plane security group. Existing control plane nodes are not affected.	sg-bp1h6rk3pgct2a08***
timezone	string	No	The cluster time zone. See Supported time zones. After the time zone is changed, the cluster inspection configuration uses the new time zone settings. For managed clusters, control plane components and installed managed components (such as terway-controlplane) will briefly restart during the change. Perform this operation during off-peak hours. After the time zone is changed, newly scaled-out nodes automatically use the new time zone settings. Existing nodes are not affected. You can use the node pool node reset feature to apply the new settings to existing nodes. For dedicated clusters, after the time zone is changed, newly scaled-out nodes (including control plane nodes) automatically use the new time zone settings. Existing nodes (including control plane nodes) are not affected. You can use the node pool node reset feature to apply the new settings to existing nodes. For control plane nodes, scale out and then scale in to apply the new settings to all control plane nodes.	Asia/Shanghai
client_token	string	No	The client token.	af31042c-6355-495b-b6e3-exxb9669
control_plane_endpoints_config	object	No	The cluster endpoint configuration.
load_balancers_config	array<object>	No	The cluster access load balancing configuration.
	object	No	The cluster access load balancing configuration.
endpoint_type	string	No
load_balancer_id	string	No
internal_dns_config	object	No	The internal DNS configuration for the cluster. Applicable to ACK managed clusters. The internal domain name is used by node-side system components such as kubelet and kube-proxy to access the API server. When internal domain name access is not enabled, node-side system components access the API server through the CLB IP address.
bind_vpcs	array	No	VPCs where the cluster internal domain name record resolution takes effect.
	string	No	VPCs where the cluster internal domain name record resolution takes effect.	vpc-xxxx
enabled	boolean	No	Whether to enable cluster internal domain name access. Valid values: true: Enable cluster internal domain name access. Node-side components (kubelet, kube-proxy) will access the API Server through the cluster internal domain name.	true
access_control_list `deprecated`	array	No	The access control list for the registered cluster API server SLB.
	string	No	The access control list for the registered cluster API server SLB. Note: The 0.0.0.0/0 CIDR block is not allowed.	192.168.XX.XX/24
instance_deletion_protection `deprecated`	boolean	No	Specifies whether to enable instance deletion protection to prevent accidental deletion of nodes through the console or API. Valid values: `true`: Nodes cannot be accidentally deleted through the console or API. `false`: Nodes can be accidentally deleted through the console or API. Default value: `false`.	false
ingress_domain_rebinding `deprecated`	boolean	No	Specifies whether to rebind the cluster test domain name. Valid values: `true`: Rebinds the cluster test domain name. `false`: Does not rebind the cluster test domain name. Default value: `false`.	false
ingress_loadbalancer_id `deprecated`	string	No	The SLB instance ID of the cluster to be modified.	lb-wz97kes8tnndkpodw****

Response elements

Element	Type	Description	Example
	object	The response body.
cluster_id	string	The cluster ID.	cb95aa626a47740afbf6aa09****
request_id	string	The request ID.	687C5BAA-D103-4993-884B-C35E4314****
task_id	string	The task ID.	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.