Alauda Container Platform
  • English

    • Plan the Control Plane Endpoint

    Every cluster needs a stable endpoint for the Kubernetes API. Select the endpoint mode before you create the cluster, and keep the address stable after kubeadm initializes the control plane.

    TOC

    Endpoint Modes by ProviderExternal LoadBalancer ContractValidate an External LoadBalancerSelf-built VIP Contract

    Endpoint Modes by Provider

    The endpoint modes available in this release depend on the provider.

    ProviderEndpoint modes
    Huawei DCSExternal LoadBalancer, or type: internal Self-built VIP when paired with ACP v4.4+. A single control-plane node can use its own IP only for development or PoC.
    VMware vSphereExternal LoadBalancer, or an internal Self-built VIP when paired with ACP v4.4+, which deploys Alive (keepalived and IPVS) on the control-plane nodes.
    Bare MetalInternal Self-built VIP and External LoadBalancer.
    Huawei Cloud StackProvider-managed HCS ELB. Use the endpoint fields and ELB workflow in Create a Cluster on Huawei Cloud Stack.

    For DCS, type: internal requires ACP v4.4+. Plan it before cluster creation. Existing clusters that use an external LoadBalancer keep it unless you have a tested migration plan.

    For vSphere, type: internal requires vSphere Provider v1.0.17+ and ACP v4.4+, and it is a creation-time choice: only a cluster created that way can use it, and a cluster whose provider was upgraded from an earlier release keeps its external LoadBalancer. It also requires the alive cluster plugin to be present and deployable on the global cluster, because the provider installs Alive through a ModuleInfo rather than shipping it itself. Verify all of these before you plan the mode; see Control Plane Endpoint Modes.

    External LoadBalancer Contract

    Provision and validate the load balancer before you apply the Cluster API resources.

    RequirementContract
    ListenerUse Layer 4 TCP forwarding with TLS passthrough. The Kubernetes API server, not the load balancer, terminates TLS.
    FrontendUse one stable VIP (an IP address) and TCP port 6443. Reserve the address before cluster creation.
    BackendsAdd every control-plane node IP on TCP port 6443. Do not add worker nodes.
    Health checkPrefer an HTTPS check to https://<control-plane-node-ip>:6443/healthz and require HTTP 200. If the device supports only TCP checks, document that the check proves port reachability but not API-server health.
    Backend ownershipThe load balancer owner must update backend membership when control-plane nodes are added, replaced, or removed. The DCS and vSphere providers do not manage external load balancer backends.
    Bootstrap reachabilityThe bootstrap node or current management cluster must reach the frontend endpoint while Cluster API creates the control plane.
    Node reachabilityAll control-plane nodes must reach the endpoint. Workload-cluster endpoints must also be reachable from the global cluster.
    Name and certificateDo not put a DNS name (FQDN) in front of the cluster endpoint — cluster access by domain is not supported. The API server certificate is issued by the cluster's own CA, so a customer-issued certificate cannot be served on the endpoint, and a domain without that certificate defeats its usual purpose.

    For ACP port requirements, see the following pages:

    WARNING

    Do not change the control plane endpoint after the cluster is initialized as a routine load-balancer edit. The endpoint is embedded in API server certificates, kubeconfigs, and management-cluster connections. Changing it requires a planned certificate and connectivity migration.

    Validate an External LoadBalancer

    Before cluster creation, confirm that the listener exists and that the bootstrap or management environment can open the frontend port:

    nc -vz <control-plane-endpoint> 6443

    After at least one API server is running, verify the preferred health check from a network location that represents the load balancer:

    curl -kfsS https://<control-plane-node-ip>:6443/healthz

    The expected response is ok with HTTP status 200.

    Self-built VIP Contract

    For Huawei DCS, use this contract only with ACP v4.4+. On VMware vSphere it applies to provider v1.0.17 and later. For Bare Metal, follow the provider-specific guide.

    • Reserve an unused IPv4 address in the same Layer-2 network as the control-plane interface that will hold the VIP.
    • Use a VRID that is unique in that Layer-2 domain.
    • Allow VRRP traffic and gratuitous ARP updates between the control-plane nodes and the surrounding network.
    • Use at least three control-plane nodes for high availability.
    • Ensure the node image and the supported alive package provide the required VIP runtime and IPVS configuration.
    • Use an IP address, not a domain name, for the Self-built VIP.
    • Let the provider and Alive reconcile the VIP and backend membership when control-plane nodes are replaced. Do not maintain a second manual backend list for the same VIP.

    On VMware vSphere the following additional rules apply:

    • The VIP must be IPv4. IPv6 and dual-stack endpoints are not accepted.
    • vrid must be between 1 and 255. The range is enforced by the provider's admission webhook rather than by the CRD schema, so an out-of-range value is rejected at apply time and not by kubectl --dry-run=client.
    • The VIP must not equal any slot address (network.primary.ip or network.additional[].ip) declared in the cluster's VSphereMachineConfigPool objects. It must also fall outside every external IPAM pool range; the provider cannot read those pools and will not detect that conflict.
    • spec.controlPlaneLoadBalancer is written when the cluster is created or never. An absent field already means an external LoadBalancer, so it cannot be filled in later, and a field that was written cannot be edited or cleared. Correcting a mistake requires rebuilding the cluster.
    • On multi-NIC nodes, set interface explicitly. Auto-detection matches the node's primary IP, and a wrong choice cannot be patched afterwards.
    • VSphereCluster.status.conditions[SelfBuiltLoadBalancerReady] reports the VIP chain only. It does not gate VSphereCluster.status.ready, so the infrastructure cluster can report ready while the VIP is still converging.

    For DCS manifests and verification, see Create a Cluster on Huawei DCS. For Bare Metal manifests, see Create a Cluster on Bare Metal. For vSphere, see Control Plane Endpoint Modes.