Performing Graceful Failover

  • reference
    Graceful failover can be performed by means of the REST API.

    HTTP method and URI

    POST /controller/startGracefulFailover


    Initiates graceful failover for one or more server nodes. The Full Admin or Cluster Admin role is required.

    Curl Syntax

    POST /controller/startGracefulFailover
        [ -d <node-to-be-gracefully-failed-over> ]

    Each server node to be gracefully failed over is specified with the <node-to-be-gracefully-failed-over> parameter. This must consist of the string otpNode=ns_1@ followed by the IP address or domain-name of the node. If multiple nodes are to be gracefully failed over, each should be specified separately, with multiple occurrences of the -d flag.

    Note that the progress of graceful failover can be tracked: see Getting Cluster Tasks.

    Subsequent to a successful graceful failover, the cluster must be rebalanced. See Rebalance.


    Success returns 200 OK. Failure to specify a node correctly returns 400 Bad Request, and an error message such as Unknown server given: ["ns_1@"]. Failure to authenticate returns 401 Unauthorized. Incorrect specification of the URI returns 404 Object Not Found.


    The following example gracefully fails over two nodes from a cluster.

    curl -u Administrator:password  \  \
    -d otpNode=ns_1%4010.144.220.103  \
    -d otpNode=ns_1%4010.144.220.104

    If graceful failover is successfully initiated and completed, the cluster should then be rebalanced, specifying all nodes in the cluster (including those gracefully failed over) as knownNodes, and additionally specifying those gracefully failed over as ejectedNodes. For example:

    curl  -u Administrator:password -v -X POST \ \
    -d 'knownNodes=ns_1@,ns_1@,ns_1@,ns_1@,ns_1@'

    See Also

    For a conceptual overview of nodes and their management, see Nodes. For practical examples of node management by means of UI, CLI, and REST API, see Manage Nodes and Clusters.

    For information on tracking an ongoing graceful failover, see Getting Cluster Tasks. For information on rebalancing a cluster with the REST API, see Rebalance.