Immutable Infrastructure
  • 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

    Provider and Version BoundaryExternal LoadBalancer ContractValidate an External LoadBalancerSelf-built VIP Contract

    Provider and Version Boundary

    Endpoint capabilities are provider-version specific. An ACP minor version alone does not enable a provider feature.

    ProviderLast verified provider releaseDocumented endpoint modes
    Huawei DCSv1.0.22External 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 vSpherev1.0.17External 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 MetalNo version boundary appliesInternal Self-built VIP and External LoadBalancer. There is no earlier provider release to preserve, so the Bare Metal guide documents both modes without a legacy-version workflow.
    Huawei Cloud StackProvider-managed HCS ELBUse the endpoint fields and ELB workflow in Creating Clusters on Huawei Cloud Stack.

    For DCS, type: internal requires DCS Provider v1.0.22+ and ACP v4.4+. DCS Provider v1.0.21 and earlier support only the external LoadBalancer path. Do not use ACP version alone to infer provider capability.

    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, use the authoritative pages instead of copying the complete port matrix into this documentation:

    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 DCS Provider v1.0.22+ and 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 Creating Clusters on Huawei DCS. For Bare Metal manifests, see Creating Clusters on Bare Metal. For vSphere, see Control Plane Endpoint Modes.