cluster specifier: support new attempt aware cluster specifier by wbpcode · Pull Request #46640 · envoyproxy/envoy

wbpcode · 2026-08-11T12:36:03Z

Commit Message: cluster specifier: support new attempt aware cluster specifier
Additional Description:
Risk Level:
Testing:
Docs Changes:
Release Notes:
Platform Specific Features:
[Optional Runtime guard:]
[Optional Fixes #Issue]
[Optional Fixes commit #PR or SHA]
[Optional Deprecated:]
[Optional API Considerations:]

Signed-off-by: wbpcode <wbphub@gmail.com>

repokitteh-read-only · 2026-08-11T12:36:17Z

CC @envoyproxy/api-shepherds: Your approval is needed for changes made to (api/envoy/|docs/root/api-docs/).
envoyproxy/api-shepherds assignee is @adisuissa
CC @envoyproxy/api-watchers: FYI only for changes made to (api/envoy/|docs/root/api-docs/).

🐱

Caused by: #46640 was opened by wbpcode.

see: more, trace.

wbpcode · 2026-08-11T12:37:36Z

+  //   envoy.my_filter:
+  //     priority_groups:
+  //     - name: remote
+  //     - name: local


The metadata self is extendable and it should be easy to support clusters there if we want per-request level fallback order and traffic distribution.

For example, the default order and configuration:

priority_groups: - name: local - name: a weight: 20 - name: b weight: 80 - name: remote clusters: - name: c weight: 20 - name: d weight: 80

the metadata could be:

envoy.my_filter: priority_groups: - name: remote clusters: - name: c weight: 80 - name: d weight: 20 - name: local

Then, the order will be overridden. And for the specific request, the group remote's clusters traffic distribution also will be overridden, but the group local, it's will use the default distribution.

Signed-off-by: wbpcode <wbphub@gmail.com>

Copilot

Pull request overview

This PR introduces a new router cluster specifier plugin, envoy.router.cluster_specifier_plugin.priority_group, which selects a priority group based on the request attempt count and then selects a cluster within the group via weighted selection. It integrates the extension into Envoy’s build/metadata systems, adds the v3 API proto, and provides docs + tests.

Changes:

Added the priority-group cluster specifier plugin implementation with optional per-request overrides via dynamic metadata and optional stable random selection via header or route hash policy.
Added the v3 API proto and wired it into API build targets and router retry documentation.
Added extension registration/build integration, user docs, changelog entry, and a comprehensive unit test suite.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`source/extensions/router/cluster_specifiers/priority_group/priority_group_cluster_specifier.h`	Declares the priority-group cluster specifier plugin and metadata parsing entry type.
`source/extensions/router/cluster_specifiers/priority_group/priority_group_cluster_specifier.cc`	Implements attempt-aware group selection, weighted cluster selection, metadata overrides, and refresh-on-retry behavior.
`source/extensions/router/cluster_specifiers/priority_group/config.h`	Declares the factory config for the new extension.
`source/extensions/router/cluster_specifiers/priority_group/config.cc`	Implements factory creation/validation and registers the extension.
`source/extensions/router/cluster_specifiers/priority_group/BUILD`	Adds Bazel targets for the new extension library and config.
`source/extensions/extensions_build_config.bzl`	Registers the extension in the build configuration map.
`source/extensions/extensions_metadata.yaml`	Adds extension metadata (category/status/type URL).
`api/envoy/extensions/router/cluster_specifiers/priority_group/v3/priority_group.proto`	Adds the public v3 API for the new cluster specifier.
`api/envoy/extensions/router/cluster_specifiers/priority_group/v3/BUILD`	Adds the API proto Bazel package definition.
`api/BUILD`	Wires the new API package into the main API proto library deps.
`api/versioning/BUILD`	Wires the new API package into versioning proto deps.
`api/envoy/config/route/v3/route_components.proto`	Updates retry policy docs to include priority-group cluster specifier support for refresh-on-retry.
`docs/root/configuration/http/cluster_specifier/priority_group.rst`	Adds user-facing documentation and an example configuration.
`docs/root/configuration/http/cluster_specifier/cluster_specifier.rst`	Adds the new page to the cluster specifier docs index.
`test/extensions/router/cluster_specifiers/priority_group/priority_group_cluster_specifier_test.cc`	Adds unit tests covering attempt selection, metadata overrides, random-value specifiers, and validation.
`test/extensions/router/cluster_specifiers/priority_group/BUILD`	Adds Bazel test target for the new unit test.
`CODEOWNERS`	Adds owners for the new extension directory.
`changelogs/current/new_features/router__priority-group-cluster-specifier.rst`	Adds a release note for the new feature.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: code <wbphub@gmail.com>

adisuissa

Thanks!
Here's a first-pass on the API

adisuissa · 2026-08-14T13:27:32Z

+// <envoy_v3_api_msg_extensions.router.cluster_specifiers.priority_group.v3.PriorityGroup>`.
+message ClusterWeight {
+  // Name of the upstream cluster.
+  string name = 1 [(validate.rules).string = {min_len: 1}];


s/name/cluster_name/

adisuissa · 2026-08-14T13:31:09Z

+// exceeds the number of the available groups, the selection wraps around to the beginning of the
+// list.
+//
+// This plugin supports refreshing the target cluster of the returned route entry, so it could be


The description says 'could be used', but I wonder if it should be 'must be used'. What are the cases where 'refresh_cluster_on_retry' should not be set? (consider clarifying this either here or in a the doc)

When only single priority group is there, then refresh_cluster_on_retry could be unset. Let's me make clarify it clearly.

adisuissa · 2026-08-14T13:34:41Z

+//     - name: remote_primary
+//       weight: 100
+//
+// With the configuration above, the initial attempt will be routed to ``local_primary`` or


From a design point-of-view, wouldn't it be better to use WeightedCluster?
This way even the first attempt request will be routed using the already provided WeightedCluster mechanism. This should avoid adding features in both the original WeightedCluster and this one.

I guess you means should we reuse the WeightedCluster API as a group? The reason is the WeightedCluster is over complex for our requirements and lots of unnecessary features (like typed_per_filter_configs, request headers to add and so on, these features now should be covered by our upstream HTTP filter rather than be put in the cluster specifier).

adisuissa · 2026-08-14T13:36:24Z

+  repeated PriorityGroup priority_groups = 1 [(validate.rules).repeated = {min_items: 1}];
+
+  // Optional dynamic metadata key that is used to override the priority groups on a per-request
+  // basis. If this is configured and the referenced dynamic metadata value is a non-empty list,


Could the matched list change between retries? For example on the first attempt the metadata selector returns a list containing 3 elements, but on the first retry the matched metadata has only 1 element?

Yeah. Although not suggested, but yeah. we allow that be updated after every retry so we could use dynamic metadata to customize every attempt

adisuissa · 2026-08-14T13:40:15Z

+  // is used instead.
+  type.metadata.v3.MetadataKey group_override_metadata = 2;
+
+  // The source of the random value that is used to select the target cluster of the selected


Isn't selecting the cluster in a weighted-cluster related to a specific group (and not to all the groups)? If so, why isn't this part of PriorityGroup?

We didn't expect different random value at different retries. A single random value is evaluated once but be used for every attempt (at every PriorityGroup).
So, we put it out of PriorityGroup as shared configuration. If we put it to the PriorityGroup, we need to repeat the same configuration at multiple groups.

cluster specifier: support new attempt aware cluster specifier

5b93c2a

Signed-off-by: wbpcode <wbphub@gmail.com>

wbpcode marked this pull request as draft August 11, 2026 12:36

repokitteh-read-only Bot added the api label Aug 11, 2026

repokitteh-read-only Bot assigned adisuissa Aug 11, 2026

wbpcode commented Aug 11, 2026

View reviewed changes

wbpcode added 2 commits August 12, 2026 13:20

update

1dbcb95

Signed-off-by: wbpcode <wbphub@gmail.com>

fix format/api

83e3463

Signed-off-by: wbpcode <wbphub@gmail.com>

wbpcode marked this pull request as ready for review August 14, 2026 05:08

wbpcode assigned htuch Aug 14, 2026

wbpcode requested a lite review from Copilot August 14, 2026 05:09

Copilot started reviewing on behalf of wbpcode August 14, 2026 05:09 View session

wbpcode marked this pull request as draft August 14, 2026 05:12

Copilot AI reviewed Aug 14, 2026

View reviewed changes

Comment thread source/extensions/router/cluster_specifiers/priority_group/priority_group_cluster_specifier.h

Comment thread api/envoy/extensions/router/cluster_specifiers/priority_group/v3/priority_group.proto Outdated

Apply suggestions from code review

f6a4683

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: code <wbphub@gmail.com>

wbpcode marked this pull request as ready for review August 14, 2026 09:30

adisuissa reviewed Aug 14, 2026

View reviewed changes

Uh oh!

Conversation

wbpcode commented Aug 11, 2026

Uh oh!

repokitteh-read-only Bot commented Aug 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

adisuissa left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wbpcode Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

wbpcode Aug 14, 2026 •

edited

Loading