Consistent naming scheme and semantics for enabled/active configuration properties

[yrodiere]

Description

Following discussions on the mailing list, we've recently tried to use consistent conventions for active/enabled configuration properties in the datasource and Hibernate extensions.

The target behavior is as follows:

• quarkus.hibernate-orm.enabled=false (extension level) will disable the Hibernate extension at build time: it will be almost as if the extension was not in the class path, it won't do anything except declare its presence so that it can be displayed on app startup.
• quarkus.hibernate-orm[."persistence-unit-name"].active=false (persistence unit level) will activate/deactivate a persistence unit at runtime: if inactive, the SessionFactory does not started on app startup and SessionFactory/Session/... beans cannot be accessed at runtime.
• (and similarly for quarkus.hibernate-envers and (quarkus.hibernate-search-*`)
• quarkus.datasource[."datasource-name"].active (datasource level) will activate/deactivate a datasource at runtime: if inactive, the connection pool does not gets started on app startup and the Datasource bean cannot be accessed at runtime.

Worth noting that we're refining that behavior in #41810/#41929 so that startup will fail (with a detailed, actionable message) if any user bean gets injected with "inactive" beans. See #36666 (comment) for the motivation; in short it's about failing fast.

There are other extensions also exposing root "enabled"/"active" properties in their configuration, and many are following the same naming scheme and semantics (though they don't all offer the .active feature):

List of configuration properties that are following the same naming and semantics as datasource/Hibernate

• quarkus.management.enabled: Enables / Disables the usage of a separate interface/port to expose the management endpoints. If sets to true, the management endpoints will be exposed to a different HTTP server. This avoids exposing the management endpoints on a publicly available server.
• quarkus.oauth2.enabled: Determine if the OAuth2 extension is enabled. Enabled by default if you include the elytron-security-oauth2 dependency, so this would be used to disable it.
• quarkus.flyway.enabled: Whether Flyway is enabled during the build.
• quarkus.info.enabled: Whether the info endpoint will be enabled
• quarkus.jacoco.enabled: Whether or not the jacoco extension is enabled.
• quarkus.micrometer.enabled: Micrometer metrics support.
• quarkus.oidc.enabled: If the OIDC extension is enabled.
• quarkus.oidc-client.enabled: If the OIDC client extension is enabled.
• quarkus.banner.enabled: Whether the banner will be displayed
• quarkus.config-tracking.enabled: Whether configuration dumping is enabled
• quarkus.console.enabled: If test results and status should be displayed in the console.
• quarkus.devservices.enabled: Global flag that can be used to disable all Dev Services. If this is set to false then Dev Services will not be used.
• quarkus.observability.enabled: If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present.
• quarkus.scheduler.enabled: If schedulers are enabled.
• quarkus.webauthn.enabled: If the WebAuthn extension is enabled.
• quarkus.smallrye-jwt.enabled: The MP-JWT configuration object
• quarkus.virtual-threads.enabled: A flag to explicitly disabled virtual threads, even if the JVM support them. In this case, methods annotated with @RunOnVirtualThread are executed on the worker thread pool.

However, others have taken a different route.

Some follow a slightly different naming scheme:

• quarkus.health.extensions.enabled: Whether extensions published health check should be enabled.

Some use an enabled root configuration property to disable the extension at runtime:

• quarkus.cache.enabled: disables the extension at runtime (expected: at build time)
• quarkus.liquibase.enabled: Flag to enable / disable Liquibase.
• quarkus.jfr.enabled: If false, only quarkus-jfr events are not recorded even if JFR is enabled. In this case, Java standard API and virtual machine information will be recorded according to the setting. Default value is true
• quarkus.kubernetes-config.enabled: If set to true, the application will attempt to look up the configuration from the API server
• quarkus.load-shedding.enabled: Whether load shedding should be enabled. Currently, this only applies to incoming HTTP requests.

And finally some use an active root configuration property with a different meaning:

• quarkus.flyway.active: Flag to activate/deactivate Flyway for a specific datasource at runtime.
  NOTE: The documentation (previous sentence) is unclear, but this actually only disables "on-startup" behavior for Flyway. You can still retrieve the Flyway bean and trigger schema changes, so it's not really "deactivated".

We even have pending PR (#42225) that would add a property quarkus.liquibase[."datasource-name"].active which takes effect at build-time... the reason being that quarkus.liquibase.enabled is already taken, and has effect on all datasources (but it's a runtime property!).

Let's discuss how to reconcile all this.

---

Note some extensions have an active/enabled property that is not at the root of their config, using it to enable/disable specific features (see below). I am not suggesting to change these in any way, though someone else might want to open a different issue to improve consistency there too; in particular metrics/tracing seems to be configured sometimes in the metrics/tracing extension, sometimes in the "integrated" (JDBC, ...) extension.

List of configuration properties that are not relevant to this issue: https://gist.github.com/yrodiere/16c8e429d0dd7b38bea3a97d6fdc86f5

Implementation ideas

I would suggest we:

• agree on naming/semantics once and for all
• create a PR to align existing core extensions
• create a PR to include these rules in a guide or some documentation aimed at extension writers

I would tentatively suggest the following naming and semantics:

• quarkus.myextension[.name-for-datasource-or-persistence-unit-or-client-or-whatever].enabled: disables a datasource/persistence unit/client (if that makes sense) or whole extension (otherwise) at build time. It will be as if the extension didn't exist
• quarkus.myextension[.name-for-datasource-or-persistence-unit-or-client-or-whatever].active: deactivates a datasource/persistence unit/client (if that makes sense) or whole extension (otherwise) at build time
• And possibly, to avoid ambiguity between disabling an extension and e.g. disabling just the default persistence unit, a built-in feature in Quarkus (no need to implement anything in extensions) to disable extensions that are in the classpath. This could be either quarkus.myextension.enable-extension, or more likely some more arcane property like quarkus.extensions."extension-id".enabled.

For the existing discrepancies, I would suggest the following.

Extensions using a slightly different naming scheme: align naming?

• quarkus.health.extensions.enabled => rename to quarkus.health.enabled?

Extensions using an enabled root configuration property to disable the extension at runtime: rename to quarkus.*.active, and introduce build-time property quarkus.*.enabled?

• quarkus.cache.enabled => rename to quarkus.cache.active, and introduce quarkus.cache.enabled for build-time only?
• quarkus.liquibase.enabled => rename to quarkus.liquibase.active, and introduce quarkus.liquibase.enabled for build-time only?
• quarkus.jfr.enabled => rename to quarkus.jfr.active, and introduce quarkus.jfr.enabled for build-time only?
• quarkus.kubernetes-config.enabled => rename to quarkus.kubernetes-config.active, and introduce quarkus.kubernetes-config.enabled for build-time only?
• quarkus.load-shedding.enabled => rename to quarkus.load-shedding.active, and introduce quarkus.load-shedding.enabled for build-time only?

Extensions with an active root configuration property with a different meaning: change the behavior to align on agreed-upon semantics?

• quarkus.flyway.active: disable both flyway's on-start behavior and access to beans as soon as active is false?

[quarkus-bot]

/cc @geoand (kubernetes), @iocanel (kubernetes), @radcortez (config)

[yrodiere]

cc @gsmet

[melloware]

If we are voting I prefer "enabled" over "active" 😬

But I do see your point about consistency. All my extensions use "enabled" at the root because I followed other extensions examples.

[yrodiere]

If we are voting I prefer "enabled" over "active" 😬

Unfortunately we are not, at least not about "enabled vs. active". Both are necessary, because they address different needs:

• quarkus.hibernate-orm.enabled=false (extension level) will disable the Hibernate extension at build time: it will be almost as if the extension was not in the class path, it won't do anything except declare its presence so that it can be displayed on app startup.

• quarkus.hibernate-orm[."persistence-unit-name"].active=false (persistence unit level) will activate/deactivate a persistence unit at runtime: if inactive, the SessionFactory does not started on app startup and SessionFactory/Session/... beans cannot be accessed at runtime.

We can probably think about different name (though I'd rather not), but picking one over the other would mean removing a feature.

[yrodiere]

Another solution would be to change the convention:

• use .build-enabled for build-time enablement -- or if we stick to extension level, quarkus.myextension.enable-extension or quarkus.extensions."extension-id".enabled
• use .enabled for runtime enablement
• keep .active where it exists, but deprecate it

I think it could makes sense given:

• the keyword "active" is kind of exotic
• I suspect the need for disabling extensions at at build-time is rather rare; you'd generally just remove the extension from your depedencies.
• people generally don't think about the build-time/runtime split when configuring Quarkus, so they probably expect enabled to just work at runtime.

However, this would potentially be a breaking change in Hibernate extensions: .enabled would no longer be applied at build time, and would be applied only to the default persistence unit, potentially leading to build errors in places where the extension was disabled for a good reason.

[xstefank]

For the existing discrepancies, I would suggest the following.

Extensions using a slightly different naming scheme: align naming?

• quarkus.health.extensions.enabled => rename to quarkus.health.enabled?

This will not work. quarkus.health.extensions.enabled is specifically saying that we don't include Quarkus provided checks in the responses, not disabling the whole extension. But I can maybe rename it to quarkus.health.extensions.included.

[xstefank]

@yrodiere @gsmet I'm also thinking that for the global enable/disable, if we are still printing the feature in the log on app startup, should it be something like smallrye-health (disabled) or smallrye-health (inactive)?

[yrodiere]

@yrodiere @gsmet I'm also thinking that for the global enable/disable, if we are still printing the feature in the log on app startup, should it be something like smallrye-health (disabled)

Makes sense to me.