Informer pools

[csviri]

Summary

Introduces an informer pool so that informers backing InformerEventSources (and the internal controller event source) can be shared across controllers instead of each controller/event source always creating its own SharedIndexInformer. This reduces the number of watch connections opened against the API server and memory overhead in operators where multiple controllers (or multiple dynamically-registered event sources) watch the same secondary resource type (e.g. ConfigMap, Secret).

This is marked @Experimental: the pooling behavior itself is production ready, but the configuration API may still evolve in a non-backwards-compatible way.

What's new

InformerPool abstraction (processing/event/source/informer/pool)

• InformerPool — interface for getting/releasing informers, keyed by an InformerClassifier, plus reference counting via numberOfInformersForResource.
• InformerClassifier — identifies "equivalent" informer requests: API server URL, label/field/shard selectors, namespace, resource type (or GVK for generic resources), and item store. informerListLimit and indexers are intentionally excluded from identity (a warning is logged if an existing informer is reused with a different list limit; indexers can be added independently to a shared informer as long as names don't collide).
• AbstractInformerPool — shared logic for building the underlying SharedIndexInformer from a classifier (selectors, field selectors, item store, list limit, exception/stopped handlers) and starting it with the configured cacheSyncTimeout.
• DefaultInformerPool (new default) — reference-counted, sharing pool: creates an informer on first request for a given classifier and reuses it for subsequent requests; only stops it once the last user releases it.
• AlwaysNewInformerPool — opt-out pool that creates a dedicated informer per event source, preserving pre-pooling behavior.

Configuration

• ConfigurationService.informerPool() — new (non-default) method; implementations must return the same instance on every call so controllers using the same ConfigurationService share the pool. AbstractConfigurationService caches a DefaultInformerPool lazily (synchronized to avoid creating more than one instance under concurrent first access).
• ConfigurationServiceOverrider.withInformerPool(InformerPool) — lets users opt into AlwaysNewInformerPool (or a custom implementation) to disable/customize sharing.

Integration

• InformerManager and InformerWrapper were reworked to go through the pool instead of creating/starting/stopping the SharedIndexInformer directly:
  • InformerManager now builds an InformerClassifier per namespace and calls informerPool.getInformer(...) / releaseInformer(...) instead of constructing the informer from the Fabric8 client itself.
  • Starting/stopping is now delegated to the pool: getInformer only registers/reference-counts, InformerPool#start blocks (idempotently) until cache sync, and releaseInformer decrements the reference count, stopping the informer only when it drops to zero. The event handler is always removed from the returned informer, even when it stays running for other users.
  • InformerWrapper no longer owns lifecycle (start/stop removed); it now just exposes the informer/classifier and cache-facing behavior.
• ControllerEventSource and ManagedInformerEventSource updated to go through the same pooled path.
• Dynamic registration/deregistration of event sources correctly reuses/releases pooled informers, replaying existing cache state to newly added handlers when attaching to an already-running shared informer.

Docs

Added a new "Sharing Informers Between Controllers (Informer Pool)" section to docs/content/en/docs/documentation/eventing.md describing sharing semantics, what counts toward informer identity, and how to select/override the pooling strategy.

Tests

• Unit tests for AlwaysNewInformerPool, DefaultInformerPool, and InformerClassifier (equality/identity semantics).
• New integration tests under informerpool:
  • basic — two reconcilers sharing an informer for the same secondary resource type, parameterized to also run against AlwaysNewInformerPool for regression coverage.
  • deregister — verifies informer lifecycle when an event source is dynamically deregistered while shared.
  • dynamic — verifies dynamically-registered/static shared informers, including replay of existing cache state to a newly attached handler.
• Existing tests (ControllerTest, EventSourceManagerTest, ReconciliationDispatcherTest, ControllerEventSourceTest, InformerEventSourceTest, MockKubernetesClient, StandaloneDependentResourceIT, WorkflowMultipleActivationIT) updated for the new construction/wiring paths.

[Copilot]

Pull request overview

Introduces initial scaffolding for “event source pooling” (starting with informers) under processing.event.source.pool, likely to enable sharing/reuse of informers across components/controllers.

Changes:

• Added EventSourcePool interface and AbstractEventSourcePool base type.
• Added InformerClassifier record to key pooled informers by selector/namespace/resource type.
• Added initial (currently incomplete) InformerPool implementation and a minor whitespace cleanup in InformerManager.

Reviewed changes

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

Show a summary per file

File	Description
operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/pool/InformerPool.java	Adds a new pool for SharedIndexInformer<?> instances (currently stubbed/incomplete).
operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/pool/InformerClassifier.java	Adds a classifier record intended as the cache key for pooled informers.
operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/pool/EventSourcePool.java	Introduces a generic pool interface for event sources.
operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/pool/AbstractEventSourcePool.java	Adds a base class placeholder for pool implementations.
operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/InformerManager.java	Removes an extraneous whitespace line in createEventSource.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (3)

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/InformerWrapper.java:109

• informerInfo() currently returns "InformerWrapper [informerInfo]", which looks like a leftover debug label and makes toString()/logs confusing when diagnosing informer issues. It should format consistently without the stray "informerInfo" token.

  private String informerInfo() {
    return "InformerWrapper [informerInfo" + informer.getApiTypeClass().getSimpleName() + "]";
  }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/pool/AlwaysNewInformerPool.java:47

• getInformer() uses informers.containsKey(key) followed by informers.put(key, informer). With a ConcurrentHashMap this check-then-act sequence is not atomic: two concurrent callers can both observe the key as absent, create two informers, and one put will overwrite the other (leaking an informer) without throwing the intended OperatorException. Use putIfAbsent (or compute) to make the registration atomic and stop the newly-created informer on collision.

    var key = new ClassifierWithName(controllerName, name, classifier);
    if (informers.containsKey(key)) {
      throw new OperatorException(
          "Informer already registered for controller: "
              + controllerName

operator-framework/src/test/java/io/javaoperatorsdk/operator/dependent/standalonedependent/StandaloneDependentResourceIT.java:136

• This test-only ConfigurationService implementation returns null from informerPool(). Even if currently “never accessed”, it’s brittle and can turn into an unexpected NPE if the cloner implementation (or any other default method used here) starts consulting informerPool(). Since the test already has a running LocallyRunOperatorExtension, it can avoid the ad-hoc ConfigurationService entirely and reuse the operator’s real ConfigurationService/resource cloner instead.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (2)

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/pool/AlwaysNewInformerPool.java:47

• getInformer uses containsKey followed by put, which is not atomic even with ConcurrentHashMap. Under concurrent calls for the same (controllerName, event source name, classifier) key, this can still create (and potentially leak) multiple informers and bypass the intended "already registered" exception. Use putIfAbsent (or computeIfAbsent) so the check+insert is atomic, and stop the extra informer if another thread won the race.

    var key = new ClassifierWithName(controllerName, name, classifier);
    if (informers.containsKey(key)) {
      throw new OperatorException(
          "Informer already registered for controller: "
              + controllerName

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/InformerWrapper.java:109

• informerInfo() currently returns "InformerWrapper [informerInfo" + ..., which looks like an accidental leftover token and makes toString() output confusing.

  private String informerInfo() {
    return "InformerWrapper [informerInfo" + informer.getApiTypeClass().getSimpleName() + "]";
  }

[csviri]

@SamBarker @k-wall I saw that you added explicit support in kroxy operator to share informers, in case you are interested and have the bandwidth PTAL if this makes sense for you; this should solve that problem out of the box. thank you!

[k-wall]

@SamBarker @k-wall I saw that you added explicit support in kroxy operator to share informers, in case you are interested and have the bandwidth PTAL if this makes sense for you; this should solve that problem out of the box. thank you!

Thank you for the heads up. We'll take a look and feed back.

[xstefank]

approving, I have only opinioned enhancements. Feel free to comment on each and we can either do it in this PR or as followups.

[xstefank]

maybe we could also have pool.releaseInformer(informer)

[csviri]

I was thinking about this a lot that time, I would rather keep the contract simpler with just the current method; I marked it @experimental ( well @PublicEvolving might be a better annotation) so we can enhance this in the future.