feat(fluentd): add pluginSortOrder field to control plugin @id sort behavior by sugaf1204 · Pull Request #1927 · fluent/fluent-operator

sugaf1204 · 2026-04-19T00:04:56Z

What this PR does / why we need it:

Adds a pluginSortOrder field to FluentdConfig and ClusterFluentdConfig.

When a CR contains many plugins, lexicographic @id sorting causes the rendered
config order to diverge from the CR definition order. Setting pluginSortOrder: index
enables numeric-aware comparison to maintain definition order.

Default remains lexicographic for backward compatibility.

Which issue(s) this PR fixes:

Fixes #

Does this PR introduced a user-facing change?

Add `pluginSortOrder` field to `FluentdConfig` and `ClusterFluentdConfig`.
Set `pluginSortOrder: index` to enable numeric-aware plugin `@id` sorting,
which maintains definition order when a CR contains many plugins.
Default is `lexicographic` to preserve existing behavior.

Additional documentation, usage docs, etc.:

- [Usage]: docs/best-practice/plugin-grouping.md

Copilot

Pull request overview

This PR fixes Fluentd plugin rendering order in generated configs when a single CR defines 10+ filter/output plugins by sorting plugin @id suffix indexes numerically (avoiding lexicographic mis-order like -10 before -2). It also adds regression fixtures and unit tests to lock in correct ordering for filters and outputs, plus a guard test around input ordering.

Changes:

Update PluginStoreByNameById.Less to compare @id trailing numeric segments numerically.
Add new Fluentd ClusterFilter/ClusterInput/ClusterOutput test fixtures that include 11 plugins (0..10).
Add expected rendered config fixtures + unit tests covering the 10+ plugin ordering regression.

Reviewed changes

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

Show a summary per file

File	Description
apis/fluentd/v1alpha1/plugins/params/model.go	Adds numeric-aware `@id` comparison for plugin child sorting.
apis/fluentd/v1alpha1/tests/tools.go	Introduces CR fixtures with 11 filters/inputs/outputs to reproduce the ordering issue.
apis/fluentd/v1alpha1/tests/helper_test.go	Adds regression tests validating numeric ordering for filters/outputs and a guard for input order.
apis/fluentd/v1alpha1/tests/expected/fluentd-cluster-cfg-output-order-by-index.cfg	New expected config validating output ordering `...-0` through `...-10`.
apis/fluentd/v1alpha1/tests/expected/fluentd-cluster-cfg-input-order-by-index.cfg	New expected config validating input rendering order in a single CR.
apis/fluentd/v1alpha1/tests/expected/fluentd-cluster-cfg-filter-order-by-index.cfg	New expected config validating filter ordering `...-0` through `...-10`.

Copilot · 2026-04-19T00:08:36Z

+		if p1 != p2 {
+			return p1 < p2
+		}
+		return n1 < n2


When ok1 && ok2 and p1 == p2, lessId returns n1 < n2 without a tie-breaker for n1 == n2. If two ids differ only in formatting (e.g., leading zeros like "...-2" vs "...-02"), Less will return false in both directions, letting sort.Sort reorder them non-deterministically. Add a deterministic tie-break (for example, fall back to full id1 < id2 when n1 == n2).

Suggested change

return n1 < n2

if n1 != n2 {

return n1 < n2

}

return id1 < id2

There shouldn't be any issues, as the two IDs have different formats and there should be no case where the numerical values are the same.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

cw-Guo · 2026-04-20T20:25:49Z

Hi @sugaf1204 , thanks for the contributions!. This looks good but it is a breaking change. To make sure smoothly upgrading experience, can you add a gate for this feature?
for example, we can add a argument, so that user can control the sorting behavior, and the default value would be the lexicographically.
@joshuabaird what do you think?

Copilot

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.

Copilot · 2026-04-26T05:56:35Z

 		// WithCfgResources will collect all plugins to generate main config
+		cfgResouces.NumericIdSort = cfg.Spec.PluginSortOrder == "index"
 		var msg string
 		err = gpr.WithCfgResources(cfgRouterLabel, cfgResouces)


The new numeric-aware ordering is only enabled when spec.pluginSortOrder is explicitly set to "index". That keeps the current lexicographic behavior (and the 10+ plugin mis-ordering) for existing CRs and for CRs that omit the field. If the intent/PR messaging is that ordering is fixed by default, consider either defaulting pluginSortOrder to "index" (API defaulting) or updating the user-facing notes to make it clear this is an opt-in behavior change.

Copilot

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.

Copilot · 2026-04-26T06:12:27Z

+              pluginSortOrder:
+                description: |-
+                  PluginSortOrder controls how child plugins within a label section are
+                  ordered by their @id. "lexicographic" (default) preserves the original
+                  string-comparison behaviour. "index" switches to numeric-aware ordering
+                  so that a CR with more than nine plugins renders in definition order
+                  (e.g. plugin-2 before plugin-10).
+                enum:
+                - lexicographic
+                - index
+                type: string


