Provide host or cluster configuration information suitable for adding a new host to an existing cluster.
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
The group of the new host. Supply this parameter as form data in
the request body. Required with the
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 |
The MIME type of the data in the request body. Must be
The MIME type of the data in the response body. The response data
is always |
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.
manage-adminrole, or the following privilege:
This request must be directed to the MarkLogic Server Admin Interface
on port 8001. For example:
This method is intended for use in the context of other REST Management
API methods during cluster configuration. Any
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.
$ 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.
$ 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.
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.