docs: improve MaxConcurrentReconciles documentation

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

Author: mattsu2020

pkg/config/controller.go

@@ -44,7 +44,14 @@ type Controller struct {
 	// e.g. ReplicaSet in apps group (regardless of version) would be `ReplicaSet.apps`.
 	GroupKindConcurrency map[string]int
 
-	// MaxConcurrentReconciles is the maximum number of concurrent Reconciles which can be run. Defaults to 1.
+	// MaxConcurrentReconciles is the maximum number of concurrent reconciliations which can be run.
+	// Defaults to 1.
+	//
+	// This value is used as a default for controllers that do not specify their own value.
+	// Per-controller options take precedence over this setting.
+	//
+	// For more details on how concurrency works, see the MaxConcurrentReconciles
+	// field in pkg/controller.TypedOptions.
 	MaxConcurrentReconciles int
 
 	// CacheSyncTimeout refers to the time limit set to wait for syncing caches.

pkg/controller/controller.go

@@ -45,7 +45,31 @@ type TypedOptions[request comparable] struct {
 	// Defaults to false if Controller.SkipNameValidation setting from the Manager is also unset.
 	SkipNameValidation *bool
 
-	// MaxConcurrentReconciles is the maximum number of concurrent Reconciles which can be run. Defaults to 1.
+	// MaxConcurrentReconciles is the maximum number of concurrent reconciliations
+	// that can be run. Defaults to 1.
+	//
+	// This value controls the number of worker goroutines that process items from
+	// the controller's work queue. Increasing it allows different queue items to be
+	// reconciled in parallel, which can improve throughput when a controller manages
+	// many objects or when reconciliation involves slow operations such as external
+	// API calls.
+	//
+	// 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
+	// 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
+	// external systems used by the reconciler. When increasing this value, consider
+	// whether client-side QPS/Burst settings and external rate limits also need to
+	// be adjusted.
+	//
+	// This option can also be configured at the manager level via
+	// config.Controller.MaxConcurrentReconciles or per GroupKind via
+	// config.Controller.GroupKindConcurrency (applied when using the builder
+	// utilities and no per-controller value is set). Per-controller values
+	// take precedence.
 	MaxConcurrentReconciles int
 
 	// CacheSyncTimeout refers to the time limit set to wait for syncing caches.

pkg/internal/controller/controller.go

@@ -58,6 +58,7 @@ type Options[request comparable] struct {
 	NewQueue func(controllerName string, rateLimiter workqueue.TypedRateLimiter[request]) workqueue.TypedRateLimitingInterface[request]
 
 	// MaxConcurrentReconciles is the maximum number of concurrent Reconciles which can be run. Defaults to 1.
+	// See controller.TypedOptions.MaxConcurrentReconciles for full documentation.
 	MaxConcurrentReconciles int
 
 	// CacheSyncTimeout refers to the time limit set on waiting for cache to sync
@@ -96,7 +97,8 @@ type Controller[request comparable] struct {
 	// Name is used to uniquely identify a Controller in tracing, logging and monitoring.  Name is required.
 	Name string
 
-	// MaxConcurrentReconciles is the maximum number of concurrent Reconciles which can be run. Defaults to 1.
+	// MaxConcurrentReconciles is the number of worker goroutines spawned to process work queue items.
+	// See controller.TypedOptions.MaxConcurrentReconciles for full documentation.
 	MaxConcurrentReconciles int
 
 	// Reconciler is a function that can be called at any time with the Name / Namespace of an object and