Documentation
Home Page Container Service for Kubernetes ACK Managed and Dedicated Clusters Developer Reference API Reference API catalog Cluster ModifyCluster

ModifyCluster

Updated at:
Copy as MD
Product

Call the ModifyCluster API to modify the configuration of an ACK cluster.

Operation description

Important As of July 4, 2026, the instance_deletion_protection, ingress_loadbalancer_id, and access_control_list request parameters will be deprecated. For details, see Announcement on ACK Cluster Management OpenAPI Parameter Changes and Deprecations.

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 ID of the cluster.

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's API server for 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 to associate with the cluster's 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. This prevents the cluster from being accidentally deleted through the console or an API operation. Valid values:

  • true: Enables deletion protection. The cluster cannot be deleted through the console or an API operation.

  • false: Disables deletion protection. The cluster can be deleted through the console or 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 for the cluster. This feature is available only for ACK Pro managed clusters.

enable_rrsa

boolean

No

Specifies whether to enable the RRSA feature. This parameter is available only for 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 in length. It can contain digits, letters, Chinese characters, and hyphens (-), but cannot start with a hyphen.

cluster-new-name
cluster_spec

string

No

The specification of the cluster. This parameter is available 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 (This edition is available only to allowlisted users.)

This feature pre-allocates control plane resources to ensure consistent, high-performance API concurrency and Pod scheduling. It is ideal for AI workloads, ultra-large-scale clusters, and mission-critical applications.

For more information about the management fees of Pro edition and provisioned control plane clusters, see Cluster management fees.

ack.pro.small
system_events_logging

object

No

Settings for system event storage.

enabled

boolean

No

Specifies whether to enable system event storage. Valid values:

  • true: enables system event storage.

  • false: Does not store system events.

true
logging_project

string

No

The name of the LogProject for system event storage.

k8s-log-cb95aa626a47740afbf6aa099b65****
operation_policy

object

No

The automated O&M policy of the cluster.

cluster_auto_upgrade

object

No

The auto-upgrade policy of the cluster.

enabled

boolean

No

Specifies whether to enable automatic cluster upgrades. Valid values:

  • true: enables automatic upgrades.

  • false: Automatic upgrade is disabled.

true
channel

string

No

The auto-upgrade channel for the cluster. For more information, see Upgrade frequency.

Valid values:

  • patch: the latest patch version.

  • stable: the previous 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 allows clients to access the API server using custom IP addresses or domain names.

This parameter is available only for managed clusters.

action

string

No

The action to perform on the SAN configuration. Valid values:

  • overwrite: Overwrites the existing SAN configuration.

  • append: Appends to the existing SAN configuration.

append
subject_alternative_names

array

No

The list of SANs.

string

No

A single SAN. This can be a custom IP address or a domain name.

aliyun.xxx.com,192.168.xx.xx
vswitch_ids

array

No

The VSwitches of the control plane. For a dedicated cluster, this change affects only newly added control plane nodes. When you change the VSwitches for a managed cluster, take note of the following items:

  • This parameter overwrites the existing VSwitch list. You must specify the full list of target VSwitches.

  • The control plane components will restart briefly during the update. We recommend performing this operation during off-peak hours.

  • Make sure that the inbound and outbound rules of all security groups in the cluster (including the control plane security group, security groups of all node pools, and security groups used by the container network) allow traffic from the IP CIDR blocks of the new VSwitches. Otherwise, nodes and containers may fail to connect to the API server.

  • If you configure an access control list (ACL) for the new control plane VSwitches, make sure that the ACL allows communication with the IP CIDR blocks of the cluster nodes and container network.

string

No

A VSwitch for the control plane.

vsw-2ze4jvvvade1yk899****
control_plane_config

object

No

The configurations of the control plane for a dedicated cluster.

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 the control plane node instances. This parameter is required only if charge_type is set to PrePaid.

If period_unit=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 node instances. This parameter is required only if charge_type is set to PrePaid.

Month: The billing cycle is monthly. This is the only supported value.

Month
auto_renew

boolean

No

Specifies whether to enable auto-renewal for the control plane node instances. This parameter is available only if 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 duration of each auto-renewal for the control plane node instances.

Valid values: 1, 2, 3, 6, and 12. Unit: month.

Default value: 1.

1
instance_types

array

No

The instance types. For more information, see instance family.

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. This parameter is required if you use a custom image.

aliyun_3_x64_20G_alibase_20240819.vhd
key_pair

string

No

The name of the key pair. You must set this parameter or login_password.

ack
login_password

string

No

