DocsICP FilingConsole
Documentation

ModifyCluster

Updated at:
Copy as MD
Product
My Favorites

You can call the ModifyCluster operation to modify the configuration of an ACK cluster.

Operation description

Important Starting July 4, 2026, the request parameters instance_deletion_protection, ingress_loadbalancer_id, and access_control_list will no longer take effect. For details about the changes, see Announcement on changes to input and output parameters and deprecation of OpenAPI operations related to 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

Request body parameters.

true
api_server_eip

boolean

No

Specifies whether to bind an EIP to the cluster for public network access to the API server. Valid values:

  • true: Binds an EIP to the cluster.

  • false: Does not bind an EIP to the cluster.

true
api_server_eip_id

string

No

The EIP instance ID bound to the cluster API server. This parameter takes effect only when api_server_eip is set to true.

eip-wz9fnasl6dsfhmvci****
deletion_protection

boolean

No

Enables or disables cluster deletion protection to prevent accidental cluster deletion from the console or using APIs. Valid values:

  • true: Enables cluster deletion protection. You cannot delete the cluster from the console or using APIs.

  • false: Disables cluster deletion protection. You can delete the cluster from the console or using APIs.

Default value: false.

false
resource_group_id

string

No

The resource group ID of the cluster.

rg-acfmyvw3wjm****
maintenance_window maintenance_window

No

The maintenance window of the cluster. This feature is available only for ACK managed clusters Pro.

enable_rrsa

boolean

No

Enables or disables the RRSA feature. Only managed clusters support this parameter. Valid values:

  • true: Enables RRSA.

  • false: Disables RRSA.

true
cluster_name

string

No

The custom cluster name. The name can contain digits, letters, Chinese characters, 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 you set cluster_type to ManagedKubernetes and configure profile. Valid values:

  • ack.pro.small: Pro

  • ack.pro.xlarge: Pro XL

  • ack.pro.2xlarge: Pro 2XL

  • ack.pro.4xlarge: Pro 4XL (requires approval from customer service to enable)

Pro XL, Pro 2XL, and Pro 4XL are three tiers provided by ACK Pro provisioned control plane. These tiers pre-allocate and dedicate control plane resources to ensure consistent high performance for API concurrency and pod scheduling. They are suitable for AI training and inference, ultra-large-scale clusters, and mission-critical workloads.

For cluster management fees for Pro and provisioned control plane clusters, see Cluster management fees.

ack.pro.small
system_events_logging

object

No

System event logging configuration.

enabled

boolean

No

Specifies whether to enable system event logging.

  • true: Enables system event logging.

  • false: Disables system event logging.

true
logging_project

string

No

The LogProject name for system event logging.

k8s-log-cb95aa626a47740afbf6aa099b65****
operation_policy

object

No

Automatic O&M policy for the cluster.

cluster_auto_upgrade

object

No

Automatic cluster upgrade.

enabled

boolean

No

Specifies whether to enable automatic cluster upgrades.

  • true: Enables automatic upgrades.

  • false: Disables automatic upgrades.

true
channel

string

No

The frequency of automatic cluster upgrades. 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

This parameter adds custom IP addresses or domain names to the SAN field of the API server certificate to control client access.

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 list of SANs.

string

No

A SAN. You can specify custom IP addresses or domain names. 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 only to newly scaled-out control plane nodes. When you change the control plane vSwitches for managed clusters, note the following:

  • This parameter performs an overwrite update. You must specify the complete target vSwitch list.

  • Control plane components restart briefly during the update. Proceed with caution.

  • Ensure that all security groups (including those for the control plane, all node pools, and container networking) allow inbound and outbound traffic for the IP CIDR blocks of the new vSwitches. Otherwise, nodes and containers cannot connect to the API server.

  • If the new control plane vSwitches have ACL rules configured, ensure that these rules allow communication between the vSwitches and the IP CIDR blocks of cluster nodes and container networks.

string

No

A vSwitch for the cluster control plane.

vsw-2ze4jvvvade1yk899****
control_plane_config

object

No

Control plane configuration for dedicated clusters.

charge_type

string

No

The billing method for control plane node instances. Valid values:

  • PrePaid: Subscription.

  • PostPaid: Pay-as-you-go.

Default value: PostPaid.

PostPaid
period

integer

No

The subscription duration for control plane node instances. This parameter is required and takes effect 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 for control plane node instances. This parameter takes effect only when charge_type is set to PrePaid.

