All Products
Search
Document Center

Container Service for Kubernetes:Create an ACK One registered cluster

Last Updated:Sep 21, 2026

An ACK One registered cluster allows you to connect Kubernetes clusters from your data centers or other cloud providers to the Container Service for Kubernetes console for unified management.

Important

Before you begin, read Registered clusters to understand the key concepts and use cases of an ACK One registered cluster.

Procedure

Create an ACK One registered cluster and attach a target cluster in the console

Create an ACK One registered cluster

  1. Log on to the ACK console. In the left navigation pane, click Clusters.

  2. At the top left of the page, select the resource group and region of the target resource. image

  3. On the Clusters page, click Create Kubernetes Cluster.

  4. Click the ACK One Registered Cluster tab and follow the on-screen instructions to configure the cluster.

    Parameter

    Description

    Cluster Name

    Enter a custom name for the cluster.

    Region

    The region where the cluster resources, such as ECS instances and cloud disks, are located. The closer the region is to your users and resource deployment region, the lower the network latency.

    IPv6 Dual-stack

    This feature is only available for Kubernetes 1.22 and later and only supports Terway. It cannot be used with the elastic Remote Direct Memory Access (eRDMA) feature

    The cluster supports both IPv4 and IPv6 protocols. However, communication between worker nodes and the control plane still uses IPv4 addresses. Make sure that:

    • The cluster VPC supports IPv6 dual-stack.

    • When using Terway in shared ENI mode, the node's instance type must support IPv6 and have the same number of supported IPv4 and IPv6 addresses.

    VPC

    The virtual private cloud (VPC) for the cluster. For high availability, select two or more different zones.

    • Automatic creation: ACK creates a corresponding vSwitch in each selected zone.

    • Use existing: Select a vSwitch to specify the zone for the cluster. You can create a new vSwitch or use an existing one.

    We recommend using standard private CIDR blocks for the cluster VPC, such as 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16. If you have special requirements, go to Quota Center to apply for permission to use a public CIDR block to create a cluster.

    Cloud resources and billing: imageVPC

    vSwitch

    Select an existing vSwitch from the list based on the zone, or click Create vSwitch to create a new one. The cluster control plane and the default node pool will use the vSwitch specified here. We recommend selecting vSwitches in multiple different zones to ensure high availability for the cluster.

    Security Group

    When using an existing VPC, you can choose to Select Existing Security Group

    This security group is applied to the cluster control plane, the default node pool, and any node pools that do not have a custom security group specified.

    Compared to basic security groups, advanced security groups can contain more private IP addresses but do not support intra-group connectivity. For more information, see Security group classification.

    • Automatic creation: All outbound traffic is allowed by default. Inbound traffic is allowed based on the recommended configuration. If you modify the rules later, ensure that the 100.64.0.0/10 CIDR block is allowed for inbound traffic.

      This CIDR block is used to access other Alibaba Cloud services for operations such as pulling images and querying basic ECS information.
    • Use existing: ACK does not configure additional access rules for the security group by default. You must manage the security group rules yourself to avoid access issues. For more information, see Configure cluster security groups.

    Access to API Server

    ACK automatically creates a pay-as-you-go private-facing Classic Load Balancer (CLB) instance as the internal endpoint for the API Server. This CLB instance cannot be reused or deleted. If deleted, the API Server will become inaccessible and cannot be recovered.

    To use an existing CLB instance, submit a ticket. After you select Use Existing Gateway for VPC, you can set SLB Source to Use Existing Gateway.

    You can choose to enable Expose API server with EIP.

    • Open: Binds an EIP to the API Server's private-facing CLB instance, allowing you to access and manage the cluster from the public network.

      This does not mean that resources within the cluster can access the public network. To allow cluster resources to access the public network, you must select Configure SNAT for VPC.
    • Not open: You can only connect to and operate the cluster using the kubeconfig file from within the VPC.

    To enable this later, see Access the API server over the internet.
    Starting from December 1, 2024, new CLB instances will incur an instance fee. For more information, see Billing item adjustment for Classic Load Balancer (CLB).

    Cloud resources and billing: imageCLB, imageEIP

    Advanced options (optional)

    Expand Advanced Options (Optional) to configure Deletion Protection, Resource Group, and other settings.

    Parameter

    Description

    Cluster Deletion Protection

    We recommend enabling this feature to prevent accidental deletion of the cluster through the console or OpenAPI.

    Resource Group

    Assign the cluster to the selected resource group for easier permission management and cost allocation.

    Label

    Bind key-value tags to the cluster to identify cloud resources.

  5. After you complete the configuration, click Create Kubernetes Cluster. The new cluster appears in the cluster list.

    After the cluster is created, its status is Waiting for Connection.

