📖docs: improve MaxConcurrentReconciles documentation by mattsu2020 · Pull Request #3521 · kubernetes-sigs/controller-runtime

mattsu2020 · 2026-05-21T13:04:31Z

Summary

This improves the GoDoc for MaxConcurrentReconciles to address issue #1416, which requested better documentation explaining when and how to use this option.

The added documentation explains:

The option controls the number of worker goroutines processing items from the controller's work queue
Different queue items may be reconciled concurrently, but the same item is never processed by multiple workers at the same time
If the same item is added again while being processed, it is marked dirty and requeued after the current reconciliation finishes
For the default reconcile.Request type, the item key is the object's namespace/name
Increasing concurrency can improve throughput but may increase load on the API server and external systems; QPS/Burst settings should be considered
Manager-level (config.Controller.MaxConcurrentReconciles) and GroupKind-level (config.Controller.GroupKindConcurrency) configuration are also available; per-controller values take precedence

Changes

File	Change
`pkg/controller/controller.go`	Detailed doc on `TypedOptions.MaxConcurrentReconciles` (primary documentation)
`pkg/config/controller.go`	Doc on manager-level default with reference to primary doc
`pkg/internal/controller/controller.go`	Internal `Options` and `Controller` structs reference primary doc

Closes #1416

k8s-ci-robot · 2026-05-21T13:04:41Z

Welcome @mattsu2020!

It looks like this is your first PR to kubernetes-sigs/controller-runtime 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/controller-runtime has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2026-05-21T13:04:42Z

Hi @mattsu2020. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

Add detailed Go doc comments for MaxConcurrentReconciles explaining: - The option controls the number of worker goroutines processing items from the controller's work queue - Different queue items may be reconciled concurrently, but the same item is never processed by multiple workers at the same time - If the same item is added again while being processed, it is marked dirty and requeued after the current reconciliation finishes - Increasing concurrency can improve throughput but may increase load on the API server and external systems; QPS/Burst settings should be considered - Manager-level (config.Controller) and GroupKind-level configuration are also available; per-controller values take precedence

mattsu2020 · 2026-06-01T12:07:38Z

Hi @joelanford @varshaprasad96,

Could you please take a look when you have a chance?

This is a docs-only PR for #1416 that improves the GoDoc around MaxConcurrentReconciles.
Since this is my first PR to controller-runtime, it still needs /ok-to-test before CI can run.

Thank you!

alvaroaleman · 2026-06-08T08:26:21Z

+	//
+	// The work queue ensures that the same item is not processed by multiple
+	// workers at the same time. If the same item is added again while it is being
+	// processed, it is marked dirty and requeued after the current reconciliation


Remove the comment about "being marked dirty", that is a) an implemention detail and b) not actually the case when using the priorityqueue, its just called locked there

Thank you
Edit comment

alvaroaleman · 2026-06-08T08:27:33Z

+	// finishes. For the default reconcile.Request type, the item key is the
+	// object's namespace/name.
+	//
+	// Higher concurrency can increase load on the Kubernetes API server and any


I don't find this a useful section, because it depends a lot on what exactly the reconciler does. The bit about QPS/Burst is also not useful, because we default to disable the clientside ratelimiter and rely on APF

Thank you.
I've deleted the relevant part of the comment.

Co-authored-by: Alvaro Aleman <alvaroaleman@users.noreply.github.com>

alvaroaleman

/hold

/assign @sbueringer

k8s-ci-robot · 2026-06-08T12:51:33Z

LGTM label has been added.

Details

Git tree hash: d7844ed6e50e8b9e6d802e7bb072abed46bcaf46

sbueringer · 2026-06-13T06:48:18Z

/ok-to-test

sbueringer · 2026-06-13T06:52:31Z

Thx!

/lgtm
/approve

k8s-ci-robot · 2026-06-13T06:52:42Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: alvaroaleman, mattsu2020, sbueringer

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [alvaroaleman,sbueringer]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

sbueringer · 2026-06-13T07:02:43Z

/hold cancel

mattsu2020 · 2026-06-13T07:19:14Z

thanks

k8s-ci-robot added the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label May 21, 2026

k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label May 21, 2026

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label May 21, 2026

k8s-ci-robot requested review from joelanford and varshaprasad96 May 21, 2026 13:04

k8s-ci-robot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label May 21, 2026

mattsu2020 force-pushed the fix_1416 branch from 13146f1 to 3f54f98 Compare May 21, 2026 13:06

k8s-ci-robot removed the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label May 21, 2026

mattsu2020 changed the title ~~docs: improve MaxConcurrentReconciles documentation~~ 📖docs: improve MaxConcurrentReconciles documentation May 29, 2026

alvaroaleman reviewed Jun 8, 2026

View reviewed changes

mattsu2020 and others added 2 commits June 8, 2026 18:27

Update pkg/controller/controller.go

bb0b4f1

Co-authored-by: Alvaro Aleman <alvaroaleman@users.noreply.github.com>

docs: simplify MaxConcurrentReconciles comment in TypedOptions

449fb20

alvaroaleman reviewed Jun 8, 2026

View reviewed changes

Comment thread pkg/controller/controller.go Outdated

alvaroaleman added the tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges. label Jun 8, 2026

Update pkg/controller/controller.go

c478f9a

Co-authored-by: Alvaro Aleman <alvaroaleman@users.noreply.github.com>

alvaroaleman approved these changes Jun 8, 2026

View reviewed changes

k8s-ci-robot assigned sbueringer Jun 8, 2026

k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jun 8, 2026

k8s-ci-robot assigned alvaroaleman Jun 8, 2026

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jun 8, 2026

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jun 8, 2026

k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Jun 13, 2026

k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jun 13, 2026

k8s-ci-robot merged commit 866050c into kubernetes-sigs:main Jun 13, 2026
8 checks passed

mattsu2020 deleted the fix_1416 branch June 13, 2026 07:19

Conversation

mattsu2020 commented May 21, 2026

Summary

Changes

Uh oh!

k8s-ci-robot commented May 21, 2026

Uh oh!

k8s-ci-robot commented May 21, 2026

Uh oh!

mattsu2020 commented Jun 1, 2026

Uh oh!

Uh oh!

alvaroaleman Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

mattsu2020 Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

alvaroaleman Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

mattsu2020 Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alvaroaleman left a comment

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented Jun 8, 2026

Uh oh!

sbueringer commented Jun 13, 2026

Uh oh!

sbueringer commented Jun 13, 2026

Uh oh!

k8s-ci-robot commented Jun 13, 2026

Uh oh!

sbueringer commented Jun 13, 2026

Uh oh!

Uh oh!

mattsu2020 commented Jun 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants