Loading TOC...

POST /admin/v1/cluster-config

Summary

Provide host or cluster configuration information suitable for adding a new host to an existing cluster.

URL Parameters
server-config The server configuration of a new host to be joined to this cluster. This parameter must be supplied as form data in the request body, and its value should be the output of a previous call to GET /admin/v1/server-config.
group The group of the new host. Supply this parameter as form data in the request body. Required with the server-config request parameter, not permitted otherwise.
zone Optional text describing the location of the new host, such as the name of an Amazon EC2 Availability Zone. Used by the Tiered Storage API to configure local disk failover. For details, see Tiered Storage in the Administrator's Guide. You can only use this parameter when the server-config request parameter is present.
Request Headers
Content-type The MIME type of the data in the request body. Must be x-www-form-urlencoded when the server-config parameter is present. Must be application/zip when server-config is not present.
Response Headers
Content-type The MIME type of the data in the response body. The response data is always application/xml.

Response

Upon success, MarkLogic Server returns a status code 202 (Accepted) if the request causes a restart, or status code 200 (OK) if the request does not cause a restart. The data in the response body depends on the context in which the request is made. For details, see the Usage notes.

If license key installation and basic initialization have not yet been done, the response payload will include a timestamp, but all other elements will be empty.

Required Privileges

This operation requires the manage-admin role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage-admin

Usage Notes

This request must be directed to the MarkLogic Server Admin Interface on port 8001. For example: http://localhost:8001/admin/v1/cluster-config.

This method is intended for use in the context of other REST Management API methods during cluster configuration. Any server-config input data should be obtained by a previous call to GET /admin/v1/server-config. Any cluster configuration data should be obtained by a previous call to POST /admin/v1/cluster-config. See the example for the full sequence of calls.

If you include the server-config request parameter, its value must be a server configuration from a host joining the cluster, and the request must be directed to a fully initialized host that is already a member of the cluster. In this case, MarkLogic Server verifies that security is initialized and responds with cluster configuration data that can be supplied to the new host in order to complete the cluster join operation. The input server configuration must be URL encoded. The data in the response body is the cluster configuration information in ZIP format.

If you do not include the server-config request parameter, this request must be sent to the host that is joining a cluster, and the POST body must contain cluster configuration data in ZIP format, obtained by a previous call to POST /admin/v1/cluster-config with the server-config parameter. In this case, MarkLogic Server verifies this host to be a new host (not already a member of the cluster and security has not been initialized), and then installs the supplied cluster configuration to complete the cluster join sequence. The joining host is restarted.

For details and a complete example, see Scripting Cluster Management in the Scripting Administrative Tasks Guide.

Example


$ curl --anyauth --user admin:password -X POST -d "group=Default" \
    --data-urlencode "server-config@./server-config.xml" \
    -H "Content-type: application/x-www-form-urlencoded" \
    -o ./cluster-config.zip http://cluster-host:8001/admin/v1/cluster-config

==> Retrieve the configuration of the bootstrap host for a cluster and save it
    to the file server-config.xml. MarkLogic Server responds with status 200 
    and a ZIP file containing the cluster configuration data to provide to the
    local host in order to complete the cluster join sequence.
  

Example


$ curl --anyauth --user admin:password -X POST \
    -d "group=Default" --data-binary @./cluster-config.zip \
    -H "Content-type: application/zip" \
    http://joining-host:8001/admin/v1/cluster-config

==> Send the cluster configuration ZIP file obtained by a previous 
    call to /admin/v1/cluster-config?server-config to a new host
    to complete the cluster join sequence. MarkLogic Server responds 
    with status code 202. A restart occurs.
  

Example


Use in the following sequence to add a host to a cluster, assuming
clusterhost is a previously fully initialized bootstrap host for
the cluster and joining-host is the host to be initialized and added to
the cluster:

(1) Initialize the new host. For details, see POST /admin/v1/init.
    Use GET /admin/v1/timestamp to verify a successful restart.
    For details, see POST /admin/v1/init.

    $ curl -X POST -d "" -i http://joining-host:8001/admin/v1/init
    $ curl -X GET http://joining-host:8001/admin/v1/timestamp

(2) Retrieve the configuration of the joining host, to be used as the
    value of the server-config param to POST /admin/v1/cluster-config.
    For details, see POST /admin/v1/server-config.

    $ curl -o joiner-config.xml -X GET -H "Accept: application/xml" \
        http://joining-host:8001/admin/v1/server-config

    ==> The configuration for joining-host is saved to joiner-config.xml.
        See the previous example for the output details.

(3) Send the joining host's URL encoded config info to the bootstrap host.
    Receive the cluster configuration in return. 

    $ curl --anyauth --user user:password -X POST -d "group=Default" \
        --data-urlencode "server-config@./joiner-config.xml" \
        -H "Content-type: application/x-www-form-urlencoded" \
        -o cluster-config.zip http://clusterhost:8001/admin/v1/cluster-config

    ==> The cluster configuration data is saved in cluster-config.zip.

(4) Send the cluster configuration ZIP file to the joining host to 
    complete the cluster join sequence. Bracket the POST with calls 
    to GET /admin/v1/timestamp to confirm a successful restart. 

    $ curl -X GET http://joining-host:8001/admin/v1/timestamp
    $ curl -X POST -H "Content-type: application/zip" \
        --data-binary @./cluster-config.zip \
        http://joining-host:8001/admin/v1/cluster-config
    $ curl --anyauth --user user:password -X GET \
        http://joining-host:8001/admin/v1/timestamp

    ==> The joining host becomes a functional member of the cluster.
  

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.