The CRD schema for pluginSortOrder documents a default of "lexicographic", but there is no default: set in the OpenAPI schema. If the intent is to have a CRD default (as implied by the Go type marker), regenerate manifests so the schema includes default: lexicographic; otherwise adjust the description to avoid claiming a CRD default.

Copilot · 2026-04-26T06:12:27Z

+	// string-comparison behaviour. "index" switches to numeric-aware ordering
+	// so that a CR with more than nine plugins renders in definition order
+	// (e.g. plugin-2 before plugin-10).
+	// +kubebuilder:validation:Enum:=lexicographic;index


FluentdConfigSpec.PluginSortOrder is documented as having a default of "lexicographic", but unlike ClusterFluentdConfigSpec it has no +kubebuilder:default marker, so the default isn't visible/expressed in the CRD schema. Consider adding +kubebuilder:default:=lexicographic here as well (and regenerate manifests/docs) to keep the API consistent.

Suggested change

// +kubebuilder:validation:Enum:=lexicographic;index

// +kubebuilder:validation:Enum:=lexicographic;index

// +kubebuilder:default:=lexicographic

Copilot · 2026-04-26T06:12:27Z

+	// PluginSortOrder controls how child plugins within a label section are
+	// ordered by their @id. "lexicographic" (default) preserves the original
+	// string-comparison behaviour. "index" switches to numeric-aware ordering
+	// so that a CR with more than nine plugins renders in definition order
+	// (e.g. plugin-2 before plugin-10).
+	// +kubebuilder:validation:Enum:=lexicographic;index
+	PluginSortOrder string `json:"pluginSortOrder,omitempty"`


The PR description/release note states plugin ordering is fixed for CRs with 10+ plugins, but the implementation keeps lexicographic ordering as the default and only enables numeric ordering when pluginSortOrder: index is set. Either update the PR description/release note to reflect the opt-in behavior, or consider making numeric ordering the default if backward compatibility allows.

updated PR description/release note

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

Pull request overview

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

Copilot · 2026-04-29T07:42:30Z


 However, for filter plugins, if you want a filter chain, the order of filters matters. You need to organize multiple filters into an array as the demo [logging stack](https://github.com/fluent/fluent-operator/blob/master/manifests/logging-stack/filter-kubernetes.yaml) suggests.For more info on various use cases of Fluent Operator Fluentd CRDs, you can refer to [Fluent-Operator-Walkthrough](https://github.com/kubesphere-sigs/fluent-operator-walkthrough#fluent-bit--fluentd-mode).

+For Fluentd configs that select more than nine child plugins in one label section, set `pluginSortOrder: index` on `FluentdConfig` or `ClusterFluentdConfig` to use numeric-aware plugin ordering. The default `lexicographic` order is kept for backward compatibility.


The doc says to set pluginSortOrder: index “on FluentdConfig / ClusterFluentdConfig”, but this field lives under .spec. As written, it’s ambiguous and could be read as a top-level field. Please clarify the path (e.g., .spec.pluginSortOrder: index) so users apply it correctly.

Copilot · 2026-04-29T07:42:31Z

+		expectedCfg := string(getExpectedCfg("./expected/fluentd-cluster-cfg-output-order-by-index.cfg"))
+		g.Expect(strings.TrimRight(expectedCfg, "\n")).To(Equal(config))
+	}


