Dynamic Hosts

Clusters that experience heavy transaction volume need additional e-nodes to be efficient. But permanently adding e-nodes to clusters whose transaction volume is not always heavy is expensive.

Dynamic hosts provide a way to add e-nodes to a cluster when transaction volume is heavy and disable them when transaction volume drops while preserving caches and other cluster configurations. Like other e-nodes, dynamic hosts do not store data. Unlike other e-nodes, dynamic hosts do not participate in the quorum.

A dynamic host joins a group that is enabled to allow dynamic hosts. The dynamic host presents its dynamic host token to the join host. The join host is a static host in the group's cluster whose Admin app server is enabled to authenticate cluster API tokens.

As soon as a dynamic host joins the group, it begins processing transactions until disabled. When re-enabled, it begins processing transactions again.

Revoking the dynamic host token prevents new dynamic hosts from joining the group.

Permanently removing a dynamic host prevents it from being re-enabled.

Enable a group to allow dynamic hosts

Enable a group to allow dynamic hosts to join in one of these ways:

• In the Admin Interface, set Allow Dynamic Hosts to true on the group’s configuration page.

• Use the JavaScript function admin.groupSetAllowDynamicHosts() with the allow-dynamic-hosts parameter set to TRUE.

• Use the XQuery function admin:group-set-allow-dynamic-hosts() with the allow-dynamic-hosts parameter set to TRUE.

• Use the REST API endpoint PUT /manage/v2/groups/{id|name}/properties.

Enable an Admin app server to authenticate tokens

Enable the join host's Admin app server to authenticate dynamic host tokens in one of these ways:

• In the Admin Interface, set API Token Authentication to true on the app server's configuration page.

• Use the JavaScript function admin.appserverSetAPITokenAuthentication().

• Use the XQuery function admin:appserver-set-API-token-authentication().

• Use the REST API endpoint PUT /manage/v2/servers/{id|name}/properties.

Install MarkLogic Server

Install MarkLogic Server onto each dynamic host machine.

Generate a dynamic host token

Generate a dynamic host token in one of these ways:

• In the Admin Interface, generate a dynamic host token.

• Use the JavaScript function admin.issueDynamicHostToken().

• Use the XQuery function admin:issue-dynamic-host-token().

• Use the REST API endpoint POST /manage/v2/clusters/{id|name}/dynamic-host-token.

View all active dynamic host tokens at any time.

Add a dynamic host

Dynamic hosts can be added to the group after these tasks are complete:

• The group is enabled to allow dynamic hosts to join.
• The join host Admin app server is enabled to authenticate tokens.
• MarkLogic Server is installed onto each machine to be used as a dynamic host.
• The dynamic host token is generated.

Add a dynamic host to the group by providing the dynamic host token to the machine in one of these ways:

• Add the token to the marklogic.conf file:

  1. Insert this line into each dynamic hosts’s marklogic.conf file:

     export MARKLOGIC_DYNAMIC_HOST_TOKEN=[generated token]

  2. Start MarkLogic Server on each dynamic host.

• Use a cURL command to post the token:

  1. Start MarkLogic Server on each dynamic host.
  2. Execute this command for each dynamic host:
     curl --anyauth -k -X POST -d '<init xmlns="http://marklogic.com/manage"><dynamic-host-token>[generated token]</dynamic-host-token></init>' -i -H "Content-type:application/xml" http://${DYNAMIC_HOST}:8001/admin/v1/init

After each dynamic host has joined the group, it is enabled and ready to accept incoming transactions.

Dynamic hosts remain configured until the cluster restarts or until they are explicitly removed.

View dynamic hosts

View which hosts are dynamic in one of these ways:

• In the Admin Interface on the Hosts Summary page, click Dynamic Hosts. The list of currently configured dynamic hosts appears.

• Use the JavaScript function xdmp.getDynamicHosts().

• Use the XQuery function xdmp:get-dynamic-hosts().

• Use the REST API endpoint GET /manage/v2/clusters/{id|name}/dynamic-hosts.

View dynamic host tokens

View all active dynamic host tokens in one of these ways:

• In the Admin Interface, view the tokens on the Manage Cluster API Tokens page.

• Use the JavaScript function admin.searchDynamicHostToken().

• Use the XQuery function admin:search-dynamic-host-token().

• Use the REST API endpoint GET /manage/v2/clusters/{id|name}/dynamic-host-token.

Disable a dynamic host

A dynamic host can be disabled by stopping MarkLogic Server on that host or by powering down the host machine.

A temporarily disabled dynamic host appears on the Dynamic Hosts page with a Disconnected status. This dynamic host can be re-enabled at any time until it is permanently removed.

Re-enable a dynamic host

Re-enable the dynamic host by starting its machine if necessary and restarting MarkLogic Server.

A dynamic host that has been permanently removed cannot be re-enabled.

Revoke a dynamic host token

Prevent further use of a dynamic host token by revoking it.

Revoke a dynamic host token in one of these ways:

• In the Admin Interface, click Revoke on the Manage Cluster API Tokens page.

• Use the JavaScript function admin.revokeDynamicHostToken().

• Use the XQuery function admin:revoke-dynamic-host-token().

• Use the REST API endpoint DELETE /manage/v2/clusters/{id|name}/dynamic-host-token.

Permanently remove a dynamic host

Permanently remove a dynamic host in one of these ways:

• In the Admin Interface, on the Hosts Summary page, follow these steps:

  1. Click Dynamic Hosts. The list of currently configured dynamic hosts appears.
  2. Click Remove for that host. The refreshed list no longer contains that host.

• Use the JavaScript function xdmp.removeDynamicHosts().

• Use the XQuery function xdmp:remove-dynamic-hosts().

• Use the REST API endpoint DELETE /manage/v2/clusters/{id|name}/dynamic-hosts.

Permanently remove all dynamic hosts in the cluster by restarting the cluster.