{
  "id": "maintenance-mode",
  "title": "Maintenance mode for cluster nodes",
  "url": "https://redis.io/docs/latest/operate/rs/7.8/clusters/maintenance-mode/",
  "summary": "Prepare a cluster node for maintenance.",
  "content": "\nUse maintenance mode to prevent data loss during hardware patching or operating system maintenance on Redis Enterprise servers. When maintenance mode is on, all shards move off of the node under maintenance and migrate to another available node.\n\n## Activate maintenance mode\n\nWhen you activate maintenance mode, Redis Enterprise does the following:\n\n1. Checks whether the cluster has enough active nodes to maintain quorum if one goes down. If taking a node offline would cause quorum loss, maintenance mode will not activate.\n\n    \nThis check does not consider if other nodes are already in maintenance mode. Do not put the majority of nodes into maintenance mode and restart them simultaneously, as this can cause the cluster to lose quorum and lead to data loss.\n    \n\n1. If no maintenance mode snapshots already exist or if you use `overwrite_snapshot` when you activate maintenance mode, Redis Enterprise creates a new node snapshot that records the node's shard and endpoint configuration.\n\n1. Marks the node as a quorum node to prevent shards and endpoints from migrating to it.\n\n    At this point, [`rladmin status`]() displays the node's shards field in yellow, which indicates that shards cannot migrate to the node.\n\n    \n\n1. Migrates shards and binds endpoints to other nodes, when space is available.\n\nMaintenance mode does not demote a master node by default. The cluster elects a new master node when the original master node restarts. \n\nAdd the `demote_node` option to the `rladmin` command to [demote a master node](#demote-a-master-node) when you activate maintenance mode.\n\nTo activate maintenance mode for a node, run the following command:\n\n```sh\nrladmin node \u003cnode_id\u003e maintenance_mode on overwrite_snapshot\n```\n\nYou can start server maintenance if:\n\n- All shards and endpoints have moved to other nodes\n\n- Enough nodes are still online to maintain quorum\n\n### Prevent replica shard migration\n\nIf you do not have enough resources available to move all of the shards to other nodes, you can turn maintenance mode on without migrating the replica shards.\n\nBefore you prevent replica shard migration during maintenance mode, consider the following effects:\n\n- Replica shards remain on the node during maintenance.\n\n- If the maintenance node fails, the master shards do not have replica shards to maintain data redundancy and high availability.\n\n- Replica shards that remain on the node can still be promoted during failover to preserve availability.\n\nTo activate maintenance mode without replica shard migration, run:\n\n```sh\nrladmin node \u003cnode_id\u003e maintenance_mode on evict_ha_replica disabled evict_active_active_replica disabled\n```\n\n### Demote a master node\n\nIf maintenance might affect connectivity to the master node, you can demote the master node when you  activate maintenance mode.  This lets the cluster elect a new master node.\n\nTo demote a master node when activating maintenance mode, run:\n\n```sh\nrladmin node \u003cnode_id\u003e maintenance_mode on demote_node\n```\n\n### Verify maintenance mode activation\n\nTo verify maintenance mode for a node, use `rladmin status` and review the node's shards field.  If that value is displayed in yellow (shown earlier), then the node is in maintenance mode.\n\nAvoid activating maintenance mode when it is already active.  Maintenance mode activations stack.  If you activate maintenance mode for a node that is already in maintenance mode, you will have to deactivate maintenance mode twice in order to restore full functionality.\n\n## Deactivate maintenance mode\n\nWhen you deactivate maintenance mode, Redis Enterprise:\n\n1. Loads a [specified node snapshot](#specify-a-snapshot) or defaults to the latest maintenance mode snapshot.\n\n1. Unmarks the node as a quorum node to allow shards and endpoints to migrate to the node.\n\n1. Restores the shards and endpoints that were in the node at the time of the snapshot.\n\n1. Deletes the snapshot.\n\nTo deactivate maintenance mode after server maintenance, run:\n\n```sh\nrladmin node \u003cnode_id\u003e maintenance_mode off\n```\n\nBy default, a snapshot is required to deactivate maintenance mode.  If the snapshot cannot be restored, deactivation is cancelled and the node remains in maintenance mode.  In such events, it may be necessary to [reset node status](#reset_node_status).\n\n### Specify a snapshot\n\nWhen you turn off maintenance mode, you can restore the node configuration from a maintenance mode snapshot or any snapshots previously created by [`rladmin node \u003cnode_id\u003e snapshot create`](). If you do not specify a snapshot, Redis Enterprise uses the latest maintenance mode snapshot by default.\n\nTo get a list of available snapshots, run:\n\n```sh\nrladmin node \u003cnode_id\u003e snapshot list\n```\n\nTo specify a snapshot when you turn maintenance mode off, run:\n\n```sh\nrladmin node \u003cnode_id\u003e maintenance_mode off snapshot_name \u003csnapshot_name\u003e\n```\n\n\nIf an error occurs when you turn on maintenance mode, the snapshot is not deleted.\nWhen you rerun the command, use the snapshot from the initial attempt since it contains the original state of the node.\n\n\n### Skip shard restoration\n\nYou can prevent the migrated shards and endpoints from returning to the original node after you turn off maintenance mode.\n\nTo turn maintenance mode off and skip shard restoration, run:\n\n```sh\nrladmin node \u003cnode_id\u003e maintenance_mode off skip_shards_restore\n```\n\n### Reset node status\n\nIn extreme cases, you may need to reset a node's status.  Run the following commands to do so:\n\n```\n$ rladmin tune node \u003cnode_id\u003e max_listeners 100\n$ rladmin tune node \u003cnode_id\u003e quorum_only disabled\n```\n\nUse these commands with caution.  For best results, contact Support before running these commands.\n\n## Cluster status example\n\nThis example shows how the output of [`rladmin status`]() changes when you turn on maintenance mode for a node.\n\nThe cluster status before turning on maintenance mode:\n\n```sh\nredislabs@rp1_node1:/opt$ rladmin status\nCLUSTER NODES:\nNODE:ID   ROLE     ADDRESS       EXTERNAL_ADDRESS     HOSTNAME    SHARDS\n*node:1   master   172.17.0.2                         rp1_node1   2/100\nnode:2    slave    172.17.0.4                         rp3_node1   2/100\nnode:3    slave    172.17.0.3                         rp2_node1   0/100\n```\n\nThe cluster status after turning on maintenance mode:\n\n```sh\nredislabs@rp1_node1:/opt$ rladmin node 2 maintenance_mode on\nPerforming maintenance_on action on node:2: 0%\ncreated snapshot NodeSnapshot\u003cname=maintenance_mode_2019-03-14_09-50-59,time=None,node_uid=2\u003e\n\nnode:2 will not accept any more shards\nPerforming maintenance_on action on node:2: 100%\nOK\nredislabs@rp1_node1:/opt$ rladmin status\nCLUSTER NODES:\nNODE:ID   ROLE     ADDRESS       EXTERNAL_ADDRESS     HOSTNAME    SHARDS\n*node:1   master   172.17.0.2                         rp1_node1   2/100\nnode:2    slave    172.17.0.4                         rp3_node1   0/0\nnode:3    slave    172.17.0.3                         rp2_node1   2/100\n```\n\nAfter turning on maintenance mode for node 2, Redis Enterprise saves a snapshot of its configuration and then moves its shards and endpoints to node 3.\n\nNow node 2 has `0/0` shards because shards cannot migrate to it while it is in maintenance mode.\n\n## Maintenance mode REST API\n\nYou can also turn maintenance mode on or off using [REST API requests]() to [\u003cnobr\u003ePOST `/nodes/{node_uid}/actions/{action}`\u003c/nobr\u003e]().\n\n### Activate maintenance mode (REST API)\n\nUse \u003cnobr\u003e`POST /nodes/{node_uid}/actions/maintenance_on`\u003c/nobr\u003e to activate maintenance mode:\n\n```sh\nPOST https://\u003chostname\u003e:9443/v1/nodes/\u003cnode_id\u003e/actions/maintenance_on\n{\n    \"overwrite_snapshot\": true,\n    \"evict_ha_replica\": true,\n    \"evict_active_active_replica\": true\n}\n```\n\nYou can set `evict_ha_replica` and `evict_active_active_replica` to `false` to [prevent replica shard migration](#prevent-replica-shard-migration).\n\nThe `maintenance_on` request returns a JSON response body:\n\n```json\n{\n    \"status\":\"queued\",\n    \"task_id\":\"\u003ctask-id-guid\u003e\"\n}\n```\n\n### Deactivate maintenance mode (REST API)\n\nUse \u003cnobr\u003e`POST /nodes/{node_uid}/actions/maintenance_off`\u003c/nobr\u003e deactivate maintenance mode:\n\n```sh\nPOST https://\u003chostname\u003e:9443/v1/nodes/\u003cnode_id\u003e/actions/maintenance_off\n{ \"skip_shards_restore\": false }\n```\n\nThe `skip_shards_restore` boolean flag allows the `maintenance_off` action to [skip shard restoration](#skip-shard-restoration) when set to `true`.\n\nThe `maintenance_off` request returns a JSON response body:\n\n```json\n{\n    \"status\":\"queued\",\n    \"task_id\":\"\u003ctask-id-guid\u003e\"\n}\n```\n\n### Track action status\n\nYou can send a request to [\u003cnobr\u003eGET `/nodes/{node_uid}/actions/{action}`\u003c/nobr\u003e]() to track the [status]() of the `maintenance_on` and `maintenance_off` actions.\n\nThis request returns the status of the `maintenance_on` action:\n\n```sh\nGET https://\u003chostname\u003e:9443/v1/nodes/\u003cnode_id\u003e/actions/maintenance_on\n```\n\nThe response body:\n\n```json\n{\n    \"status\":\"completed\",\n    \"task_id\":\"38c7405b-26a7-4379-b84c-cab4b3db706d\"\n}\n```\n",
  "tags": ["docs","operate","rs"],
  "last_updated": "2026-04-01T08:10:08-05:00"
}