MarkLogic 9 Product DocumentationPOST /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. |
| 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 themanage-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.