Convert a Standalone Self-Managed mongod to a Replica Set

A standalone mongod instance is useful for testing and development. A standalone instance isn't a good choice for a production deployment because it can be a single point of failure. A replica set, also known as a cluster, provides redundancy and availability. Always use a replica set in production.

If you have a standalone server with data that you want to use in production, convert the standalone server to a replica set first.

Important

If you convert a development server to a replica set for production use, consult the security checklist before you expose your cluster to the internet.

Before You Begin

Cluster Type

Before you convert your standalone instance, consider whether a replica set or a sharded cluster is more appropriate for your workload.

A sharded cluster is a special kind of cluster. A sharded cluster provides redundancy and availability; it also distributes data across shards. Shards are usually hosted on multiple servers and allow for horizontal scaling.

Authorization

To use authorization with a replica set, you must also configure replica set members to use X.509 certificates or keyfiles to perform internal authentication.

For more information, see:

Procedure

Shut down the standalone instance.

Use mongosh to connect to your mongod instance.

mongosh

Switch to the admin database and run shutdown.

use admin
db.adminCommand(
   {
      shutdown: 1,
      comment: "Convert to cluster"
   }
)

Configure Replica Set Members

Update the configuration file on each server and to set the replSetName setting.

replication:
  replSetName: "rs0"

Configure Member Authentication

Configure member authentication for each server in the replica set.

Configure the replica set to use X.509 certificates for internal member authentication.

Setting	Option	Description
`net.tls.mode`	`--tlsMode`	Sets the TLS mode to use in authentication. To configure the server to require X.509 certificate authentication, set this option to `requireTLS`.
`net.tls.certificateKeyFile`	`--tlsCertificateKeyFile`	Sets the path to the `.pem` file that contains the TLS certificate for client connections.
`net.tls.CAFile`	`--tlsCAFile`	Sets the path to the file that contains the root certificate chain for the Certificate Authority (CA).
`net.tls.clusterFile`	`--tlsClusterFile`	Sets the path to the `.pem` file that contains the TLS certificate for cluster member connections.
`security.clusterAuthMode`	`--clusterAuthMode`	Sets the mode used to authenticate cluster members. To use X.509 authentication, set this option to `x509`.

For example:

replication:
  replSetName: "rs0"
security:
  clusterAuthMode: x509
net:
  tls:
    mode: requireTLS
    certificateKeyFile: /etc/mongodb/client.pem
    CAFile: /etc/mongodb/ca.pem
    clusterFile: /etc/mongodb/member.pem

Configure the replica set to use keyfiles for internal member authentication. To authenticate, each member must have a copy of the same keyfile.

Setting	Option	Description
`security.keyFile`	`--keyFile`	Sets the path to the replica set keyfile.

For example:

replication:
   replSetName: "rs0"
security:
    keyFile: /etc/mongodb/keyfile

Configures a replica set without authorization.

Warning

You should only use this configuration for internal replica sets that are not accessible through the network.

Setting	Option	Description
`net.bindIp`	`--bind_ip`	Sets the hostnames or IP addresses that MongoDB listens on for client connections. To block network access to the server, set this option to `localhost`.

For example:

replication:
  replSetName: "rs0"
net:
   bindIp: localhost

Start MongoDB

Start mongod for each member.

Initialize the replica set.

To initialize the replica set, use mongosh to reconnect to your server instance. Then, run rs.initiate().

rs.initiate()

You only have to initiate the replica set once.

To view the replica set configuration, use rs.conf().

To check the status of the replica set, use rs.status().

Add nodes to the replica set.

The new replica set has a single, primary node. The next step is to add new nodes to the replica set. Review the documentation on clusters before you add additional nodes:

When you are ready to add nodes, use rs.add().

Update Your Application Connection String.

After you convert the mongod to a replica set, update the connection string used by your applications to the connection string for your replica set. Then, restart your applications.

Learn More

Back

Replica Set

Add Members