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.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.
