Add blog explaining how to migrate to new dev services model #2460

holly-cummins · 2025-11-13T21:52:23Z

It's only five releases overdue :)

github-actions · 2025-11-13T21:59:17Z

🎊 PR Preview 7ca167d has been successfully built and deployed to https://quarkus-site-pr-2460-preview.surge.sh

Images of blog posts older than 3 months are not available.
Newsletters older than 3 months are not available.

_posts/2025-11-17-new-dev-services-api.adoc

Co-authored-by: Harald Albers <[email protected]>

ozangunalp

That is very good, Thanks @holly-cummins !

I've added some minor recommendations

ozangunalp · 2025-11-19T10:14:20Z

_posts/2025-11-17-new-dev-services-api.adoc

+
+----
+
+Deciding whether to re-use or replace a service is now handled centrally, based on a diff of the configuration.


Maybe we need to give some more context on this. How this was done before in dev service implementations.

Edit:

The article speaks about it later, maybe a word with a link to eligibility ro re-use would suffice

ozangunalp · 2025-11-19T10:19:51Z

_posts/2025-11-17-new-dev-services-api.adoc

+
+==== The `Startable`
+
+In order to support lazy starting, pass an implementation of `Startable` to the builder.


It is obvious to us, but we can add here a note NOT to call start before passing the startable

ozangunalp · 2025-11-19T10:31:12Z

_posts/2025-11-17-new-dev-services-api.adoc

+
+=== How can I have a build step do something after a dev service is started?
+
+This isn’t possible, because a dev service would never be started in the build phase. However, the `postStartHook` on the builder allows you to take actions once the dev service is started.


The postStartHook covers one of the use cases for the current build steps after the dev service starts.
There is another one for injecting configuration into the application through recorders, etc.

We can include a recommendation for how to resolve this second issue using Config in recorders.

cescoffier · 2025-11-19T10:15:25Z

_posts/2025-11-17-new-dev-services-api.adoc

+
+If you have test suites which use multiple profiles or test resources, you should find that you no longer see duplicate containers active at the same time. The containers should launch one after the other.
+
+However, this depends on the extension, because every extension needs to be converted to the new model. The Redis, Lambda, Nayarana, and Kafka extensions have been converted so far. You can track progress with the conversions by following the sub-issues of https://github.com/quarkusio/quarkus/issues/45785[#45785].


Suggested change

However, this depends on the extension, because every extension needs to be converted to the new model. The Redis, Lambda, Nayarana, and Kafka extensions have been converted so far. You can track progress with the conversions by following the sub-issues of https://github.com/quarkusio/quarkus/issues/45785[#45785].

However, this depends on the extension, as each needs to be converted to the new model. The Redis, Lambda, Narayana, and Kafka extensions have been converted so far. You can track progress on conversions by following the sub-issues in https://github.com/quarkusio/quarkus/issues/45785[#45785].

cescoffier · 2025-11-19T10:16:01Z

_posts/2025-11-17-new-dev-services-api.adoc

+
+[source,java]
+----
+    DevServicesResultBuildItem = DevServicesResultBuildItem.owned().name(MY_FEATURE_NAME)


Suggested change

DevServicesResultBuildItem = DevServicesResultBuildItem.owned().name(MY_FEATURE_NAME)

var item = DevServicesResultBuildItem.owned().name(MY_FEATURE_NAME)

cescoffier · 2025-11-19T10:17:13Z

_posts/2025-11-17-new-dev-services-api.adoc

+                            useSharedNetwork)
+                            .withEnv(myConfig.containerEnv())
+                     .configProvider(
+                            Map.of(someProp, s -> s.getConnectionInfo()))


Suggested change

Map.of(someProp, s -> s.getConnectionInfo()))

Map.of(someProp, s -> s.getConnectionInfo())

)

cescoffier · 2025-11-19T10:17:54Z

_posts/2025-11-17-new-dev-services-api.adoc

