Node actions requests

Node action requests

Get all actions

GET /v1/nodes/actions

Get the status of all currently executing, pending, or completed actions on all nodes.

Permissions

Request

Example HTTP request

GET /nodes/actions

Request headers

Response

Returns a list of action objects.

Status codes

Get node actions statuses

GET /v1/nodes/{node_uid}/actions

Get the status of all actions on a specific node.

Required permissions

Request

Example HTTP request

GET /nodes/1/actions

Request headers

URL parameters

Response

Returns a JSON object that includes a list of action objects for the specified node.

If no actions are available, the response will include an empty array.

Example JSON body

{
    "actions": [
        {
            "name": "remove_node",
            "node_uid": "1",
            "status": "running",
            "progress": 10
        }
    ]
}

Error codes

Status codes

Get node action status

GET /v1/nodes/{node_uid}/actions/{action}

Get the status of a currently executing, queued, or completed action on a specific node.

Request

Example HTTP request

GET /nodes/1/actions/remove

Headers

Response

Returns an action object for the specified node.

Error codes

Status codes

Initiate node action

POST /v1/nodes/{node_uid}/actions/{action}

Initiate a node action.

The API allows only a single instance of any action type to be invoked at the same time, and violations of this requirement will result in a 409 CONFLICT response.

The caller is expected to query and process the results of the previously executed instance of the same action, which will be removed as soon as the new one is submitted.

Permissions

Request

Example HTTP request

POST /nodes/1/actions/remove

Headers

URL parameters

Currently supported actions are:

• remove: Removes the node from the cluster after migrating all bound resources to other nodes. As soon as a successful remove request is received, the cluster will no longer automatically migrate resources, such as shards and endpoints, to the node even if the remove task fails at some point.

  • By default, the remove node action completes after all resources migrate off the removed node. Node removal does not wait for migrated shards' persistence files to be created on the new nodes.

    To change node removal to wait for the creation of new persistence files for all migrated shards, set wait_for_persistence to true in the request body or update the cluster policy persistent_node_removal to true to change the cluster's default behavior.

    POST /v1/nodes/<node_id>/actions/remove
    {
        "wait_for_persistence": true
    }
    

• maintenance_on: Creates a snapshot of the node, migrates shards to other nodes, and prepares the node for maintenance. See maintenance mode for more information.

  • As of Redis Enterprise Software version 7.4.2, a new node snapshot is created only if no maintenance mode snapshots already exist or if you set "overwrite_snapshot": true in the request body.

    POST /v1/nodes/1/actions/maintenance_on
    {
        "overwrite_snapshot": true
    }
    

  • If there aren't enough resources to migrate shards out of the maintained node, set "evict_ha_replica": false and "evict_active_active_replica": false in the request body to keep the replica shards in place but demote any master shards. Use these two parameters instead of keep_slave_shards, which is deprecated as of Redis Enterprise Software version 7.4.2.

    POST /v1/nodes/1/actions/maintenance_on
    {
        "overwrite_snapshot": true,
        "evict_ha_replica": false,
        "evict_active_active_replica": false
    }
    

  • To specify databases whose shards should be evicted from the node when entering maintenance mode, set "evict_dbs": ["List of database ID strings"] in the request body.

    POST /v1/nodes/1/actions/maintenance_on
    {
        "overwrite_snapshot": true,
        "evict_dbs": ["1", "3"] 
    }
    

• maintenance_off: Restores node to its previous state before maintenance started. See maintenance mode for more information.

  • By default, it uses the latest node snapshot.

  • Use "snapshot_name": "..." in the request body to restore the state from a specific snapshot.

  • To avoid restoring shards at the node, use "skip_shards_restore": true.

• enslave_node: Turn node into a replica.

Response

The body content may provide additional action details.

Status codes

Example requests

cURL

$ curl -k -X POST -u "[username]:[password]" -d "{}"
            https://[host][:port]/v1/nodes/1/actions/remove

Python

import requests
import json

url = "https://[host][port]/v1/nodes/1/actions/remove"

payload = json.dumps({})
headers = {
  'Content-Type': 'application/json',
}
auth = ("[username]", "[password]")

response = requests.request("POST", url, auth=auth, headers=headers, data=payload)

print(response.text)

Cancel action

DELETE /v1/nodes/{node_uid}/actions/{action}

Cancel a queued or executing node action, or remove the status of a previously executed and completed action.

Permissions

Request

Example HTTP request

DELETE /nodes/1/actions/remove

Headers

URL parameters

Response

Returns a status code.

Status codes