All Products
Search

This Product

    API Gateway:Dedicated instance clusters

    Document Center

    API Gateway:Dedicated instance clusters

    Last Updated:Jun 08, 2026

    Cluster multiple dedicated instances together to scale beyond the limits of a single instance.

    How it works

    A single dedicated instance has a fixed performance ceiling. When the highest-specification instance cannot meet your traffic demands, add multiple instances to a cluster. The cluster distributes API traffic across all member instances using domain name system (DNS) resolution — each instance independently handles its portion of requests.

    Only instances of the same type and specification, in the same region, can join the same cluster. For specification details, see Dedicated instances.

    image.png

    Figure: Multiple dedicated instances share API traffic through DNS-based load distribution.

    Before you begin

    Review these requirements before creating or modifying a cluster:

    • Minimum specification: Only dedicated instances of api.s2.large.x4 or higher can join a cluster.

    • Cluster limit: A single cluster supports up to 20 instances. To increase this quota, submit a ticket.

    • Matching configuration: All instances in a cluster must share the same specification, version, and type. The first instance added to the cluster sets these values for all subsequent additions.

    • No API groups on additional instances: When adding a second or later instance, the instance must not have existing API groups. (The first instance added may have API groups — they transfer to the cluster.)

    • Egress IP addresses: Adding an instance may introduce new egress IP addresses. Add any new egress IP addresses to your backend service's allowlist to avoid connectivity issues.

    • DNS propagation: When you add or remove an instance, DNS resolution records update accordingly. Allow up to 60 seconds — the time to live (TTL) — for the change to propagate.

    Manage clusters

    Create a dedicated instance cluster

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

    2. Click Create Cluster. In the Create Cluster dialog box, enter a Name and Description, then click Confirm.

    3. Verify that the new cluster appears in the list with a Ready state.

    Add instances to a cluster

    1. In the cluster list, find the target cluster and click Manage Instances in the Actions column.

    2. Click Add Instance and select the instance to add.

      Note

      1. When the cluster is in the Ready state, add exactly one instance. That instance's specification, version, and type become the cluster's baseline configuration.

      2. The first instance may have existing API groups. After you add it, those API groups transfer to and become part of the cluster.

    3. Click Add. The system provisions resources and initializes the cluster using the added instance's configuration. When initialization completes, the cluster transitions to the Running state.

    4. (Optional) Add more instances. Select multiple instances at a time to batch-add them.

      Note

      Every instance you add must match the cluster's baseline configuration. If it does not, the system returns one of the following errors:

      1. The shared or serverless instance cannot be added to the cluster.

      2. The instance that you want to add is of a different version. In this case, submit a ticket to have your instance updated.

      3. The instance that you want to add is of a different specification and cannot be added.

      4. The instance that you want to add is of a different type and cannot be added.

      5. The instance that you want to add has API groups and cannot be added.

      6. The instance that you want to add has different configurations for Inbound IPv6 Traffic, Outbound IPv6 Traffic, or Calls from API Gateway and cannot be added.

      7. The instance that you want to add has different configurations for HTTPS Security Policy, VPC for Access to Dedicated Instance, IPv6 Access Control, IPv4 Access Control, or Custom Private CIDR Block and these configurations will be overwritten by the corresponding cluster configurations after addition.

    Modify cluster configurations

    1. In the cluster list, find the target cluster and click Manage Instances in the Actions column.

    2. Click Modify in the upper-right corner to update the cluster name and description.

    3. Update other settings as needed — for example, HTTPS Security Policy or VPC for Access to Dedicated Instance. Changes apply to all instances in the cluster.

    4. Wait for all changes to propagate across the cluster before making further modifications.

    Remove instances from a cluster

    1. In the cluster list, find the target cluster and click Manage Instances in the Actions column.

    2. In the Dedicated Instances list, select the instances to remove, then click Remove Instance in the upper-right corner.

      Note

      1. While a removal is in progress, you cannot change cluster configurations, add instances, or remove other instances.

      2. If the cluster has an API group, you cannot remove all dedicated instances from it.

    Limits and notes

    1. Only dedicated instances of api.s2.large.x4 or higher specifications can join a cluster.

    2. A single cluster supports up to 20 instances. To increase this limit, submit a ticket.

    3. When creating an API group, specify a dedicated instance cluster as the target instance. API group creation is blocked while the cluster has an ongoing operation: configuration change, instance addition, or instance removal.

    4. API groups from other API Gateway instances can be migrated to a dedicated instance cluster.

    5. If adding an instance introduces new egress IP addresses, add those addresses to your backend service's allowlist.

    6. When you add or remove an instance, DNS resolution records for the cluster's API group domain names are updated. The TTL of these records is 60 seconds.