Version v5.7.0 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.
Configurations
The Java Operator SDK (JOSDK) provides abstractions that work great out of the box. However, we recognize that default behavior isn’t always suitable for every use case. Numerous configuration options help you tailor the framework to your specific needs.
Configuration options operate at several levels:
- Operator-level using
ConfigurationService - Reconciler-level using
ControllerConfiguration - DependentResource-level using the
DependentResourceConfiguratorinterface - EventSource-level where some event sources (like
InformerEventSource) need fine-tuning to identify which events trigger the associated reconciler
Operator-Level Configuration
Configuration that impacts the entire operator is performed via the ConfigurationService class. ConfigurationService is an abstract class with different implementations based on which framework flavor you use (e.g., Quarkus Operator SDK replaces the default implementation). Configurations initialize with sensible defaults but can be changed during initialization.
For example, to disable CRD validation on startup and configure leader election:
Operator operator = new Operator( override -> override
.checkingCRDAndValidateLocalModel(false)
.withLeaderElectionConfiguration(new LeaderElectionConfiguration("bar", "barNS")));
Virtual Threads
Reconciliation is mostly about blocking: talking to the Kubernetes API server or to external systems. Virtual threads make such blocking calls much cheaper than platform threads, and the framework can be switched over to them with a single flag:
Operator operator = new Operator(override -> override.withUseVirtualThreads(true));
When enabled, reconciliations, dependent resource workflows and the framework’s internal housekeeping (starting the informers, for example) all run on virtual threads.
Enabling virtual threads does not remove the concurrency limits, parallelism is configured
exactly as before: withConcurrentReconciliationThreads(int) still caps how many reconciliations
run at the same time and withConcurrentWorkflowExecutorThreads(int) how many dependent resources
of a workflow are processed concurrently. Only the threads backing those limits change. Since
virtual threads are cheap, these limits can usually be raised significantly compared to what is
reasonable with platform threads.
Things to keep in mind:
- Virtual threads are only supported on Java 25 or later. Before Java 25 a virtual thread pins
its carrier thread while it is inside a
synchronizedblock, which can starve the carrier pool and even deadlock the operator on startup. JEP 491, delivered in Java 25, removed that pinning. This is checked at runtime: on an older JVM, including the ones where virtual threads exist (Java 21 to 24), a warning is logged and platform threads are used instead, so the same configuration works on any Java version the operator runs on. - The scheduled tasks (the polls of the polling event sources, which each create an executor of
their own unless one is provided, and the retried and rescheduled reconciliations) run on virtual
threads too. The JDK has no scheduled executor backed by virtual threads, so the default ones keep
a single platform thread for the timing only and run each task they fire on a virtual thread. The
number of those tasks running at the same time is not limited, so
withConcurrentRetryAndRescheduleThreads(int)only applies to platform threads. - Virtual threads are always daemon threads, so unlike the threads of the platform thread pools they
don’t keep the JVM running: if the
mainmethod of your application returns after starting the operator and nothing else keeps the JVM alive, callOperator.keepAlive(), see Keeping the JVM Alive. - A custom
ExecutorServiceprovided throughwithExecutorService(...)orwithWorkflowExecutorService(...)is always used as is, the flag has no effect on it. The same goes forwithRetryAndRescheduleExecutorService(...). Note however that overriding the flag, orwithConcurrentRetryAndRescheduleThreads(int), of a configuration that provides its own retry and reschedule executor replaces that executor with the default one, so provide it again withwithRetryAndRescheduleExecutorService(...)in that case. - The Kubernetes client the framework creates when none is provided also switches its internal
task executor (used to dispatch informer events to their handlers and to deliver watch events)
to virtual threads. A client you provide through
withKubernetesClient(...)is used as is: to get the same behavior, configure it yourself, e.g. withnew KubernetesClientBuilder().withTaskExecutor(Executors.newVirtualThreadPerTaskExecutor())(the client doesn’t shut down an executor passed that way, usewithTaskExecutorSupplier(...)if it should be shut down when the client is closed). Either way, the blocking calls your reconciler makes through the client work well on virtual threads without any client-side change.
Reconciler-Level Configuration
While reconcilers are typically configured using the @ControllerConfiguration annotation, you can also override configuration at runtime when registering the reconciler with the operator. You can either:
- Pass a completely new
ControllerConfigurationinstance - Override specific aspects using a
ControllerConfigurationOverriderConsumer(preferred)
Operator operator;
Reconciler reconciler;
...
operator.register(reconciler, configOverrider ->
configOverrider.withFinalizer("my-nifty-operator/finalizer").withLabelSelector("foo=bar"));
Dynamically Changing Target Namespaces
A controller can be configured to watch a specific set of namespaces in addition of the
namespace in which it is currently deployed or the whole cluster. The initial set can be provided
programmatically, via the @Informer annotation, or read from an external configuration source (see
the namespaces property). The framework supports
dynamically changing the list of these namespaces while the operator is running.
When a reconciler is registered, an instance of
RegisteredController
is returned, providing access to the methods allowing users to change watched namespaces as the
operator is running.
A typical scenario would probably involve extracting the list of target namespaces from a
ConfigMap or some other input but this part is out of the scope of the framework since this is
use-case specific. For example, reacting to changes to a ConfigMap would probably involve
registering an associated Informer and then calling the changeNamespaces method on
RegisteredController.
public static void main(String[] args) {
KubernetesClient client = new DefaultKubernetesClient();
Operator operator = new Operator(client);
RegisteredController registeredController = operator.register(new WebPageReconciler(client));
operator.installShutdownHook();
operator.start();
// call registeredController further while operator is running
}
If watched namespaces change for a controller, it might be desirable to propagate these changes to
InformerEventSources associated with the controller. In order to express this,
InformerEventSource implementations interested in following such changes need to be
configured appropriately so that the followControllerNamespaceChanges method returns true:
@ControllerConfiguration
public class MyReconciler implements Reconciler<TestCustomResource> {
@Override
public Map<String, EventSource> prepareEventSources(
EventSourceContext<ChangeNamespaceTestCustomResource> context) {
InformerEventSource<ConfigMap, TestCustomResource> configMapES =
new InformerEventSource<>(InformerEventSourceConfiguration.from(ConfigMap.class, TestCustomResource.class)
.withNamespacesInheritedFromController(context)
.build());
return EventSourceUtils.nameEventSources(configMapES);
}
}
As seen in the above code snippet, the informer will have the initial namespaces inherited from controller, but also will adjust the target namespaces if it changes for the controller.
See also the integration test for this feature.
Keeping the JVM Alive
The operator normally keeps the JVM running through the non-daemon threads of its thread pools. If
nothing else does, for example because all the threads of the operator are daemon threads as it is
the case with virtual threads, the JVM exits as soon as the main method returns after starting
the operator. Call Operator.keepAlive() to have a non-daemon thread keep the JVM running until the
operator is stopped:
public static void main(String[] args) {
Operator operator = new Operator();
operator.register(new MyReconciler());
operator.installShutdownHook();
operator.start();
operator.keepAlive();
}
DependentResource-level configuration
It is possible to define custom annotations to configure custom DependentResource implementations. In order to provide
such a configuration mechanism for your own DependentResource implementations, they must be annotated with the
@Configured annotation. This annotation defines 3 fields that tie everything together:
by, which specifies which annotation class will be used to configure your dependents,with, which specifies the class holding the configuration object for your dependents andconverter, which specifies theConfigurationConverterimplementation in charge of converting the annotation specified by thebyfield into objects of the class specified by thewithfield.
ConfigurationConverter instances implement a single configFrom method, which will receive, as expected, the
annotation instance annotating the dependent resource instance to be configured, but it can also extract information
from the DependentResourceSpec instance associated with the DependentResource class so that metadata from it can be
used in the configuration, as well as the parent ControllerConfiguration, if needed. The role of
ConfigurationConverter implementations is to extract the annotation information, augment it with metadata from the
DependentResourceSpec and the configuration from the parent controller on which the dependent is defined, to finally
create the configuration object that the DependentResource instances will use.
However, one last element is required to finish the configuration process: the target DependentResource class must
implement the ConfiguredDependentResource interface, parameterized with the annotation class defined by the
@Configured annotation by field. This interface is called by the framework to inject the configuration at the
appropriate time and retrieve the configuration, if it’s available.
For example, KubernetesDependentResource, a core implementation that the framework provides, can be configured via the
@KubernetesDependent annotation. This set up is configured as follows:
@Configured(
by = KubernetesDependent.class,
with = KubernetesDependentResourceConfig.class,
converter = KubernetesDependentConverter.class)
public abstract class KubernetesDependentResource<R extends HasMetadata, P extends HasMetadata>
extends AbstractEventSourceHolderDependentResource<R, P, InformerEventSource<R, P>>
implements ConfiguredDependentResource<KubernetesDependentResourceConfig<R>> {
// code omitted
}
The @Configured annotation specifies that KubernetesDependentResource instances can be configured by using the
@KubernetesDependent annotation, which gets converted into a KubernetesDependentResourceConfig object by a
KubernetesDependentConverter. That configuration object is then injected by the framework in the
KubernetesDependentResource instance, after it’s been created, because the class implements the
ConfiguredDependentResource interface, properly parameterized.
For more information on how to use this feature, we recommend looking at how this mechanism is implemented for
KubernetesDependentResource in the core framework, SchemaDependentResource in the samples or CustomAnnotationDep
in the BaseConfigurationServiceTest test class.
Loading Configuration from External Sources
JOSDK ships a ConfigLoader that bridges any key-value configuration source to the operator and
controller configuration APIs. This lets you drive operator behaviour from environment variables,
system properties, YAML files, or any config library (MicroProfile Config, SmallRye Config,
Spring Environment, etc.) without writing glue code by hand.
Architecture
The system is built around two thin abstractions:
ConfigProvider— a single-method interface that resolves a typed value for a dot-separated key:public interface ConfigProvider { <T> Optional<T> getValue(String key, Class<T> type); }ConfigLoader— reads all known JOSDK keys from aConfigProviderand returnsConsumer<ConfigurationServiceOverrider>/Consumer<ControllerConfigurationOverrider<R>>values that you pass directly to theOperatorconstructor oroperator.register().
The default ConfigLoader (no-arg constructor) stacks environment variables over system
properties: environment variables win, system properties are the fallback.
// uses env vars + system properties out of the box
Operator operator = new Operator(ConfigLoader.getDefault().applyConfigs());
Built-in Providers
| Provider | Source | Key mapping |
|---|---|---|
EnvVarConfigProvider | System.getenv() | dots and hyphens → underscores, upper-cased (josdk.check-crd → JOSDK_CHECK_CRD) |
PropertiesConfigProvider | java.util.Properties or .properties file | key used as-is; use PropertiesConfigProvider.systemProperties() to read Java system properties |
YamlConfigProvider | YAML file | dot-separated key traverses nested mappings |
AggregatePriorityListConfigProvider | ordered list of providers | first non-empty result wins |
All string-based providers convert values to the target type automatically.
Supported types: String, Boolean, Integer, Long, Double, Duration (ISO-8601, e.g. PT30S).
Plugging in Any Config Library
ConfigProvider is a single-method interface, so adapting any config library takes only a few
lines. As an example, here is an adapter for
SmallRye Config:
public class SmallRyeConfigProvider implements ConfigProvider {
private final SmallRyeConfig config;
public SmallRyeConfigProvider(SmallRyeConfig config) {
this.config = config;
}
@Override
public <T> Optional<T> getValue(String key, Class<T> type) {
return config.getOptionalValue(key, type);
}
}
The same pattern applies to MicroProfile Config, Spring Environment, Apache Commons
Configuration, or any other library that can look up typed values by string key.
Wiring Everything Together
Pass the ConfigLoader results when constructing the operator and registering reconcilers:
// Load operator-wide config from a YAML file via SmallRye Config
URL configUrl = MyOperator.class.getResource("/application.yaml");
var configLoader = new ConfigLoader(
new SmallRyeConfigProvider(
new SmallRyeConfigBuilder()
.withSources(new YamlConfigSource(configUrl))
.build()));
// applyConfigs() → Consumer<ConfigurationServiceOverrider>
Operator operator = new Operator(configLoader.applyConfigs());
// applyControllerConfigs(name) → Consumer<ControllerConfigurationOverrider<R>>
operator.register(new MyReconciler(),
configLoader.applyControllerConfigs(MyReconciler.NAME));
Only keys that are actually present in the source are applied; everything else retains its programmatic or annotation-based default.
You can also compose multiple sources with explicit priority using
AggregatePriorityListConfigProvider:
var configLoader = new ConfigLoader(
new AggregatePriorityListConfigProvider(List.of(
new EnvVarConfigProvider(), // highest priority
PropertiesConfigProvider.systemProperties(),
new YamlConfigProvider(Path.of("config/operator.yaml")) // lowest priority
)));
Operator-Level Configuration Keys
All operator-level keys are prefixed with josdk..
General
| Key | Type | Description |
|---|---|---|
josdk.check-crd | Boolean | Validate CRDs against local model on startup |
josdk.close-client-on-stop | Boolean | Close the Kubernetes client when the operator stops |
josdk.use-virtual-threads | Boolean | Run the framework’s concurrent work on virtual threads (only supported on Java 25+, platform threads are used on older versions) |
josdk.use-ssa-to-patch-primary-resource | Boolean | Use Server-Side Apply to patch the primary resource |
josdk.clone-secondary-resources-when-getting-from-cache | Boolean | Clone secondary resources on cache reads |
Reconciliation
| Key | Type | Description |
|---|---|---|
josdk.reconciliation.concurrent-threads | Integer | Thread pool size for reconciliation |
josdk.reconciliation.termination-timeout | Duration | How long to wait for in-flight reconciliations to finish on shutdown |
Workflow
| Key | Type | Description |
|---|---|---|
josdk.workflow.executor-threads | Integer | Thread pool size for workflow execution |
Retry and Reschedule
| Key | Type | Description |
|---|---|---|
josdk.retry-and-reschedule.concurrent-threads | Integer | Thread pool size for triggering retried and rescheduled reconciliations |
Informer
| Key | Type | Description |
|---|---|---|
josdk.informer.cache-sync-timeout | Duration | Timeout for the initial informer cache sync |
josdk.informer.stop-on-error-during-startup | Boolean | Stop the operator if an informer fails to start |
Dependent Resources
| Key | Type | Description |
|---|---|---|
josdk.dependent-resources.ssa-based-create-update-match | Boolean | Use SSA-based matching for dependent resource create/update |
Events
See Recording Kubernetes Events for how events are recorded. The key below configures where events about cluster scoped resources go.
| Key | Type | Description |
|---|---|---|
josdk.events.cluster-scoped-namespace | String | Namespace to record events about cluster scoped resources in (defaults to default); the API server only accepts default and kube-system |
Recording events requires the operator’s service account to be allowed get, create and patch on
events in the core ("") API group. All three are used: an event that does not exist yet is
created, and an event that does is a repeat of one already recorded, which is patched to count the
new occurrence instead of being recorded a second time. The
generic Helm chart grants all three. If you write your own RBAC and a permission is
missing, recording fails silently as far as reconciliation is concerned by default: the failure is
swallowed so that it cannot break a reconciliation, and only shows up as a warning in the operator
log. Kubernetes treats events as best effort, supplemental data, so this is usually what you want.
Where an event that is not recorded must not go unnoticed, configure a recorder that propagates the
failure to the reconciler instead, so that the reconciliation fails and is retried like any other
failed one:
KubernetesClient client = new KubernetesClientBuilder().build();
Operator operator = new Operator(override -> override
.withKubernetesClient(client)
.withEventRecorder(DefaultEventRecorder.builder(new DefaultEventSink(client))
.failOnError(true)
.build()));
Every failure propagates then, transient ones included, such as the conflict two replicas run into when they count the same occurrence of an event at the same time.
Note that events live in a namespace of their own choosing, which is the namespace of the object
they are about, and for cluster scoped objects the namespace configured above. A namespaced Role
therefore has to grant the permission in every namespace events are recorded in — including
default, or whatever josdk.events.cluster-scoped-namespace is set to, if the operator reconciles
cluster scoped resources. A ClusterRole covers all of them at once.
The API server only accepts events about cluster scoped objects in the default and kube-system
namespaces, so those are the only values josdk.events.cluster-scoped-namespace can usefully be set
to. In particular, the namespace the operator itself runs in is rejected, and the event dropped with
a warning in the operator log (or, with failOnError(true), the reconciliation failed).
Leader Election
Leader election is activated when at least one josdk.leader-election.* key is present.
josdk.leader-election.lease-name is required when any other leader-election key is set.
Setting josdk.leader-election.enabled=false suppresses leader election even if other keys are
present.
| Key | Type | Description |
|---|---|---|
josdk.leader-election.enabled | Boolean | Explicitly enable (true) or disable (false) leader election |
josdk.leader-election.lease-name | String | Required. Name of the Kubernetes Lease object used for leader election |
josdk.leader-election.lease-namespace | String | Namespace for the Lease object (defaults to the operator’s namespace) |
josdk.leader-election.identity | String | Unique identity for this instance; defaults to the pod name |
josdk.leader-election.lease-duration | Duration | How long a lease is valid (default PT15S) |
josdk.leader-election.renew-deadline | Duration | How long the leader tries to renew before giving up (default PT10S) |
josdk.leader-election.retry-period | Duration | How often a candidate polls while waiting to become leader (default PT2S) |
Controller-Level Configuration Keys
All controller-level keys are prefixed with josdk.controller.<controller-name>., where
<controller-name> is the value returned by the reconciler’s name (typically set via
@ControllerConfiguration(name = "...")).
General
| Key | Type | Description |
|---|---|---|
josdk.controller.<name>.finalizer | String | Finalizer string added to managed resources |
josdk.controller.<name>.generation-aware | Boolean | Skip reconciliation when the resource generation has not changed |
josdk.controller.<name>.label-selector | String | Label selector to filter watched resources |
josdk.controller.<name>.shard-selector | String | Shard selector to filter watched resources for sharding across operator replicas |
josdk.controller.<name>.max-reconciliation-interval | Duration | Maximum interval between reconciliations even without events |
josdk.controller.<name>.field-manager | String | Field manager name used for SSA operations |
josdk.controller.<name>.trigger-reconciler-on-all-events | Boolean | Trigger reconciliation on every event, not only meaningful changes |
josdk.controller.<name>.default-filters | Boolean | When false, JOSDK’s internal update filters (generation-aware, finalizer-needed, marked-for-deletion) are not applied and the user’s onUpdateFilter becomes the sole filter |
Watched Namespaces
| Key | Type | Description |
|---|---|---|
josdk.controller.<name>.namespaces | String | Comma-separated list of namespaces the controller watches |
Entries are trimmed and blank ones are ignored, so ns1, ns2 and ns1,ns2 are equivalent. Instead
of a list of namespaces, the value can also be one of the two special values below, which have to be
used on their own — combining them with a namespace name is an error:
| Value | Meaning |
|---|---|
JOSDK_ALL_NAMESPACES | Watch the whole cluster (the default) |
JOSDK_WATCH_CURRENT | Watch only the namespace the operator is deployed in |
Setting this property is equivalent to calling settingNamespaces on
ControllerConfigurationOverrider and therefore replaces, rather than extends, the namespaces
configured via the @Informer annotation. The set of watched namespaces can still be changed while
the operator is running, see
Dynamically Changing Target Namespaces.
josdk.controller.mycontroller.namespaces=team-a,team-b
Informer
| Key | Type | Description |
|---|---|---|
josdk.controller.<name>.informer.label-selector | String | Label selector for the primary resource informer (alias for label-selector) |
josdk.controller.<name>.informer.shard-selector | String | Shard selector for the primary resource informer (alias for shard-selector) |
josdk.controller.<name>.informer.list-limit | Long | Page size for paginated informer list requests; omit for no pagination |
josdk.controller.<name>.informer.comparable-resource-versions | Boolean | Whether the resource versions of the primary resource can be treated as integers and thus compared |
josdk.controller.<name>.informer.without-namespace-index | Boolean | Removes the namespace index the informer maintains; defaults to false. See Removing the Namespace Index |
Retry
If any retry.* key is present, a GenericRetry is configured starting from the
default limited exponential retry.
Only explicitly set keys override the defaults.
| Key | Type | Description |
|---|---|---|
josdk.controller.<name>.retry.max-attempts | Integer | Maximum number of retry attempts |
josdk.controller.<name>.retry.initial-interval | Long (ms) | Initial backoff interval in milliseconds |
josdk.controller.<name>.retry.interval-multiplier | Double | Exponential backoff multiplier |
josdk.controller.<name>.retry.max-interval | Long (ms) | Maximum backoff interval in milliseconds |
Rate Limiter
The rate limiter is only activated when rate-limiter.limit-for-period is present and has a
positive value. rate-limiter.refresh-period is optional and falls back to the default of 10 s.
| Key | Type | Description |
|---|---|---|
josdk.controller.<name>.rate-limiter.limit-for-period | Integer | Maximum number of reconciliations allowed per refresh period. Must be positive to activate the limiter |
josdk.controller.<name>.rate-limiter.refresh-period | Duration | Window over which the limit is counted (default PT10S) |
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.