All Products
Search
Document Center

Container Service for Kubernetes:Create ACK One registered clusters

Last Updated:May 27, 2025

ACK One registered clusters allow you to connect Kubernetes clusters deployed in data centers or on third-party clouds to the Container Service for Kubernetes (ACK) console for centralized management. This topic describes how to create an ACK One registered cluster and register a Kubernetes cluster from your data center.

Important

Before you read this topic, we recommend that you read Overview of registered clusters to learn the concepts and scenarios about ACK One registered clusters.

Prerequisites

The cluster registration proxy provides a public endpoint and an internal endpoint. For more information about how to enable Internet access for the cluster API server by using an elastic IP address (EIP), see Control public access to the API server of a cluster.

You must register external clusters in the Container Service for Kubernetes (ACK) console by using the internal endpoint in the following scenarios:

Make sure that the external cluster can access the endpoint of the cluster registration proxy through port 5533. For more information, see Functions and features.

Other features, such as cluster management, security management, logs, and monitoring and alerting, do not have requirements on internal network connectivity. However, you must make sure that the external cluster can access the Internet.

Procedure

Create an ACK One registered cluster and register an external cluster by using the console

Create an ACK One registered cluster

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

  2. Move the pointer over All Resources at the top of the page and select the resource group you want to use.

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

  4. Click the ACK One Registered Cluster tab and configure the cluster parameters.

    Parameter

    Description

    Cluster Name

    The custom name of the cluster.

    Region

    The region of the cluster. The closer the selected region is to the user and the deployed resources, the lower the network latency and the faster the access speed.

    IPv6 Dual-stack

    This feature is in public preview. To use it, submit an application in the Quota Center console.

    If you enable IPv4/IPv6 dual-stack, a dual-stack cluster is created.

    Important
    • Only clusters that run Kubernetes 1.22 and later support this feature.

    • IPv4 addresses are used for communication between worker nodes and the control plane.

    • If you use the shared ENI mode of Terway, the ECS instance type must support IPv6 addresses. To add ECS instances of the specified type to the cluster, the number of IPv4 addresses supported by the ECS instance type must be the same as the number of IPv6 addresses. For more information about ECS instance types, see Overview of instance families.

    • The VPC used by the cluster must support IPv4/IPv6 dual-stack.

    • To use elastic Remote Direct Memory Access (eRDMA) in a cluster, you must disable IPv4/IPv6 dual stack.

    VPC

    Configure the VPC of the cluster. You can specify a zone to automatically create a VPC. You can also select an existing VPC in the VPC list.

    vSwitch

    Select an existing vSwitch from the vSwitch list or click Create vSwitch to create a vSwitch. The control plane and the default node pool use the vSwitch that you select. We recommend that you select multiple vSwitches in different zones to ensure high availability.

    Security Group

    When VPC is set to Select Existing VPC, you can select the Select Existing Security Group option.

    You can select Create Basic Security Group, Create Advanced Security Group, or Select Existing Security Group.

    • By default, automatically created security groups allow all outbound traffic. When you modify the security group for business purposes, make sure that traffic destined for 100.64.0.0/10 is allowed. This CIDR block is used to access other Alibaba Cloud services to pull images and query basic ECS information.

    • If you select an existing security group, the system does not automatically configure security group rules. This may cause errors when you access the nodes in the cluster. You must manually configure security group rules. For more information, see Configure security groups for clusters.

    Access to API Server

    Create a pay-as-you-go internal-facing Classic Load Balancer (CLB) instance for the API server to serve as the internal endpoint of the API server in the cluster. The API server provides various HTTP REST interfaces for managing resource objects (such as pods and Services), including create, read, update, delete, and watch operations.

    You can select or clear Expose API server with EIP. The API server provides multiple HTTP-based RESTful APIs, which can be used to create, delete, modify, query, and monitor resources such as pods and Services.

    • If you select this check box, an elastic IP address (EIP) is associated with the internal-facing CLB instance used to expose the API server of the cluster. This way, you can access the API server of the cluster over the Internet.

    • If you clear this check box, no EIP is created. You can use a kubeconfig file to connect to the cluster only from within the VPC and then manage the cluster.

    Important
    • If you delete the default CLB instance, you cannot access the API server.

    • After binding an EIP to a CLB instance, the API server can receive requests from the public network. However, resources within the cluster cannot access the public network. To allow resources within the cluster to access the public network to pull public images, select the Configure SNAT check box for the VPC.

    • Starting from December 1, 2024, an instance fee will be charged for newly created CLB instances. For more information, see CLB billing adjustments.

    Associate EIP

    Specify whether to associate an elastic IP address (EIP) with the cluster. If you select this check box, an EIP is automatically created and associated with the cluster.

    Note

    If the cluster is connected to Alibaba Cloud over the Internet, you must select this option. You do not need to select this option if the cluster is connected to Alibaba Cloud over an Express Connect circuit.

    Deletion Protection

    We recommend that you enable deletion protection in the console or by using API to prevent clusters from being accidentally released.

    Resource Group

    The resource group to which the cluster belongs. Each resource can belong to only one resource group. You can regard a resource group as a project, an application, or an organization based on your business scenarios.

    Labels

    Add a label to the cluster. Labels are used to identify cloud resources. A label is a key-value pair.

    Terms Of Service

    Before you create a cluster, you must read and agree to the Alibaba Cloud International Website Product Terms of Service, Service Level Agreement, and the product-specific terms that you have selected (if applicable).

  5. After you complete the configuration, click Create Cluster. After the cluster is created, you can view the cluster in the cluster list.

    image

