Rotate Keys for Sharded Clusters
Sharded cluster members can use keyfilesto authenticate each other as memers of the same deployment.
Starting in version 4.2, a keyfile cancontain multiple keys and membership authentication is established ifat least one key is common across members. This allows for rollingupgrade of the keys without downtime.
The following tutorial steps through the process to update, without anydowntime, the key for a sharded cluster. [1]
Warning
The example keys in this tutorial are for illustrative purposesonly. Do NOT use for your deployement. Instead, generate akeyfile using any method you choose (e.g. openssl rand -base64756
, etc.).
Consider a sharded cluster where each member’s keyfile contains thefollowing key:
The following procedure updates the sharded cluster members to use anew key:
[1] | This tutorial is not applicable to the keyfile used for the MongoDB’s encryptedstorage engine local keymanagement. That keyfile can onlycontain 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. Youcan specify multiple keys either as strings enclosed in quotes or as asequence of keys.
Warning
The example keys in this tutorial are for illustrative purposesonly. Do NOT use for your deployement. Instead, generate akeyfile using any method you choose (e.g. openssl rand -base64756
, etc.).
- Multiple Key Strings
- Multiple Key Sequence
You can specify multiple key strings where each keystring is enclosed in quotes
You can specify multiple key strings as a sequence of keystrings (optionally enclosed in quotes):
2. Restart Each Member
Once all the keyfiles contain both the old and new keys, restart eachmember one at a time.
Config Servers
For each secondary of the config server replica set (CSRS),connect a mongo
shell to the member and:
- Use the
db.shutdownServer()
method to shut down the member:
- use admin
- db.shutdownServer()
- Restart the member.
For the primary, connect a mongo
shell to the member and
- Use
rs.stepDown()
to step down the member:
- rs.stepDown()
- Use the
db.shutdownServer()
method to shut down the member:
- use admin
- db.shutdownServer()
- Restart the member.
Shard Replica Sets
For each secondary member of the shard replica sets, connect amongo
shell to the member and:
- Use the
db.shutdownServer()
method to shut down the member:
- use admin
- db.shutdownServer()
- Restart the member.
For the primary of each shard replica set, connect amongo
shell to the member and
- Use
rs.stepDown()
to step down the member:
- rs.stepDown()
- Use the
db.shutdownServer()
method to shut down the member:
- use admin
- db.shutdownServer()
- Restart the member.
mongos Routers
For each mongos/router instance, connect amongo
shell to the mongos
instance and:
- Use the
db.shutdownServer()
method to shut down the member:
- use admin
- db.shutdownServer()
- Restart the member.
Once all members have been restarted, the members now accept either theold 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 purposesonly. Do NOT use for your deployement. Instead, generate akeyfile using any method you choose (e.g. openssl rand -base64756
, 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 oneat a time.
Config Servers
For each secondary of the config server replica set (CSRS),connect a mongo
shell to the member and:
- Use the
db.shutdownServer()
method to shut down the member:
- use admin
- db.shutdownServer()
- Restart the member.
For the primary, connect a mongo
shell to the member and
- Use
rs.stepDown()
to step down the member:
- rs.stepDown()
- Use the
db.shutdownServer()
method to shut down the member:
- use admin
- db.shutdownServer()
- Restart the member.
Shard Replica Sets
For each secondary member of the shard replica sets, connect amongo
shell to the member and:
- Use the
db.shutdownServer()
method to shut down the member:
- use admin
- db.shutdownServer()
- Restart the member.
For the primary of each shard replica set, connect amongo
shell to the member and
- Use
rs.stepDown()
to step down the member:
- rs.stepDown()
- Use the
db.shutdownServer()
method to shut down the member:
- use admin
- db.shutdownServer()
- Restart the member.
mongos Routers
For each mongos/router instance, connect amongo
shell to the mongos
instance and:
- Use the
db.shutdownServer()
method to shut down the member:
- use admin
- db.shutdownServer()
- Restart the member.
Once all members have been restarted, the members now accept only thenew key for membership authentication.