How should we configure server-wide options for MicroProfile features

[Azquelt]

Background

MicroProfile specifications generally allow configuration options to be set using in terms of MP Config. The supported properties are listed in the Open Liberty documentation.

MP Config is a standard way of setting config which works across different application servers. It's also works well in container environments because any MP Config property can be set via an environment variable.

In contrast, most other parts of Open Liberty config are configured using server.xml.

MP Config reads config values from several sources, some of which are specific to an application whereas others are system-wide.

• Application-specific sources

  • microprofile-config.properties file within the application archive
  • <appProperties> element within an <application> element in server.xml
  • Custom config sources (since they're packaged in an application)

• Server-wide sources

  • System properties
  • Environment variables
  • server.xml variables

Problem

For mpOpenApi-x.x features, we have some config properties which are server-wide, rather than scoped to a particular application. When we read these config values, we don't consider any config sources which are application-specific.

This behaviour could be unintuitive for users who are used to putting all their config which is known at build time within their application, or who are using custom config sources.

For example mpOpenAPI-2.0+ has the following config properties:

• mp.openapi.extensions.liberty.merged.include
  • specifies which applications are included in the merged OpenAPI document
• mp.openapi.extensions.liberty.merged.exclude
  • specifies which applications are excluded from the merged OpenAPI document

MicroProfile Metrics also has some config properties which are server-wide:

• mp.metrics.<registry>.enabled
• mp.metrics.<registry>.<property>
• mp.metrics.smallrye.histogram.precision
• mp.metrics.smallrye.timer.precision
• mp.metrics.tags
  • This one is mentioned in the spec as defining tags "at the application server level"

Possible solutions

1. All server-wide config should be in server.xml. Only app-scoped config properties may be read from MP Config.

   • Users may need to use both MP Config and server.xml to configure the feature
   • If the value needs to be configurable at deployment time, the user must use placeholders in the server.xml
   • Add new server.xml elements for server-wide config properties which are currently read from MP Config.
     • Old options would continue to be supported

2. Continue to use MP Config for all configuration of MP features

   • Users cannot place server-wide config in application-specific config sources
   • Users cannot use custom config sources for server-wide config
   • This effectively constrains users to using system properties, environment variables and server.xml variables to configure these properties

3. Read config from both server.xml and MP Config

   • Define a set of guidelines for how liberty should behave if the user configures both

[tevans78]

Note that some other MP features may be configured via server.xml elements. Some are global, some are scoped by application. Because these server.xml elements are outside of the scope captured by the generic server.xml ConfigSource provided by the mpConfig feature, it is not entirely clear which "source" takes precedence in each case. https://github.com/OpenLiberty/open-liberty/issues/21423

[Azquelt]

Points raised

From the design meeting 2023-05-30

• Option 1 may be unworkable because in some places we are using open-source implementations and we don't always have control over exactly where that implementation reads its config from
• We weren't entirely sure of what user expectations would be:
  • On the one hand, it could be confusing to allow server-level config within an application - logically it doesn't make sense there
  • On the other hand, if the user is only deploying one application, they may not be thinking about what's config for their application vs. what's config for the whole server, they're thinking about it as one unit they deploy
• One of the design principles of liberty is that server config is dynamic
  • It's very unfortunate that this isn't the case for properties read from MP Config
• We don't currently document which config properties can't be configured with an application
• We don't currently warn the user if they try to configure server-level config within an application config source

Actions

1. Where we have a choice, we should prefer to put server-level configuration in server.xml
   • This ensures that as far as possible we maintain the principle that server-level config should be dynamic
2. Update documentation for existing MP Config properties which cannot be set in application config sources
3. Make the maven + gradle plugins aware of MP Config properties which cannot be set in application config sources
   • They could move the relevant properties into server.xml, or at least warn the user