All Products
Search

This Product

    Container Service for Kubernetes:Overview of the ACK One ALB multi-cluster gateway

    Document Center

    Container Service for Kubernetes:Overview of the ACK One ALB multi-cluster gateway

    Last Updated:Mar 26, 2026

    ALB multi-cluster gateways extend ALB Ingress to span multiple clusters managed by Distributed Cloud Container Platform for Kubernetes (ACK One). A single Application Load Balancer (ALB) instance acts as the unified entry point, distributing traffic to backend Services across all associated clusters. In most cases, ALB multi-cluster gateways can be used in the same manner as the single-cluster mode of ALB Ingress, except for several differences.

    Why use multi-cluster gateways

    Running a single ALB instance across multiple clusters provides the following capabilities beyond a single-cluster ALB Ingress deployment:

    • Fault isolation: Traffic is distributed across multiple clusters, so the impact of a single cluster failure is isolated to that cluster.

    • Unified traffic management: Manage routing rules, listeners, and load balancing in one place rather than maintaining separate Ingress configurations per cluster.

    • Consistent ingress: Apply the same ALB features — auto scaling, fully hosted operation, and O&M-free management — across all clusters in your Fleet instance.

    How it works

    image

    The architecture separates control plane and data plane responsibilities:

    • Control plane — ALB Ingress controller: Watches the API server for changes to Ingress resources and updates the ALB instance configuration based on routing rules. The controller manages the ALB instance but does not distribute traffic.

    • Data plane — ALB instance: Receives and distributes incoming traffic to backend Services across all associated clusters, based on the rules configured by the controller.

    The following components work together to define and route traffic:

    • AlbConfig: A CustomResourceDefinition (CRD) created by the ALB Ingress controller that defines the ALB instance configuration. Each AlbConfig maps to exactly one ALB instance. In multi-cluster mode, the alb.ingress.kubernetes.io/remote-clusters annotation on the AlbConfig specifies which clusters the ALB instance serves.

    • IngressClass: Identifies which Ingress controller handles a given Ingress resource, allowing multiple controllers to coexist in the same cluster.

    • Ingress: Defines external traffic routing rules and access control rules. The ALB Ingress controller monitors Ingress changes and updates the ALB instance accordingly.

    • Service: Provides a stable virtual IP address and port for a group of pods. The ALB instance routes traffic to Services without requiring awareness of individual pod changes.

    Limitations

    Multi-cluster mode supports most ALB Ingress features with one exception: traffic splitting by weight and canary release cannot be used at the same time in multi-cluster mode.

    Feature Single-cluster mode Multi-cluster mode
    Traffic splitting by weight + canary release simultaneously Supported Not supported

    For the full list of supported annotations, see Annotations supported by ALB Ingresses.

    Configure an AlbConfig

    Create an AlbConfig with the alb.ingress.kubernetes.io/remote-clusters annotation to associate clusters with the ALB instance.

    apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: ackone-gateway-demo
  annotations:
    # Specify the cluster IDs associated with this ALB multi-cluster gateway.
    alb.ingress.kubernetes.io/remote-clusters: ${cluster1},${cluster2}
spec:
  config:
    name: one-alb-demo
    addressType: Internet
    addressAllocatedMode: Fixed
    zoneMappings:
    - vSwitchId: ${vsw-id1}
    - vSwitchId: ${vsw-id2}
  listeners:
  - port: 8001
    protocol: HTTP

    Replace the following placeholders with actual values:

    Placeholder Description
    ${cluster1},${cluster2} Cluster IDs associated with your Fleet instance
    ${vsw-id1}, ${vsw-id2} vSwitch IDs in the zones where the ALB instance is deployed

    The following table describes the key parameters:

    Parameter Required Description
    metadata.name Yes Name of the AlbConfig.
    metadata.annotations: alb.ingress.kubernetes.io/remote-clusters Yes Comma-separated list of cluster IDs to add to the ALB multi-cluster gateway. The clusters must already be associated with the Fleet instance.
    spec.config.name No Name of the ALB instance.
    spec.config.addressType No Network type of the ALB instance. Valid values: Internet (default) — the ALB instance is accessible over the internet and requires an associated elastic IP address (EIP); Intranet — the ALB instance is accessible only within the VPC. When using Internet, you are charged instance fees and bandwidth or data transfer fees for the associated EIPs. For pricing details, see Pay-as-you-go.
    spec.config.zoneMappings Yes vSwitch IDs for the zones where the ALB instance is deployed. The vSwitches must be in ALB-supported zones and in the same VPC as the clusters. If the region supports two or more zones, specify vSwitches in at least two zones for high availability. For supported regions and zones, see Regions and zones. For instructions on creating a vSwitch, see Create and manage a vSwitch.
    spec.listeners No Listener port and protocol. The example above configures an HTTP listener on port 8001. A listener defines how the ALB instance receives traffic. Include a listener in the AlbConfig; otherwise, create one manually before using ALB Ingresses.

    For the full list of AlbConfig fields, see ALB Ingress GlobalConfiguration dictionary. For configuration examples, see Configure ALB instances and listeners.

    What's next