+
+Because service lifecycle is handled centrally, any shutdown listeners or other logic for stopping services should also be removed.
+
+=== Remove any references to `RunningDevService`


Suggested change

=== Remove any references to `RunningDevService`

==== Remove any references to `RunningDevService`

cescoffier · 2025-11-19T10:27:35Z

_posts/2025-11-17-new-dev-services-api.adoc

+
+All dev services using the old API start in the JUnit discovery phase (as of Quarkus 3.22). This is because they are started during https://quarkus.io/guides/reaugmentation#what-is-augmentation[the augmentation phase], along with bytecode manipulation and other application initialization steps. When the testing design changed, all augmentation happened at the beginning of the test run, during the JUnit discovery phase. This means all Dev Services also start at the beginning of the test run. If several test classes with different Dev Service configuration are augmented before any tests are run, multiple differently-configured Dev Services may be running at the same time.
+
+In the new model, Dev Services are started post-augment, and pre-launch.


Suggested change

In the new model, Dev Services are started post-augment, and pre-launch.

In the new model, Dev Services are started between the augmentation and the application's actual launch.

cescoffier · 2025-11-19T10:29:20Z

_posts/2025-11-17-new-dev-services-api.adoc

+
+As always, if you spot issues or oddities, please let us know on https://quarkusio.zulipchat.com/[zulip] or https://github.com/quarkusio/quarkus/issues[raise an issue].
+
+=== Technical details


Maybe "Why this change was needed" or "Background".

The rationale is that this subsection is under "What changes for users" (and you said nothing), but then why should they care about the technical details?

cescoffier · 2025-11-19T10:30:28Z

_posts/2025-11-17-new-dev-services-api.adoc

+
+==== Dependency changes and setting a minimum Quarkus version
+
+This bit is a bit awkward, unfortunately! In Quarkus 3.28, a new `devservices` runtime module was introduced. Most extensions have both a deployment and a runtime model, but historically, Dev Services only had a deployment module. The associated runtime classes lived in other modules. A runtime module was added in 3.28. Because it was a potentially disruptive change, it was done post-LTS. That seemed like a good idea, but had some unexpected consequences.


Suggested change

This bit is a bit awkward, unfortunately! In Quarkus 3.28, a new `devservices` runtime module was introduced. Most extensions have both a deployment and a runtime model, but historically, Dev Services only had a deployment module. The associated runtime classes lived in other modules. A runtime module was added in 3.28. Because it was a potentially disruptive change, it was done post-LTS. That seemed like a good idea, but had some unexpected consequences.

This bit is a bit awkward, unfortunately! In Quarkus 3.28, a new `devservices` runtime module was introduced. Most extensions have both a deployment and a runtime module, but historically, Dev Services only had a deployment module. The associated runtime classes lived in other modules. A runtime module was added in 3.28. Because it was a potentially disruptive change, it was done post-LTS. That seemed like a good idea, but it had some unexpected consequences.

cescoffier · 2025-11-19T10:33:09Z

_posts/2025-11-17-new-dev-services-api.adoc

+- Do not use static variables in the extension processor
+- Use the `discovered()` and `owned()` builders in `DevServicesResultBuildItem`
+- Config which is only known after the service is started can be passed in using a `configProvider()`
+


Can we have a checklist? The section is rather long (and the dependency part slightly overwhelming (I had to read it twice)), if we could introduce a checklist with all actions, the owner could just see the action plan.

cescoffier · 2025-11-19T10:34:51Z

_posts/2025-11-17-new-dev-services-api.adoc

+layout: post
+title: 'A Better Way of Creating Dev Services'
+tags: announcement testing
+synopsis: ''


Suggested change

synopsis: ''

synopsis: 'A new Dev Services API in Quarkus 3.25 fixes port conflicts and excessive resource usage in test suites, while providing a simpler programming model for extension authors.'

Add blog explaining how to migrate to new dev services model

83f4569

holly-cummins mentioned this pull request Nov 13, 2025