The SSH login password for the nodes. 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. This password is used for new nodes when you scale out the control plane.

Ack@2000.
system_disk_category

string

No

The type of the system disk. Valid values:

  • cloud_efficiency: Ultra Disk.

  • cloud_ssd: standard 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 system disk. Unit: GiB. Valid values: 40 to 500.

120
system_disk_snapshot_policy_id

string

No

The ID of the automatic snapshot policy that is used for the system disk of the node.

sp-2zej1nogjvovnz4z****
system_disk_performance_level

string

No

The performance level of the system disk. This parameter is available only for ESSDs. The performance level is related to the disk size. For more information, see ESSDs.

PL1
system_disk_provisioned_iops

integer

No

The provisioned read/write IOPS of the system disk. Valid values: 0 to min{50,000, 1,000 × Capacity - Base IOPS}. Base IOPS = min{1,800 + 50 × Capacity, 50,000}.

This parameter is available 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 bursting for the system disk. Valid values:

  • true: yes

  • false: no

This parameter is available 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

Enables level 3 protection. For more information, see Enable level 3 protection for an ACK cluster.

Valid values:

  • true: enables level 3 protection.

  • false: disables level 3 protection.

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. For clusters of version 1.12.6 or later, the following policies are supported:

  • static: allows pods with specific resource characteristics to be granted increased CPU affinity and exclusivity on the node.

  • none: indicates that the default CPU affinity scheme is used.

Default value: none.

none
runtime

string

No

The name of the container runtime. Valid values:

  • containerd: Recommended. Supported by all cluster versions.

Default value: containerd.

containerd
node_port_range

string

No

The port range for NodePort services. Valid range: 30000 to 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 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 rules in the security group to block traffic, make sure to allow traffic on the ports and protocols that the cluster depends on. For more information about the recommended security group rules, see Configure and manage cluster security groups.

  • For clusters other than dedicated ACK clusters, the control plane and installed managed components, such as terway-controlplane, restart briefly during the update. We recommend that you perform this operation during off-peak hours. After the control plane security group is changed, the elastic network interfaces (ENIs) that are used by the control plane and installed managed components are automatically added to the new security group.

  • For dedicated ACK clusters, the new control plane security group is automatically applied to new master nodes after the security group is changed. 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 the time zone is changed, the new time zone setting is applied to the cluster inspection feature.

  • For managed clusters, the control plane and installed managed components, such as terway-controlplane, restart briefly during the update. We recommend that you perform this operation during off-peak hours. After the time zone is changed, the new time zone setting is automatically applied to new nodes. Existing nodes are not affected. You can reset the nodes in the node pool to apply the new setting to them.

  • For dedicated clusters, after the time zone is changed, the new time zone setting is automatically applied to new 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 setting to them. For control plane nodes, you must scale out and then scale in the nodes to apply the new setting to all control plane nodes.

Asia/Shanghai
control_plane_endpoints_config

object

No

The cluster connection configurations.

internal_dns_config

object

No

The internal domain name configurations of the cluster. This parameter is available only for 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. If you do not enable access to the cluster over an internal domain name, the node-side system components access the API server by using the CLB IP address.

bind_vpcs

array

No

The VPC in which the internal domain name of the cluster is resolved.

string

No

The VPC in which the internal domain name of the cluster is resolved.

vpc-xxxx
enabled

boolean

No

Specifies whether to enable access to the cluster over an internal domain name. Valid values:

  • true: enables access to the cluster over an internal domain name. Node-side components, such as kubelet and kube-proxy, access the API server over the internal domain name.

true
access_control_list deprecated

array

No

The access control list (ACL) of the SLB instance that is used by the API server of a registered cluster.

string

No

The access control list (ACL) of the SLB instance that is used by the API server of a registered cluster.

Note Do not specify 0.0.0.0/0.

192.168.XX.XX/24
instance_deletion_protection deprecated

boolean

No

Specifies whether to enable deletion protection for nodes to prevent them from being deleted by mistake in the console or by calling an API operation. Valid values:

  • true: You cannot delete nodes by mistake in the console or by calling an API operation.

  • false: You can delete nodes by mistake in the console or by calling an API operation.

Default value: false.

false
ingress_domain_rebinding deprecated

boolean

No

Specifies whether to rebind the test domain name of the cluster. Valid values:

  • true: rebinds the test domain name of the cluster.

  • false: does not rebind the test domain name of the cluster.

Default value: false.

false
ingress_loadbalancer_id deprecated

string

No

The ID of the SLB instance that is associated with 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.

Previous：DeleteClusterNext：UpgradeCluster