Import Standard Kubernetes Cluster

Use this procedure to import an existing standard Kubernetes cluster, such as a cluster deployed with kubeadm, as a third-party cluster.

Terminology

TermDescription
Provider-managed Kubernetes serviceA Kubernetes service where the provider owns the control plane nodes and control plane components. Users usually cannot log in to or directly maintain the control plane nodes.
Self-managed Kubernetes clusterA Kubernetes cluster where the cluster owner maintains the control plane nodes and cluster components.

Prerequisites

Notes

By default, the platform monitors NIC traffic matching eth.*|en.*|wl.*|ww.*. If your NIC uses a different naming convention, update the configuration after integration following Collect Network Data from Custom Named Network Cards.

Obtain Registry Address

  • To use the registry deployed by the platform during global cluster installation, run the following on a global control plane node:

    if ! REGISTRY=$(kubectl get cm -n kube-public global-info -o jsonpath='{.data.registryAddress}'); then
        echo "Failed to read the registry address. Do not continue with an empty address." >&2
        exit 1
    fi
    if [ "$REGISTRY" = "cpaas-registry.cpaas-system" ]; then
        if ! REGISTRY=$(kubectl get registry.platform.alauda.io cpaas-registry -n cpaas-system -o jsonpath='{.spec.endpoints[0]}'); then
            echo "Failed to read the registry endpoint. Do not continue with an empty address or cpaas-registry.cpaas-system." >&2
            exit 1
        fi
        if [ -z "$REGISTRY" ]; then
            echo "Failed to resolve a real registry endpoint. Do not continue with an empty address or cpaas-registry.cpaas-system." >&2
            exit 1
        fi
    elif [ "$(kubectl get productbase -o jsonpath='{.items[].spec.registry.preferPlatformURL}')" != 'false' ]; then
        REGISTRY=$(kubectl get cm -n kube-public global-info -o jsonpath='{.data.platformURL}' | awk -F // '{print $NF}')
    fi
    if [ -z "$REGISTRY" ]; then
        echo "Failed to resolve a registry address. Do not continue with an empty address." >&2
        exit 1
    fi
    echo "Registry address: $REGISTRY"

In mirror mode, cpaas-registry.cpaas-system is a logical name used by global nodes. The command reads the first registry endpoint and prints that host[:port]. Imported nodes pull images from that address. The logical name is resolved even when the platform URL is preferred. If the command exits with an error, stop. Do not continue with an empty address or the logical name. If the cluster is already imported, compare the printed address with the image address of the Sentry Pod and use the Pod image address when they differ.

  • To use an external registry, set REGISTRY manually:

    REGISTRY=<external-registry-address>  # e.g., registry.example.cn:60080 or 192.168.134.43
    echo "Registry address: $REGISTRY"

Check if Extra Registry Config is Needed

  1. Run the following to check if the registry supports HTTPS with a trusted CA certificate:

    REGISTRY=<registry-address-from-previous-step>
    
    if curl -s -o /dev/null --retry 3 --retry-delay 5 -- "https://${REGISTRY}/v2/"; then
        echo 'Pass: Registry uses a trusted CA certificate. No extra config needed.'
    else
        echo 'Fail: Registry does not support HTTPS or uses an untrusted certificate. Follow "Trust Insecure Registry".'
    fi
  2. If check fails, see How to trust an insecure registry?

Get Cluster Info

See How to fetch cluster information?.

Integrate Cluster

  1. In the left navigation, go to Cluster Management > Clusters.

  2. Click Import Cluster.

  3. Configure parameters as below:

    ParameterDescription
    RegistryRegistry storing required platform component images. Options: Platform Default (configured during global setup), Private Registry (requires address, port, username, password).
    Cluster InfoCan be entered manually or parsed from a KubeConfig file. Required fields: Cluster Address, CA Certificate (Base64 decoded if entered manually), and Authentication (token or client certificate with cluster-admin rights).
  4. Click Check Connectivity. The platform verifies network access and auto-detects cluster type.

  5. If successful, click Import to complete.

    Progress can be viewed via the execution progress dialog (status.conditions). Once integrated, the cluster appears as healthy in the list.

Network Configuration

Ensure connectivity between the global cluster and the imported cluster.

Post-import Configuration

If you need the platform to collect audit data from an imported standard Kubernetes cluster, configure Kubernetes API server audit logging on the cluster after import. See How to configure audit collection for imported standard Kubernetes clusters?.

FAQ

Why is the "Add Node" button disabled?

Adding nodes through the platform UI is not supported for imported standard Kubernetes clusters. Add nodes directly in the target cluster or through the cluster provider.

Which certificates are supported?

  1. Kubernetes Certificates: Only API Server certificates can be viewed; other certificates are unsupported and will not auto-rotate.
  2. Platform Component Certificates: Viewable and auto-rotatable.

Which features are unsupported?

  • Provider-managed Kubernetes services: Audit logs are not available.
  • Provider-managed Kubernetes services: ETCD, Scheduler, and Controller Manager monitoring are not supported. Only API Server metrics are available.
  • All clusters: Certificates other than API Server are not supported.

How to fix Containerd runtime causing distributed storage deployment failures?

When using Containerd, distributed storage deployment fails unless you adjust Containerd settings on all nodes:

  1. Edit /etc/systemd/system/containerd.service, set LimitNOFILE=1048576.
  2. Run systemctl daemon-reload.
  3. Restart Containerd: systemctl restart containerd.
  4. On control plane nodes, restart distributed storage pods:
    kubectl delete pod --all -n rook-ceph