Document MongoDB automatic TLS and migration guidance

[eerhardt]

Summary

Document the MongoDB TLS behavior introduced by microsoft/aspire#18196 ("Introduce MongoDBReplicaSetResource") as a compatibility-impacting change, including migration guidance in the MongoDB hosting documentation and the appropriate release/breaking-change notes.

This affects ordinary AddMongoDB resources, not just replica sets. In local run mode, MongoDB now participates in Aspire's shared certificate configuration. When a certificate is configured (normally the developer certificate under the default settings), Aspire starts MongoDB with --tlsMode requireTLS and adds tls=true to its generated connection string. This was an intentional design change during PR review, rather than an accidental side effect of enabling replica sets.

The integration README describes this behavior, but users upgrading existing applications need a discoverable explanation of the changed default and their options.

Compatibility impact to explain

• Existing clients using plaintext connections can stop working, even if the application does not use replica sets.
• Consumers should use the full Aspire-generated connection string. Constructing a URI from only Host/Port can omit the required TLS option.
• TLS also requires certificate trust and a matching server name. In local testing, a container client using the MongoDB resource DNS name encountered a hostname mismatch because that name was not in the developer certificate. Trusting the CA alone does not resolve that mismatch. Document supported connection/certificate arrangements rather than recommending disabled certificate validation as the general solution.
• Clearly distinguish local run-mode defaults from publish/deploy behavior; this does not mean published MongoDB containers automatically receive the same developer-certificate configuration.

Migration guidance to include

Opt out for an individual standalone MongoDB resource

C#:

var mongo = builder.AddMongoDB("mongo")
    .WithoutHttpsCertificate();

TypeScript:

const mongo = await builder.addMongoDB("mongo")
    .withoutHttpsCertificate();

This also works with the simple single-member WithReplicaSet() / withReplicaSet() configuration. Explain that the opt-out disables transport encryption and should be an explicit local-development choice.

Explain the other controls and their limits

• ASPIRE_DEVELOPER_CERTIFICATE_DEFAULT_HTTPS_TERMINATION=false disables ambient developer-certificate defaults globally, affecting other resources as well as MongoDB. Prefer the resource-level opt-out when only MongoDB needs different behavior.
• WithTlsMode(MongoDBTlsMode.PreferTls) / withTlsMode({ mode: MongoDBTlsMode.PreferTls }) allows both plaintext and TLS clients, but the generated connection string still advertises TLS. It is not equivalent to disabling TLS.
• Do not apply the no-TLS workaround to advanced multi-member replica sets. AddMongoDBReplicaSet().WithMember() explicitly configures certificates and relies on TLS/SNI for split-horizon discovery. The global default switch does not disable that explicit configuration.

Requested documentation updates

• Add a compatibility/breaking-change note identifying the first release containing the new default.
• Update MongoDB hosting documentation to explain when automatic TLS applies, including ordinary AddMongoDB resources.
• Provide C# and TypeScript migration examples and explain certificate trust versus hostname validation.
• Distinguish standalone, simple single-member replica sets, and advanced multi-member replica sets.
• Clarify the scope of resource-level/global opt-outs, PreferTls, and run versus publish behavior.

References

• Introducing PR: Introduce MongoDBReplicaSetResource aspire#18196
• MongoDB integration README
• MongoDB hosting implementation
• Advanced replica-set implementation

The individual opt-out, PreferTls, and global default switch were exercised against installed preview packages during local feature validation. This issue is for documentation of the TLS behavior; it does not request changing the product default.