Month: Billing by month. 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 for each renewal of 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

An 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 you use 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 system disk category for nodes. Valid values:

  • cloud_efficiency: Ultra disk.

  • cloud_ssd: Standard SSD.

  • cloud_essd: ESSD.

  • cloud_auto: ESSD AutoPL.

  • cloud_essd_entry: ESSD Entry.

cloud_essd
system_disk_size

integer

No

The system disk size for nodes. Valid values: [40,500]. Unit: GiB.

120
system_disk_snapshot_policy_id

string

No

The automatic snapshot policy ID for node system disks.

sp-2zej1nogjvovnz4z****
system_disk_performance_level

string

No

The performance level of node system disks. This parameter applies only to ESSDs. The performance level depends on the disk size. For more information, see ESSD.

PL1
system_disk_provisioned_iops

integer

No

The provisioned read/write IOPS for node system disks. Valid values: 0 to min{50,000, 1000 × capacity - baseline performance}. Baseline performance = 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.

1000
system_disk_bursting_enabled

boolean

No

Specifies whether to enable performance burst for node system disks. Valid values:

  • true: Enables performance burst.

  • false: Disables performance burst.

You can set this parameter only when system_disk_category is set to cloud_auto. For more information, see ESSD AutoPL.

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

MLPS 2.0 security hardening. For more information, see Use MLPS 2.0 security hardening 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

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 CPU management policy for nodes. Clusters of version 1.12.6 or later support the following policies:

  • static: Enhances CPU affinity and exclusivity for pods with specific resource characteristics on nodes.

  • none: Uses the default CPU affinity scheme.

Default value: none.

none
runtime

string

No

The container runtime. Valid values:

  • containerd: Recommended. Supported by all cluster versions.

Default value: containerd.

containerd
node_port_range

string

No

Valid 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 security group ID for the control plane.

  • If you configure blocking rules in the security group, ensure that the security group rules allow the protocols and ports required by the cluster. For recommended security group rules, see Configure and manage cluster security groups.

  • For non-dedicated ACK clusters, the control plane and installed managed components (such as terway-controlplane) restart briefly during the update. Perform this operation during off-peak hours. After you change the control plane security group, the ENIs used by the control plane and managed components are automatically added to the new security group.

  • For ACK dedicated clusters, newly scaled-out master nodes automatically apply the new control plane security group. Existing control plane nodes are unaffected.

sg-bp1h6rk3pgct2a08***
timezone

string

No

The cluster time zone. For more information, see Supported time zones.

  • After you change the time zone, cluster inspection configurations use the new time zone.

  • For managed clusters, the control plane and installed managed components (such as terway-controlplane) restart briefly during the update. Perform this operation during off-peak hours. Newly scaled-out nodes automatically apply the new time zone. Existing nodes are unaffected. You can reset nodes in node pools to apply the new time zone to existing nodes.

  • For dedicated clusters, newly scaled-out nodes (including control plane nodes) automatically apply the new time zone. Existing nodes (including control plane nodes) are unaffected. You can reset nodes in node pools to apply the new time zone to existing nodes. For control plane nodes, scale out and then scale in to apply the new time zone to all control plane nodes.

Asia/Shanghai
control_plane_endpoints_config

object

No

Cluster connection configuration.

internal_dns_config

object

No

Internal domain name configuration for the cluster. This feature is available for ACK managed clusters. Cluster internal domain names allow node-side system components such as kubelet and kube-proxy to access the API server. If this feature is disabled, node-side system components access the API server through the CLB IP address.

bind_vpcs

array

No

The VPCs where cluster internal domain name resolution takes effect.

string

No

A VPC where cluster internal domain name resolution takes effect.

vpc-xxxx
enabled

boolean

No

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

  • true: Enables cluster internal domain name access. Node-side components (kubelet, kube-proxy) access the API server through the cluster internal domain name.

true
access_control_list deprecated

array

No

The access control list for the API server SLB of registered clusters.

string

No

An access control list entry for the API server SLB of registered clusters.

Note: Do not specify the 0.0.0.0/0 CIDR block.

192.168.XX.XX/24
instance_deletion_protection deprecated

boolean

No

Enables or disables instance deletion protection to prevent accidental release of nodes from the console or using APIs. Valid values:

  • true: Prevents accidental node deletion from the console or using APIs.

  • false: Allows accidental node deletion from the console or using APIs.

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.