All devservices belonging to all TestProfiles are started at tests initialisation at startup quarkusio/quarkus#50902

Closed

holly-cummins added 2 commits November 14, 2025 10:37

Minor updates

459f0c1

Correct typo

ac0d6a7

albers reviewed Nov 17, 2025

View reviewed changes

_posts/2025-11-17-new-dev-services-api.adoc Outdated Show resolved Hide resolved

Update _posts/2025-11-17-new-dev-services-api.adoc

8e8dfe0

Co-authored-by: Harald Albers <[email protected]>

ozangunalp approved these changes Nov 19, 2025

View reviewed changes

cescoffier requested changes Nov 19, 2025

View reviewed changes

albers mentioned this pull request Nov 20, 2025

Refactoring: Pull out resolving of configuration files quarkiverse/quarkus-azure-services#461

Open


		----

		Deciding whether to re-use or replace a service is now handled centrally, based on a diff of the configuration.


		==== The `Startable`

		In order to support lazy starting, pass an implementation of `Startable` to the builder.


		=== How can I have a build step do something after a dev service is started?

		This isn’t possible, because a dev service would never be started in the build phase. However, the `postStartHook` on the builder allows you to take actions once the dev service is started.


		If you have test suites which use multiple profiles or test resources, you should find that you no longer see duplicate containers active at the same time. The containers should launch one after the other.

		However, this depends on the extension, because every extension needs to be converted to the new model. The Redis, Lambda, Nayarana, and Kafka extensions have been converted so far. You can track progress with the conversions by following the sub-issues of https://github.com/quarkusio/quarkus/issues/45785[#45785].

	DevServicesResultBuildItem = DevServicesResultBuildItem.owned().name(MY_FEATURE_NAME)
	var item = DevServicesResultBuildItem.owned().name(MY_FEATURE_NAME)

	Map.of(someProp, s -> s.getConnectionInfo()))
	Map.of(someProp, s -> s.getConnectionInfo())
	)


		Because service lifecycle is handled centrally, any shutdown listeners or other logic for stopping services should also be removed.

		=== Remove any references to `RunningDevService`

	=== Remove any references to `RunningDevService`
	==== Remove any references to `RunningDevService`


		All dev services using the old API start in the JUnit discovery phase (as of Quarkus 3.22). This is because they are started during https://quarkus.io/guides/reaugmentation#what-is-augmentation[the augmentation phase], along with bytecode manipulation and other application initialization steps. When the testing design changed, all augmentation happened at the beginning of the test run, during the JUnit discovery phase. This means all Dev Services also start at the beginning of the test run. If several test classes with different Dev Service configuration are augmented before any tests are run, multiple differently-configured Dev Services may be running at the same time.

		In the new model, Dev Services are started post-augment, and pre-launch.


		As always, if you spot issues or oddities, please let us know on https://quarkusio.zulipchat.com/[zulip] or https://github.com/quarkusio/quarkus/issues[raise an issue].

		=== Technical details


		==== Dependency changes and setting a minimum Quarkus version

		This bit is a bit awkward, unfortunately! In Quarkus 3.28, a new `devservices` runtime module was introduced. Most extensions have both a deployment and a runtime model, but historically, Dev Services only had a deployment module. The associated runtime classes lived in other modules. A runtime module was added in 3.28. Because it was a potentially disruptive change, it was done post-LTS. That seemed like a good idea, but had some unexpected consequences.

	synopsis: ''
	synopsis: 'A new Dev Services API in Quarkus 3.25 fixes port conflicts and excessive resource usage in test suites, while providing a simpler programming model for extension authors.'

Add blog explaining how to migrate to new dev services model #2460

Are you sure you want to change the base?

Add blog explaining how to migrate to new dev services model #2460

Uh oh!

Conversation

holly-cummins commented Nov 13, 2025

Uh oh!

github-actions bot commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

ozangunalp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Nov 13, 2025 •

edited

Loading