These new tests special-case the expected fixtures by trimming trailing newlines, while the rest of this test file compares fixtures verbatim. To keep expectations consistent (and avoid hiding newline mismatches), consider normalizing this in one place (e.g., update getExpectedCfg to trim the trailing newline, or ensure these new expected/*.cfg fixtures match the existing convention so no per-test trimming is needed).

@id

…ehavior Adds pluginSortOrder field to FluentdConfig and ClusterFluentdConfig. Default is "lexicographic" to preserve existing behavior. Set pluginSortOrder: index to enable numeric-aware @id comparison, which maintains definition order when a CR contains many plugins. Adds regression tests for inputs, filters, and outputs. CRD schema default is set to "lexicographic" in generated manifests. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: sugaf1204 <sugaf1204@icloud.com>

sugaf1204 · 2026-04-29T17:36:59Z

Hi @cw-Guo , thank you for the feedback. I have updated the implementation to maintain the original behavior by default and added a flag to control the sorting behavior.

cw-Guo

LGTM

Copilot

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated no new comments.

cw-Guo · 2026-05-06T05:06:32Z

Thanks @sugaf1204 for your contributions!

Copilot AI review requested due to automatic review settings April 19, 2026 00:04

Copilot started reviewing on behalf of sugaf1204 April 19, 2026 00:05 View session

Copilot AI reviewed Apr 19, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings April 19, 2026 00:25

Copilot started reviewing on behalf of sugaf1204 April 19, 2026 00:25 View session

Copilot AI reviewed Apr 19, 2026

View reviewed changes

sugaf1204 marked this pull request as draft April 19, 2026 08:30

sugaf1204 force-pushed the worktree-order-index branch from 458e9af to f548ad3 Compare April 19, 2026 08:31

sugaf1204 marked this pull request as ready for review April 19, 2026 08:32

Copilot AI review requested due to automatic review settings April 19, 2026 08:32

Copilot started reviewing on behalf of sugaf1204 April 19, 2026 08:32 View session

Copilot AI reviewed Apr 19, 2026

View reviewed changes

sugaf1204 force-pushed the worktree-order-index branch from 3dae5ee to 416a9bf Compare April 19, 2026 08:37

Copilot AI review requested due to automatic review settings April 26, 2026 05:52

sugaf1204 force-pushed the worktree-order-index branch from 416a9bf to 0fdf2f3 Compare April 26, 2026 05:52

Copilot started reviewing on behalf of sugaf1204 April 26, 2026 05:52 View session

Copilot AI reviewed Apr 26, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings April 26, 2026 06:08

Copilot started reviewing on behalf of sugaf1204 April 26, 2026 06:08 View session

Copilot AI reviewed Apr 26, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings April 26, 2026 06:15

Copilot started reviewing on behalf of sugaf1204 April 26, 2026 06:15 View session

Copilot AI reviewed Apr 26, 2026

View reviewed changes

sugaf1204 force-pushed the worktree-order-index branch from 77b8c02 to cf6307b Compare April 26, 2026 07:28

Copilot AI review requested due to automatic review settings April 29, 2026 07:35

sugaf1204 force-pushed the worktree-order-index branch from cf6307b to f938113 Compare April 29, 2026 07:35

Copilot started reviewing on behalf of sugaf1204 April 29, 2026 07:36 View session

sugaf1204 changed the title ~~fix(fluentd): sort plugin @id numerically to preserve CR definition order~~ feat(fluentd): add opt-in numeric plugin sort order for large CRs Apr 29, 2026

Copilot AI reviewed Apr 29, 2026

View reviewed changes

sugaf1204 force-pushed the worktree-order-index branch from f938113 to 1baf828 Compare April 29, 2026 07:58

sugaf1204 force-pushed the worktree-order-index branch from 1baf828 to b4d7a3f Compare April 29, 2026 08:16

sugaf1204 changed the title ~~feat(fluentd): add opt-in numeric plugin sort order for large CRs~~ feat(fluentd): add pluginSortOrder field to control plugin @id sort behavior Apr 29, 2026

cw-Guo self-assigned this May 5, 2026

cw-Guo approved these changes May 6, 2026

View reviewed changes

Merge branch 'master' into worktree-order-index

7c7d9a1

Copilot AI review requested due to automatic review settings May 6, 2026 03:32

Copilot started reviewing on behalf of cw-Guo May 6, 2026 03:32 View session

Copilot AI reviewed May 6, 2026

View reviewed changes

cw-Guo merged commit 52c62b6 into fluent:master May 6, 2026
17 checks passed

This was referenced May 21, 2026

chore(master): release 3.8.0 #1969

Merged

chore: update fluent-operator charts to v4.1.0 (appVersion 3.8.0) fluent/helm-charts#722

Closed

	// +kubebuilder:validation:Enum:=lexicographic;index
	// +kubebuilder:validation:Enum:=lexicographic;index
	// +kubebuilder:default:=lexicographic


		However, for filter plugins, if you want a filter chain, the order of filters matters. You need to organize multiple filters into an array as the demo [logging stack](https://github.com/fluent/fluent-operator/blob/master/manifests/logging-stack/filter-kubernetes.yaml) suggests.For more info on various use cases of Fluent Operator Fluentd CRDs, you can refer to [Fluent-Operator-Walkthrough](https://github.com/kubesphere-sigs/fluent-operator-walkthrough#fluent-bit--fluentd-mode).

		For Fluentd configs that select more than nine child plugins in one label section, set `pluginSortOrder: index` on `FluentdConfig` or `ClusterFluentdConfig` to use numeric-aware plugin ordering. The default `lexicographic` order is kept for backward compatibility.

Conversation

sugaf1204 commented Apr 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does / why we need it:

Which issue(s) this PR fixes:

Does this PR introduced a user-facing change?

Additional documentation, usage docs, etc.:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Apr 19, 2026

Choose a reason for hiding this comment

Uh oh!

sugaf1204 Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

cw-Guo commented Apr 20, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

sugaf1204 Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

sugaf1204 Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

sugaf1204 Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

sugaf1204 Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

sugaf1204 Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 29, 2026

Choose a reason for hiding this comment

sugaf1204 commented Apr 19, 2026 •

edited

Loading