Properties migrator demo

Spring Boot 2 introduced a new feature that allows to inspect the Environment on startup and give a report of properties usage that are no longer supported.

Properties that can be migrated automatically are migrated at runtime with a warning report that lists the properties and their replacements so that you can adapt your configuration.

Properties that have no replacement or not a one-to-one replacement (e.g. a property that was split in two or several properties that were combined into one) are listed in an error report with some further information.

To enable the report during the migration, simply add an extra module to your project

[source,xml]

Or if you're using Gradle:

[source]

runtime("org.springframework.boot:spring-boot-properties-migrator")

All the behaviour of the tool is derived from the metadata which means custom starters and application configuration can also be migrated the exact same way. This sample project showcase different use cases, each in its own commit.

Steps

Simple App

Initially, we have a simple 1.5. app with several properties used to customize things. Not all of them are relevant to this app and have been added solely to demonstrate the migration.

The important piece is that the actuator is running on port 9090 and the health endpoint has been customized and is available at http://localhost:9090/my-health rather than http://localhost:9090/health.

Upgrade App to Spring Boot 2

If we upgrade the application to Spring Boot, we noticed that properties defined in application.properties show up as errors. That's because those keys have changed and are no longer honoured.

If we start our app now, we can see that the health endpoint is available at http://localhost:8080/actuator/health (as the default context for actuator endpoints is /actuator rather than / in Spring Boot 2).

The assistance in the IDE is very nice but not all properties are accessible from it. In the next step we'll add the migrator.

Add Properties Migrator

If we add spring-boot-properties-migrator to the app, the migration kicks in automatically and report the following on startup:

[source]

2018-08-29 09:54:28.497 WARN 77310 --- [ main] o.s.b.c.p.m.PropertiesMigrationListener : The use of configuration keys that have been renamed was found in the environment:

Property source 'applicationConfig: [classpath:/application.properties]': Key: endpoints.health.path Line: 6 Replacement: management.endpoints.web.path-mapping.health Key: management.port Line: 3 Replacement: management.server.port

Each configuration key has been temporarily mapped to its replacement for your convenience. To silence this warning, please update your configuration to use the new keys.

2018-08-29 09:54:28.498 ERROR 77310 --- [ main] o.s.b.c.p.m.PropertiesMigrationListener : The use of configuration keys that are no longer supported was found in the environment:

Property source 'applicationConfig: [classpath:/application.properties]': Key: management.security.enabled Line: 4 Reason: A global security auto-configuration is now provided. Key: security.basic.enabled Line: 1 Reason: The security auto-configuration is no longer customizable.

Please refer to the migration guide or reference guide for potential alternatives.

The first report warns us about two properties that could be migrated at runtime and still require the source to be updated. The health endpoint is now back at http://localhost:9090/actuator/my-health.

There are two keys (unused and for demonstration purposes) that are no longer used and for which there isn't a replacement. Some dedicated actions are required.

Fix Configuration

We can now fix configuration based on the advice. If we restart the application, the report doesn't show anything particular.

That does not explain how you can use the properties migration with your own keys. Let's initiate that in the next step.

Add Simple Library

A new project called demo-properties-migrator-lib showcases a very simple custom auto-configuration that exposes two keys: demo.acme.name and demo.acme.counter. We're now using this library in our project that outputs the following on startup:

[source]

Value for name: 'my-test'

Deprecate a Property

Let's assume in the lifecycle of this project that demo.acme.name is not the proper name for the feature and target is better. It is very easy to deprecate a property and introduce a new one, doing the mapping in the code. This deprecating is very simple but there is no particular limitation as how the mapping should be done (i.e. the replacement can be in a totally different namespace).

We upgrade our app to the next version of the library (1.1.0) and everything works the same except we have a warning in application.properties in our IDE as demo.acme.name is now deprecated.

Let's ignore the deprecation message for now.

Remove the Property

It's time to introduce a major new release of our library. 2.0.0 can remove the deprecated code in 1.1 so let's do that.

If we don't do anything special, our application log looks like as follows:

[source]

Value for target: 'null'

Also demo.application.name shows up as unknown in our IDE (no assistance whatsoever). The next step will fix that and showcase how the properties migrator is reusing the metadata transparently.

Document Deprecation Manually

The code has been removed but we can still create a https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#configuration-metadata-additional-metadata[manual meta-data entry] for the property that the lib used to support. If we do this, we can see that the IDE recognizes the key again.

If we start our app with no further change, we get the following:

[source]

Value for target: 'my-test'

2018-08-29 10:39:17.046 WARN 86191 --- [ main] o.s.b.c.p.m.PropertiesMigrationListener : The use of configuration keys that have been renamed was found in the environment:

Property source 'applicationConfig: [classpath:/application.properties]': Key: demo.acme.name Line: 4 Replacement: demo.acme.target

Each configuration key has been temporarily mapped to its replacement for your convenience. To silence this warning, please update your configuration to use the new keys.

The properties migration has remapped our key at runtime and the report provides more information about what needs to be done.

Fix Configuration Again

We can now fix our configuration. Once we're done with the migration, be it a Spring Boot migration or a 3rd party library/app/starter migration, make sure to remove spring-boot-properties-migrator as it is not required to run your app.