• Security >
• Authentication >
• Internal/Membership Authentication >
• Rotate Keys for Sharded Clusters

Rotate Keys for Sharded Clusters

Sharded cluster members can use keyfiles to authenticate each other as memers of the same deployment.

Starting in version 4.2, a keyfile can contain multiple keys and membership authentication is established if at least one key is common across members. This allows for rolling upgrade of the keys without downtime.

The following tutorial steps through the process to update, without any downtime, the key for a sharded cluster. [1]

Warning

The example keys in this tutorial are for illustrative purposes only. Do NOT use for your deployement. Instead, generate a keyfile using any method you choose (e.g. openssl rand -base64 756, etc.).

Consider a sharded cluster where each member’s keyfile contains the following key:

The following procedure updates the sharded cluster members to use a new key:

[1]	This tutorial is not applicable to the keyfile used for the MongoDB’s encrypted storage engine local key management. That keyfile can only contain a single key.

Procedure

1. Modify the Keyfile to Include Old and New Keys

Modify each member’s keyfile to include both the old and new keys. You can specify multiple keys either as strings enclosed in quotes or as a sequence of keys.

Warning

The example keys in this tutorial are for illustrative purposes only. Do NOT use for your deployement. Instead, generate a keyfile using any method you choose (e.g. openssl rand -base64 756, etc.).

• Multiple Key Strings
• Multiple Key Sequence

You can specify multiple key strings where each key string is enclosed in quotes

You can specify multiple key strings as a sequence of key strings (optionally enclosed in quotes):

2. Restart Each Member

Once all the keyfiles contain both the old and new keys, restart each member one at a time.

Config Servers

For each secondary of the config server replica set (CSRS), connect a mongo shell to the member and:

1. Use the db.shutdownServer() method to shut down the member:

   copy

   use admin
   db.shutdownServer()
   

2. Restart the member.

For the primary, connect a mongo shell to the member and

1. Use rs.stepDown() to step down the member:

   copy

   rs.stepDown()
   

2. Use the db.shutdownServer() method to shut down the member:

   copy

   use admin
   db.shutdownServer()
   

3. Restart the member.

Shard Replica Sets

For each secondary member of the shard replica sets, connect a mongo shell to the member and:

1. Use the db.shutdownServer() method to shut down the member:

   copy

   use admin
   db.shutdownServer()
   

2. Restart the member.

For the primary of each shard replica set, connect a mongo shell to the member and

1. Use rs.stepDown() to step down the member:

   copy

   rs.stepDown()
   

2. Use the db.shutdownServer() method to shut down the member:

   copy

   use admin
   db.shutdownServer()
   

3. Restart the member.

mongos Routers

For each mongos/router instance, connect a mongo shell to the mongos instance and:

1. Use the db.shutdownServer() method to shut down the member:

   copy

   use admin
   db.shutdownServer()
   

2. Restart the member.

Once all members have been restarted, the members now accept either the old or new key for membership authentication.

3. Update Keyfile Content to the New Key Only

Warning

The example keys in this tutorial are for illustrative purposes only. Do NOT use for your deployement. Instead, generate a keyfile using any method you choose (e.g. openssl rand -base64 756, etc.).

Modify each member’s keyfile to include only the new password.

4. Restart Each Member

Once all the keyfiles contain the new key only, restart each member one at a time.

Config Servers

For each secondary of the config server replica set (CSRS), connect a mongo shell to the member and:

1. Use the db.shutdownServer() method to shut down the member:

   copy

   use admin
   db.shutdownServer()
   

2. Restart the member.

For the primary, connect a mongo shell to the member and

1. Use rs.stepDown() to step down the member:

   copy

   rs.stepDown()
   

2. Use the db.shutdownServer() method to shut down the member:

   copy

   use admin
   db.shutdownServer()
   

3. Restart the member.

Shard Replica Sets

For each secondary member of the shard replica sets, connect a mongo shell to the member and:

1. Use the db.shutdownServer() method to shut down the member:

   copy

   use admin
   db.shutdownServer()
   

2. Restart the member.

For the primary of each shard replica set, connect a mongo shell to the member and

1. Use rs.stepDown() to step down the member:

   copy

   rs.stepDown()
   

2. Use the db.shutdownServer() method to shut down the member:

   copy

   use admin
   db.shutdownServer()
   

3. Restart the member.

mongos Routers

For each mongos/router instance, connect a mongo shell to the mongos instance and:

1. Use the db.shutdownServer() method to shut down the member:

   copy

   use admin
   db.shutdownServer()
   

2. Restart the member.

Once all members have been restarted, the members now accept only the new key for membership authentication.

←   Update Sharded Cluster to Keyfile Authentication (No Downtime) Use x.509 Certificate for Membership Authentication  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.