Register an external cluster with the 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 Public Network or Internal Network based on your requirements, and then click Copy on the right side.image

  3. Copy the connection information to a file in the external cluster and run the kubectl command to register the external cluster with the new cluster.

    For example, you can create a file named agent.yaml, copy the connection information to the agent.yaml file, and then run the kubectl apply -f agent.yaml command in the external cluster.

  4. Run the following command in the external cluster to query the status of the agent:

    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 cluster is registered, you can see that the cluster is in the Running status on the Clusters page of the Container Service for Kubernetes (ACK) console.

Result

On the Clusters page, find the 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 kubeconfig to connect to the cluster and deploy applications in the cluster. For more information, see Obtain the kubeconfig file of a cluster and use kubectl to connect to the cluster.

Create an ACK One registered cluster and register an external cluster by using onectl

  1. Install and configure onectl. For more information, see Use onectl to manage registered clusters.

  2. You can use onectl to create an ACK One registered cluster by using one of the following methods:

    Important

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

    • Non-interactive mode: Run the following command to create a registered cluster.

      onectl cluster create --region **** --vpc **** --vswitch ****
    • Interactive mode: Run the following command to create a registered cluster.

      onectl cluster create -i

    You can run the following command to view the detailed information of the parameters:

    onectl cluster create -h

    After the cluster is created, ACK will initialize the registered cluster. At this point, the status of the registered cluster is initial. Expected output:

    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 initialization is complete, the status of the registered cluster changes to waiting. Run the following command to query the status of the cluster:

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

    Expected output:

    name  = test-registered-cluster
    state = waiting
    ...
  4. After the status of the registered cluster changes to waiting, run the following command to connect the external 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 the preceding Step 2.

    kubeconfig

    No

    The path of the kubeconfig file of the external cluster. If no path is specified, the kubeconfig file specified in 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 required by the ack-cluster-agent component in a registered cluster.

    You can run the following command to view the detailed information of the parameters:

    onectl cluster connect -h
  5. Run the following command to check whether the external cluster is connected to the registered cluster:

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

    Expected output:

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

    If the cluster is in the running status, the external cluster is connected to the ACK One registered cluster.