MongoDB Replicaset support

[artiomchi]

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]

🚀 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"

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