guides

Use DNS Names in Connection Strings

A practical rollout for moving MongoDB, Redpanda, and other service clients from fixed IP addresses to environment-specific DNS names.

Last updated · 5 August 2026

A connection string should identify a service, not the address of the VM currently running it. Hard-coded IPs couple application releases to infrastructure changes and make migrations harder to stage or reverse.

For the current MongoDB endpoints, use these service identities:

Environment	Replace	With
Production	`mongodb://myuser:<password>@10.0.0.16:27017`	`mongodb://myuser:<password>@mongo.excloud.dev:27017`
Staging	`mongodb://myuser:<password>@10.0.0.17:27017`	`mongodb://myuser:<password>@mongo.staging.excloud.dev:27017`

Use the hostnames without a trailing dot in application connection strings. The absolute DNS forms are mongo.excloud.dev. and mongo.staging.excloud.dev., but some TLS and application libraries do not normalize a trailing dot consistently.

Never commit the real username or password. Store the complete URI in a secret manager or construct it from injected secrets. Percent-encode credentials if they contain URI-reserved characters such as @, :, /, ?, or #.

What this change provides

A stable DNS name lets operators change the backing address without changing application code or rebuilding every deployment. It creates a useful migration and rollback control point.

DNS alone does not provide zero downtime. It does not:

move existing TCP connections;
replicate database state;
wait for the new service to become healthy;
drain old connection pools;
force every runtime or local resolver to honor the authoritative TTL immediately;
rewrite MongoDB replica-set or Kafka/Redpanda advertised member addresses.

Treat DNS as one component of the migration plan, not as a load balancer or database failover protocol.

1. Inventory every address

Search source, deployment manifests, CI variables, secret stores, and dashboards. Do not limit the search to mongodb://:

rg -n '10\.0\.0\.(16|17)|mongodb(\+srv)?://|bootstrap\.servers|brokers' \
  --glob '!vendor/**' --glob '!node_modules/**' .

Also inspect values outside Git:

Kubernetes Secrets and ConfigMaps;
systemd environment files;
container platform variables;
CI/CD environment variables;
worker and cron-job configuration;
monitoring, backup, and migration jobs;
developer .env files;
Redpanda/Kafka bootstrap and advertised broker addresses.

Record the owner, environment, secret location, client runtime, and restart/reload procedure for each consumer.

2. Create environment-specific records

Create records for:

mongo.excloud.dev.    production
mongo.staging.excloud.dev.    staging

Use AAAA records for assigned Global Unicast IPv6 addresses wherever the server, client, routing, and security groups support IPv6 end to end. Add A records while IPv4-only clients remain.

Example zone-file notation:

mongo.excloud.dev.  300 IN AAAA 2001:db8:100::16
mongo.excloud.dev.  300 IN A    192.0.2.16

mongo.staging.excloud.dev.  300 IN AAAA 2001:db8:200::17
mongo.staging.excloud.dev.  300 IN A    192.0.2.17

The addresses above are documentation ranges; replace them with the assigned service addresses. The trailing dots are intentional because the names are absolute in a zone file.

Global Unicast IPv6 space is globally unique and avoids the private-IPv4 overlap common in peered networks, VPNs, and acquisitions. Do not generalize that property to all IPv6: link-local addresses are interface-scoped, and Unique Local Addresses are private and not globally routed.

If the database must remain private, use authoritative internal DNS or split-horizon DNS so the name resolves only to privately routed addresses for authorized clients. Publishing a private address in public DNS does not make it reachable, but it can expose internal topology and is usually unnecessary.

If you use Excloud DNS, follow the DNS quickstart and records reference.

3. Verify DNS from the application network

Query both record families explicitly:

dig +short A mongo.excloud.dev.
dig +short AAAA mongo.excloud.dev.
dig +short A mongo.staging.excloud.dev.
dig +short AAAA mongo.staging.excloud.dev.

Then test through the same name-service path and network namespace as the application:

getent ahosts mongo.excloud.dev
getent ahosts mongo.staging.excloud.dev

Run checks inside the relevant container or pod as well as on an operator laptop. Confirm that security-group and host-firewall rules allow port 27017 over every published address family.

A published AAAA record is a promise that IPv6 works. Do not publish it until routing, firewall policy, MongoDB bind settings, and monitoring all work over IPv6.

4. Test the name before changing applications

Use a real database client from staging or a disposable workload. Do not print credentials in shell history or CI logs.

With a URI supplied securely as MONGODB_URI:

mongosh "$MONGODB_URI" --eval 'db.runCommand({ ping: 1 })'

Validate:

authentication;
TLS certificate hostname verification, if TLS is enabled;
read and write behavior appropriate for the test environment;
IPv4 and IPv6 paths separately where possible;
logs and metrics identifying connections to the expected server.

For TLS, issue a certificate whose Subject Alternative Name contains the service hostname. A certificate for an IP address or an old node name may fail once clients connect through mongo.excloud.dev.

5. Update connection strings through configuration

Use one environment variable or secret path across deployments while giving each environment its own value:

# Production secret value
MONGODB_URI=mongodb://myuser:<encoded-password>@mongo.excloud.dev:27017

# Staging secret value
MONGODB_URI=mongodb://myuser:<encoded-password>@mongo.staging.excloud.dev:27017

Applications should read the value at startup rather than carrying a fallback IP in source code. A fallback silently restores the coupling this migration is meant to remove.

Roll out staging first. Restart or reload consumers in controlled batches, confirm new connections use the DNS name, and monitor connection errors, latency, replica-set state, and application error rates. Then repeat for production.

MongoDB topology caveat

For a standalone MongoDB node, an A/AAAA-backed hostname can replace the literal IP directly.

For a replica set, the seed URI is only the first contact. MongoDB returns its member list to the driver, and the driver connects to those advertised member names. Configure every replica-set member with a stable, resolvable DNS name that clients can reach. Changing only the seed host does not remove hard-coded or private addresses advertised by the set.

If you adopt mongodb+srv://, publish the required SRV records and follow the driver’s SRV and TLS behavior. Do not add :27017 to an SRV URI. This is a separate, tested migration—not a mechanical string replacement.

Redpanda and Kafka caveat

A DNS bootstrap name removes the initial hard-coded address, but Kafka-compatible clients receive broker addresses from cluster metadata. Each broker’s advertised_kafka_api address must use a stable DNS name resolvable and reachable by the clients.

Do not point one round-robin name at several brokers and assume that solves advertised listeners, health checks, or failover. Give brokers stable identities, for example:

rp-0.kafka.excloud.dev
rp-1.kafka.excloud.dev
rp-2.kafka.excloud.dev

Use an appropriate bootstrap list or DNS-based discovery mechanism, then test metadata resolution from every client network.

6. Prepare future cutovers

Well before moving a service:

Confirm all clients use the service name rather than an IP.
Measure the current DNS TTL and application/runtime DNS caching behavior.
Lower the TTL—for example, from 3600 to 60—at least one old-TTL period before the cutover.
Replicate and validate data on the target.
Make the target reachable under its own temporary validation name.
Change the service record during the migration window.
Recycle or drain connection pools as the driver and application require.
Monitor new connections, errors, lag, and data correctness.
Keep the old service available for the planned rollback period.
Raise the TTL again after the new endpoint is stable.

A TTL is a cache lifetime, not a deadline by which every client is guaranteed to switch. Existing sessions can live beyond it, and some runtimes cache DNS independently.

Rollback

Keep a written rollback record value and the old service ready. If validation fails:

Restore the previous A/AAAA target.
Drain or restart clients whose pools remain connected to the new target.
Verify reads and writes against the intended primary.
Check for data written during the cutover and reconcile it before another attempt.

Database consistency determines whether address rollback is safe. DNS can redirect new connections; it cannot merge diverged data.