MongoDB Replicaset support by artiomchi · Pull Request #16698 · microsoft/aspire

artiomchi · 2026-05-02T16:21:09Z

Description

This PR modifies the MongoDB Builder to add support for building a single node replica set. This will allow applications using transactions or change streams to use MongoDB in Aspire.

I'm using the same approach as I used when building the Testcontainers.MongoDb library. Instead of building a separate container in a dockerfile, the standard mongo container is used. To start as a replicaset, a keyfile is generated and added to to the container. The healthcheck is used to ensure the replicaset is initialised on server startup. This keeps the implementation clean and doesn't require an additional dockerfile.

New WithReplicaSet() Extension Method on the builder
- Configures Mongo to run as a single node replica set
- Generates a new keyfile and stores it as a secret parameter
New Mongo health check
- Falls back to simple connection checks for non replica sets
- Ensures replSetInitiate command runs
- Verifies primary node election
MongoDBServer resource updates
- Adds ReplicaSetName property
- Updates connection string to include directConnection=true parameter when replica set is enabled

Fixes #5238

Decision points

New health check

The new health check replaces the simple original health check and will only return healthy once the replica set is initialised. It is also used to call the rs.initiate() call in Mongo to initialise the replicaset.

Alternatives considered:

OnResourceReady callback fires after the health check passes - this would mark the resource as healthy before the replica set is ready
docker-entrypoint-initdb.d - tried in the past, this won't work as that script runs against a standalone mongod instance, and won't affect the main instance
Separate health check - this would require the main health check to pass, and would send conflicting signals
Additional resource that initialises the replicaset once the server is ready, then referencing that in applications - works, provides visibility in the dashboard that the replicaset is initialised separately, but adds unnecessary complexity to configuratio for the users in the AppHost, as well as in the dashboard. Doesn't bring any tangible value

Direct connection in connection string

Specifying the replicaset name in the connection string is explicitly discouraged by the MongoDB driver configuration, and can cause behavioural conflicts. Specifying directConnection=true in the connection string tells the MongoDB driver to connect directly to the specified host bypassing topology discovery. Since we only have a single node, this is more than enough. Additionally, the topology discovery would return the internal host address within the container, which wouldn't be accessible by the application.

Note

There may be an issue in Mongo 8.0 - 8.2 that causes Mongo to crash every ~30 seconds if replica set is initiated. Seems to be a compatibility issue with certain linux kernels. Switching to older Mongo versions (7.0) seems to completely bypass the issue. Not related to this PR or Aspire, purely a MongoDB regression.

ref:
bluewave-labs/Checkmate#3444
https://www.mongodb.com/community/forums/t/mongodb-8-x-and-linux-kernel-6-19/337547
stoatchat/self-hosted#268

Checklist

Is this feature complete?
- Yes. Ready to ship.
- No. Follow-up changes expected.
Are you including unit tests for the changes and scenario tests if relevant?
- Yes
- No
Did you add public API?
- Yes
  - If yes, did you have an API Review for it?
    - Yes
    - No
  - Did you add <remarks /> and <code /> elements on your triple slash comments?
    - Yes
    - No
- No
Does the change make any security assumptions or guarantees?
- Yes
  - If yes, have you done a threat model and had a security review?
    - Yes
    - No
- No
Does the change require an update in our Aspire docs?
- Yes
  - Link to aspire.dev issue:
    - microsoft/aspire.dev#800
- No

github-actions · 2026-05-02T16:21:21Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 16698

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 16698"

Minor cleanup

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds single-node replica set support for hosted MongoDB resources so transaction-dependent scenarios can run against the Aspire MongoDB container, and introduces tests for the new API and connection string behavior.

Changes:

Add WithReplicaSet(...) to configure MongoDB as a single-node replica set and expose ReplicaSetName.
Replace the default MongoDB health check with a custom health check that initializes the replica set and waits for primary election.
Add functional and unit tests covering the new API, container args, and connection string updates.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/Aspire.Hosting.MongoDB.Tests/MongoDbFunctionalTests.cs	Adds a functional test that verifies transactions succeed against a replica-set-enabled MongoDB resource.
tests/Aspire.Hosting.MongoDB.Tests/MongoDBPublicApiTests.cs	Adds public API validation tests for `WithReplicaSet` and `ReplicaSetName`.
tests/Aspire.Hosting.MongoDB.Tests/AddMongoDBTests.cs	Adds unit tests for replica set defaults, args, annotations, and connection string behavior.
src/Aspire.Hosting.MongoDB/api/Aspire.Hosting.MongoDB.cs	Updates the shipped public API surface with `WithReplicaSet` and `ReplicaSetName`.
src/Aspire.Hosting.MongoDB/MongoDBServerResource.cs	Extends the resource model and connection string generation for replica set mode.
src/Aspire.Hosting.MongoDB/MongoDBServerHealthCheck.cs	Introduces a custom health check that initializes the replica set and checks primary readiness.
src/Aspire.Hosting.MongoDB/MongoDBBuilderExtensions.cs	Registers the new health check and implements `WithReplicaSet`.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

