All Products
Search

This Product

    Container Service for Kubernetes:ModifyCluster

    Document Center

    Container Service for Kubernetes:ModifyCluster

    Last Updated:Sep 10, 2026

    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 OpenAPI request and response parameters 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
    access_control_list deprecated

    array

    No

    The access control list (ACL) for the API server SLB of a registered cluster.

    string

    No

    The access control list (ACL) for the API server SLB of a registered cluster.

    Note: The 0.0.0.0/0 CIDR block is not allowed.

    192.168.XX.XX/24
    api_server_custom_cert_sans

    object

    No

    The custom API server certificate Subject Alternative Names (SANs). 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 SAN configuration.

    • append: appends to the existing SAN 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
    api_server_eip

    boolean

    No

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

    • true: The cluster is attached with an EIP.

    • false: The cluster is not attached with an EIP.

    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****
    client_token

    string

    No

    The client token.

    af31042c-6355-495b-b6e3-exxb9669
    cluster_name

    string

    No

    The custom cluster name. The name can contain digits, Chinese characters, letters, and hyphens (-). The name 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 be added 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
    control_plane_config

    object

    No

    The control plane configuration for dedicated clusters.

    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 period for each renewal of control plane node instances.

    Valid values: {1, 2, 3, 6, 12}. Unit: months.

    Default value: 1.

    1
    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
    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
    cpu_policy

    string

    No

    The CPU management policy for nodes. The following policies are supported for clusters running version 1.12.6 or later:

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

    • none: Uses the default CPU affinity scheme.

    Default value: none.

    none
    deploymentset_id

    string

    No

    The deployment set ID.

    ds-bp10b35imuam5amw****
    image_id

    string

    No

    The custom image ID. Specify this parameter when you use a custom image.

    aliyun_3_x64_20G_alibase_20240819.vhd
    image_type

    string

    No

    The operating system image type. Valid values:

    • AliyunLinux3: Alinux3 image.

    • Custom: custom image.

    AliyunLinux3
    instance_types

    array

    No

    The instance types. For more information, see Instance families.

    string

    No

    The instance type.

    ecs.g6.large
    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.
    node_port_range

    string

    No

    The node service port range. Valid port range: [30000, 65535].

    Default value: 30000-32767.

    30000-32767
    period

    integer

    No

    The subscription duration for control plane node instances. This parameter takes effect and is required only when charge_type is set to PrePaid.

    If period_unit=Month, valid values are {1, 2, 3, 6, 12, 24, 36, 48, 60}.

    1
    period_unit

    string

    No

    The billing cycle unit for control plane node instances. This parameter takes effect only when charge_type is set to PrePaid.

    Month: The billing cycle is measured in months. Currently, only months are supported.

    Month
    runtime

    string

    No

    The container runtime name. Valid values:

    • containerd: Recommended. Supported by all cluster versions.

    Default value: containerd.

    containerd
    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
    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
    soc_enabled

    boolean

    No

    Specifies whether to enable MLPS 2.0 security hardening. For more information, see China Chinese ACK MLPS 2.0 security hardening.

    Valid values:

    • true: Enables MLPS 2.0 security hardening.

    • false: Disables MLPS 2.0 security hardening.

    Default value: false.

    false
    system_disk_bursting_enabled

    boolean

    No

    Specifies whether to enable burst mode for the node system cloud disk. Valid values:

    • true: Enables burst mode.

    • false: Disables burst mode.

    This parameter is supported only when system_disk_category is set to cloud_auto. For more information, see ESSD AutoPL cloud disks.

    true
    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_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 varies based on the cloud disk size. For more information, see ESSDs.

    PL1
    system_disk_provisioned_iops

    integer

    No

    The provisioned read/write IOPS for 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_size

    integer

    No

    The size of the node system cloud disk. Valid values: 40 to 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****
    control_plane_endpoints_config

    object

    No

    The cluster connection configuration.

    internal_dns_config

    object

    No

    The internal domain name configuration of the cluster. This parameter applies 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. If the internal domain name access is not enabled, node-side system components access the API server through the CLB IP address.

    bind_vpcs

    array

    No

    The VPCs in which the internal domain name DNS records take effect.

    string

    No

    The VPCs in which the internal domain name DNS records take effect.

    vpc-xxxx
    enabled

    boolean

    No

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

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

    true
    load_balancers_config

    array<object>

    No

    The load balancing configuration for cluster access.

    object

    No

    The load balancing configuration for cluster access.

    endpoint_type

    string

    No

    The endpoint type.

    public
    load_balancer_id

    string

    No

    The SLB instance associated with the endpoint.

    nlb-xxxx
    deletion_protection

    boolean

    No

    Specifies whether to enable deletion protection for the cluster. Deletion protection prevents the cluster from being accidentally deleted in the console or by calling API operations. Valid values:

    • true: Enables deletion protection. The cluster cannot be deleted in the console or by calling API operations.

    • false: Disables deletion protection. The cluster can be deleted in the console or by calling API operations.

    Default value: false.

    false
    enable_rrsa

    boolean

    No

    Specifies whether to enable or disable the RRSA feature. Only managed clusters support this parameter. Valid values:

    • true: Enable.

    • false: Disable.

    true
    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 instance ID of the SLB instance of the cluster to be modified.

    lb-wz97kes8tnndkpodw****
    instance_deletion_protection deprecated

    boolean

    No

    Specifies whether to enable instance deletion protection to prevent nodes from being accidentally deleted in the console or by calling API operations. Valid values:

    • true: Nodes cannot be accidentally deleted in the console or by calling API operations.

    • false: Nodes can be deleted in the console or by calling API operations.

    Default value: false.

    false
    maintenance_window maintenance_window

    No

    The O&M window configuration of the cluster. This feature takes effect only in ACK Pro managed clusters.

    operation_policy

    object

    No

    The automatic O&M policy of the cluster.

    cluster_auto_upgrade

    object

    No

    The automatic cluster upgrade configuration.

    channel

    string

    No

    The automatic cluster upgrade frequency. For more information, see Upgrade frequency.

    Valid values:

    • patch: The latest patch version.

    • stable: The second latest minor version.

    • rapid: The latest minor version.

    patch
    enabled

    boolean

    No

    Specifies whether to enable automatic cluster upgrade.

    • true: Enables automatic upgrade.

    • false: Disables automatic upgrade.

    true
    resource_group_id

    string

    No

    The resource group ID of the cluster.

    rg-acfmyvw3wjm****
    security_group_id

    string

    No

    The security group ID of the control plane.

    • If you have configured blocking rules in the security group, make sure that the security group rules allow the protocols and ports that the cluster depends on. For the recommended security group rule scope, see Configure and manage cluster security groups.

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

    • 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***
    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****
    timezone

    string

    No

    The time zone of the cluster. See Supported time zones.

    • After the time zone is changed, the cluster inspection configuration uses the new time zone settings.

    • For managed clusters, the cluster control plane and installed managed components (such as terway-controlplane) 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, you need to scale out and then scale in to apply the new settings to all control plane nodes.

    Asia/Shanghai
    vswitch_ids

    array

    No

    The control plane vSwitches of the cluster. For dedicated clusters, the change applies to newly scaled-out control plane nodes. For managed clusters, note the following items when changing the control plane vSwitches:

    • This parameter performs a full overwrite update. Specify the complete target vSwitch list.

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

    • Make sure 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. This prevents nodes and containers from being unable to connect to the API server.

    • If ACL rules are configured for the new control plane vSwitches, make sure that the ACL rules allow communication with the IP CIDR blocks of cluster nodes and the container network.

    string

    No

    The control plane vSwitch of the cluster.

    vsw-2ze4jvvvade1yk899****

    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.