Attach the target cluster to an ACK One registered cluster

  1. Find the newly created ACK One registered cluster and click Details in the Actions column.

  2. On the Cluster Information page, click the Connection Information tab. On the Connection Information tab, select Internet or Private Network, and then click Copy on the right.

  3. Save the copied content to a file named agent.yaml. Then, run kubectl apply -f agent.yaml on the target cluster to register it with the ACK One registered cluster.

  4. Check the agent status in the target cluster.

    kubectl -n kube-system get pod |grep ack-cluster-agent

    Expected output:

    ack-cluster-agent-5f7d568f6-6fc4k              1/1     Running   0          9s
    ack-cluster-agent-5f7d568f6-tf6fp              1/1     Running   0          9s

    After the registration succeeds, the cluster status changes to Running on the Clusters page of the Container Service for Kubernetes console.

Results

On the Clusters page, find the corresponding ACK One registered cluster and click Details in the Actions column to view the Basic Information and Connection Information of the new cluster.

You can use this kubeconfig to connect to the target cluster and deploy application workloads. For more information about how to connect to a cluster, see Connect to a Kubernetes cluster by using kubectl.

Use onectl to create an ACK One registered cluster and attach a target cluster

  1. Install and configure onectl. For more information, see Manage a registered cluster by using onectl.

  2. onectl supports the following two methods to create an ACK One registered cluster.

    Important

    When you create an ACK One registered cluster, you must specify parameters such as the VPC, vSwitch, and region.

    • Non-interactive creation:

      onectl cluster create --region **** --vpc **** --vswitch ****
    • Interactive creation:

      onectl cluster create -i

    Run the following command to view detailed parameter descriptions:

    onectl cluster create -h

    After the cluster is created, it is initialized and enters the initial state. The expected output is as follows:

    Registered cluster test-registered-cluster created successfully, information of the cluster:
    name         = test-registered-cluster
    state        = initial
    cluster id   = c3c277f2fc10f45c1b86473**********
    region id    = cn-zhangjiakou
    node numbers = 0
    vpc id       = vpc-8vb95w2o172**********
    vswitch id   = vsw-8vbv8bxhput**********
  3. After the cluster is initialized, it enters the waiting state. Run the following command to view the cluster state:

    onectl cluster describe --cluster-id ****

    Expected output:

    name  = test-registered-cluster
    state = waiting
    ...
  4. When the cluster is in the waiting state, run the following command to connect the target cluster to the ACK One registered cluster.

    onectl cluster connect --cluster-id **** --kubeconfig ~/.kube/config --restricted true

    Parameter

    Required

    Description

    cluster-id

    Yes

    The ID of the ACK One registered cluster created in Step 2.

    kubeconfig

    No

    The path to the kubeconfig file of the target cluster. If you do not specify this parameter, the configuration file specified by the KUBECONFIG environment variable is used.

    restricted

    No

    Specifies whether to connect to the ACK One registered cluster in restricted mode. For more information, see RBAC permissions for the ack-cluster-agent component of a registered cluster.

    You can also run the following command to view detailed parameter descriptions:

    onectl cluster connect -h
  5. Run the following command to verify that the target cluster is connected:

    onectl cluster describe --cluster-id ****

    Expected output:

    name  = test-registered-cluster
    state = running
    ...

    A state of running indicates that the ACK One registered cluster is successfully connected.