Composite cluster configuration (proto)

extensions.clusters.composite.v3.ClusterConfig

[extensions.clusters.composite.v3.ClusterConfig proto]

Configuration for the composite cluster. See the architecture overview for more information. This cluster type enables retry-aware cluster selection, allowing different retry attempts to automatically target different upstream clusters. Unlike the standard aggregate cluster which uses health-based selection, the composite cluster uses the retry attempt count to deterministically select which sub-cluster to route to.

When retry attempts exceed the number of configured clusters, requests will fail with no host available.

Example configuration:

name: composite_cluster
connect_timeout: 0.25s
lb_policy: CLUSTER_PROVIDED
cluster_type:
  name: envoy.clusters.composite
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.clusters.composite.v3.ClusterConfig
    clusters:
    - name: primary_cluster
    - name: secondary_cluster
    - name: fallback_cluster

This extension has the qualified name envoy.clusters.composite

Note

This extension is not hardened and should only be used in deployments where both the downstream and upstream are trusted.

Tip

This extension extends and can be used with the following extension category:

envoy.clusters

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.extensions.clusters.composite.v3.ClusterConfig

{
  "clusters": []
}

clusters: (repeated extensions.clusters.composite.v3.ClusterConfig.ClusterEntry, REQUIRED) List of clusters to use for request routing. The first cluster is used for the initial request (attempt 1), the second cluster for the first retry (attempt 2), and so on. Must contain at least one cluster. When retry attempts exceed the number of configured clusters, requests will fail with no host available.

extensions.clusters.composite.v3.ClusterConfig.ClusterEntry

[extensions.clusters.composite.v3.ClusterConfig.ClusterEntry proto]

Configuration for an individual cluster entry.

{
  "name": ...
}

name: (string, REQUIRED) Name of the cluster. This cluster must be defined elsewhere in the configuration.