Re-augment a Quarkus Application
What is augmentation?
Quarkus application configuration may include two types of configuration options:
-
Build time options, handled during the application build time;
-
Runtime options, that may be adjusted after the application has been built but before it has been launched.
The augmentation is a phase of an application build process during which the byte code of the application is optimized according to the application build time configuration.
Initialization steps that used to happen when an EAR file was deployed on a Jakarta EE server such as parsing static configuration, creating proxy instances, etc. now happen at augmentation time.
CDI beans added after augmentation won’t work (because of the missing proxy classes) as well as build time properties (e.g. quarkus.datasource.db-kind) changed after augmentation will be ignored.
Build time properties are marked with a lock icon () in the list of all configuration options.
It doesn’t matter if you use profiles or any other way to override the properties.
Re-augmentation is the process of recreating the augmentation output for a different build time configuration
When is re-augmentation useful?
Re-augmentation is useful in case the users of your application want to be able to change some of its build time properties.
For instance changing the database driver or switching features on or off (e.g. OpenTelemetry or Config Consul).
If there are only two or three build time properties that depend on the user environment, you may consider providing alternative builds of the application. However, in case there are more such properties you may prefer shipping a mutable jar instead and let your users re-augment the application for their environment.
Please notice that you won’t be able to use native images with the package type mutable-jar.
Think of the consequences and what other options you have!
It is not a good idea to do re-augmentation at runtime unless you miss the good old times when starting up a server took several minutes, and you could enjoy a cup of coffee until it was ready.
How to re-augment a Quarkus application
In order to run the augmentation steps you need the deployment JARs of the used Quarkus extensions.
These JARs are only present in the mutable-jar distribution. This means that you need to build your application with quarkus.package.jar.type=mutable-jar.
The mutable-jar distribution is the same as the fast-jar distribution, except for the additional folder quarkus-app/lib/deployment
which contains the deployment JARs and their dependencies (and some class-loader configuration).
By default, you’ll get a warning if a build time property has been changed at runtime.
You may set the quarkus.configuration.build-time-mismatch-at-runtime=fail property to make sure your application does not start up if there is a mismatch.
However, as of this writing changing quarkus.datasource.db-kind at runtime did neither fail nor produce a warning but was silently ignored.
|
Build time configuration provided by build tools (properties in Maven pom.xml or gradle.properties
in Gradle) in the quarkus namespace will be part of the mutable-jar distribution, including configuration from
quarkus that reference secrets or passwords. Please, do not include sensitive information in the build tool
configuration files.
|
2. Re-augment your application with a different build time configuration
In order to re-augment your Quarkus application with different build time properties, start the application with the desired configuration plus the quarkus.launch.rebuild system property set to true.
The following example changes the quarkus.datasource.db-kind to mysql. For this to work the mysql-extension must have been included in the build. Augmentation can only use extensions that were present during compile time.
java -jar -Dquarkus.launch.rebuild=true -Dquarkus.datasource.db-kind=mysql target/quarkus-app/quarkus-run.jar
It does not matter if you use system properties, environment variables, profiles, or an external config file. The current
configuration will be used for augmentation (the content of quarkus-app/quarkus will be replaced with the new augmentation output).
The command line above will not launch the application. Quarkus will exit immediately after the application has been re-augmented.
|
3. Optional: Delete the deployments folder
You may delete the directory quarkus-app/lib/deployment to save some space in your ZIP distribution or Docker image (remember to use a multistage Docker build to avoid unnecessary layers). After deleting the deployment directory, it is obviously not possible anymore to re-augment the application.