…ead safe way Disposing of the mongo cursor in the health check

…tensions.CreateGeneratedParameter

fedarovich · 2026-05-04T17:14:13Z

+                                new BsonDocument
+                                {
+                                    ["_id"] = 0,
+                                    ["host"] = $"{resource.Name}:{targetPort}"


While it works for the simplest scenarios, the issue is that depending on which service is accessing the resource, it requires a different host name:

If the replica set is accessed from the Aspire container network, $"{resource.Name}:{targetPort}" should be fine, though more correct name would be $"{resource.Name}.dev.internal:{targetPort}". Ideally, the actual URL should be retrieved from the server's ConnectionStringExpression with the DefaultAspireContainerNetwork context.

If the replica set is accessed from the services running locally, not in a container, they should be resolved as $"localhost:{targetPort}". Or, more precisely, from the server's ConnectionStringExpression with the LocalhostNetwork context. It's possible to add manual hosts mapping, of cause, but it does not seem to be a good solution.

I guess, if Dev Tunnels are being used, the things might get even more complicated, but I have not tried it myself.

As far as I know, the only reliable solution for that is using MongoDB Horizons feature, but it makes things more complicated as well.

Nah, none of this should be a problem. The host name here is only for the internal replication engine initialisation.

For connections to the mongo database from the application, the regular connection string is used, with the addition of the directConnection=true param.

fedarovich · 2026-05-04T17:19:54Z

+    /// <param name="replicaSetName">The name of the replica set. Defaults to <c>rs0</c>.</param>
+    /// <returns>The <see cref="IResourceBuilder{T}"/>.</returns>
+    [AspireExport(Description = "Configures the MongoDB container to start as a single-node replica set")]
+    public static IResourceBuilder<MongoDBServerResource> WithReplicaSet(this IResourceBuilder<MongoDBServerResource> builder, string replicaSetName = "rs0")


My concern is that this design does not allow to extend this feature beyond single-node replica sets.
In my opinion, having a replica set as a separate resource is a better option.

Is this needed though, for a local development database? This shouldn't be used to deploy a resilient production level database, that would require an entirely different ballgame

fedarovich · 2026-05-04T17:23:22Z

+                    var targetPort = resource.PrimaryEndpoint.TargetPort ?? 27017;
+                    var initCmd = new BsonDocument
+                    {
+                        ["replSetInitiate"] = new BsonDocument


It feels a bit like an abuse of the healthcheck. This logic can live in a separate event handler.

You might say that, but it's the cleaner way to do this, considering the alternatives, while keeping the design simple and unobtrusive. Happy to discuss further, but I've explained the design decisions for this in the PR body above

Initial replicaset approach

3af3774

Correctly export the new properties

925dd48

artiomchi mentioned this pull request May 2, 2026

MongoDB Replica set support - needs documentation update microsoft/aspire.dev#800

Open

Test patching

67db131

Minor cleanup

artiomchi force-pushed the feat/add-mongodb-replicaset-support branch from 66c95f0 to 67db131 Compare May 2, 2026 16:57

artiomchi marked this pull request as ready for review May 2, 2026 16:58

Copilot AI review requested due to automatic review settings May 2, 2026 16:58

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread src/Aspire.Hosting.MongoDB/MongoDBServerHealthCheck.cs Outdated

Comment thread tests/Aspire.Hosting.MongoDB.Tests/AddMongoDBTests.cs Outdated

Comment thread tests/Aspire.Hosting.MongoDB.Tests/MongoDbFunctionalTests.cs

CR patches

f778b33

artiomchi requested a review from Copilot May 2, 2026 17:18

Copilot AI reviewed May 2, 2026

View reviewed changes

artiomchi added 2 commits May 2, 2026 18:34

Ensuring the mongo client in the health check is initialised in a thr…

b9d1d4c

…ead safe way Disposing of the mongo cursor in the health check

WithReplicaSet now creates the keyfile via ParameterResourceBuilderEx…

f40dc99

…tensions.CreateGeneratedParameter

github-actions Bot mentioned this pull request May 3, 2026

[repo-pulse] 📊 Repo Pulse — Daily Activity Dashboard #16404

Open

fedarovich reviewed May 4, 2026

View reviewed changes

Conversation

artiomchi commented May 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Decision points

New health check

Direct connection in connection string

Note

Checklist

Uh oh!

github-actions Bot commented May 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fedarovich May 4, 2026

Choose a reason for hiding this comment

Uh oh!

artiomchi May 4, 2026

Choose a reason for hiding this comment

Uh oh!

fedarovich May 4, 2026

Choose a reason for hiding this comment

Uh oh!

artiomchi May 4, 2026

Choose a reason for hiding this comment

Uh oh!

fedarovich May 4, 2026

Choose a reason for hiding this comment

Uh oh!

artiomchi May 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

artiomchi commented May 2, 2026 •

edited

Loading

github-actions Bot commented May 2, 2026 •

edited

Loading