Configuring a Cluster

This section describes some of the basic configuration tasks for a cluster. When you have a cluster, you can perform most administrative tasks from the Admin Interface of any node in the cluster. This section describes some of those cluster tasks and includes the following sections:

• Determining Which Nodes Are in Which Group in a Cluster
• Adding Another Node to a Cluster
• Removing a Node from a Cluster
• Upgrading a Cluster to a New Maintenance Release of MarkLogic Server

Determining Which Nodes Are in Which Group in a Cluster

The Admin Interface has summary and status screens to help you determine the makeup of a cluster. The system summary page (the default Admin Interface page when you log in) has links to each group and to each host in the cluster. If you have a cluster with multiple groups configured and you click on a group, the Admin Interface displays a group summary page which shows all of the hosts in a group. For each group, there is also a status page.

Similarly, each host has a summary page and a status page. For more details about the status pages, see Monitoring MarkLogic Server Performance in Query Performance and Tuning.

Adding Another Node to a Cluster

This section describes the general procedure for adding a new node to an existing cluster. For more detailed installation instructions, including the procedure to add a new node to a cluster, see Install MarkLogic Server.

The following are the general steps needed to add another node to an existing cluster (the existing cluster can have one or more hosts):

1. Install MarkLogic Server on the new host. All hosts in the cluster must run the same version of MarkLogic Server.

2. Access the Admin Interface on the new host. For example, if the host is installed on a machine named raymond, access http://raymond:8001.

3. On the License Key Entry page, enter a valid licensee and corresponding license key. The license keys are specific to a named machine. MarkLogic Server will restart after you enter the license key.

4. Accept the license agreement. MarkLogic Server will restart after you accept the license agreement.

   Important:
   
   Accepting this license agreement is optional. However, to begin using MarkLogic Server, you must accept the terms and conditions outlined in the license agreement. If you have executed a written software license with MarkLogic Corporation, the agreement displayed references that written agreement.

5. On the Server Install page, click OK to install the initial servers. MarkLogic Server will restart after you click OK.

6. On the Join a Cluster page, enter the name of any host in the cluster, with the port number of its Admin Interface. Then Click the OK button.

7. On the next Join a Cluster page, select the group to which you want to join. Then Click the OK button.

8. On the next Join a Cluster page, click OK to confirm that you want to join a cluster.

9. On the Joined a Cluster page, click OK to transfer cluster information to the new node in the cluster. MarkLogic Server will restart on the new node after you click OK.

10. After the MarkLogic Server restarts on the node, it prompts you for a username and password. Enter a username and password for the Admin Interface.

The new node is now part of the cluster.

Removing a Node from a Cluster

If you want to remove a node from a cluster, you must log into the Admin Interface for that node, go to its host configuration page and click the leave button.

Before you remove a node from a cluster, make sure it is not hosting any forests for the cluster (the forest summary page shows this information) or is not acting as a failover host for any forests. Additionally, make sure it is not coupled to any other hosts as a foreign cluster. You must resolve any forest dependencies with other hosts and de-couple any foreign clusters before you can remove a host from the cluster; the Admin Interface will not allow you to remove a host from the cluster if there are other hosts depending on it, and it will attempt to help you to resolve the dependencies. That might involve removing the host as a failover host, detaching the forest from the database, or assigning the forest to another d-node. For details about managing forests, see Administrate MarkLogic Server.

Perform the following basic procedure to remove a host from a cluster:

1. Access the Admin Interface for the node you want to remove from the cluster.

2. Navigate to the host configuration page for the host, either through the tree menu (the Configure tab under Hosts > host_name) or from one of the summary pages.

3. To leave the cluster, click the leave button. The leave button only appears when you are using the Admin Interface on which the host machine is running. On the Admin Interface on other nodes in the cluster, there is an admin button, which is a link to open the Admin Interface running on that host.

4. On the Leave Cluster page, click OK to confirm. MarkLogic Server on that host will restart, and the host is removed from the cluster.

At this point, the installation process will begin again (although you will not have to reenter the license key information). You can choose to join the cluster again, join another cluster, or skip the cluster installation and install as a stand-alone host.

Upgrading a Cluster to a New Maintenance Release of MarkLogic Server

Each host in a MarkLogic cluster must run the same version of the MarkLogic software. Therefore, if you install a maintenance release, you need to install it on all of the hosts in the cluster.

The upgrade installation is relatively quick, and should require only a small amount of cluster down time. It does require each host to shut down, uninstall, reinstall, and start up, however.

For a more detailed upgrade procedure, see Install MarkLogic Server. The general procedure for upgrading a cluster is as follows:

1. Download the maintenance release of MarkLogic you plan on installing. Make sure to download the correct release for your platform.

2. Shut down all of the hosts in the cluster. For example, on the Cluster Status page, click the Shutdown button.

3. After the hosts have finished shutting down, uninstall each instance of MarkLogic Server (from the Add/Remove Programs Control Panel on Windows, with rpm -e MarkLogic on Red Hat Linux, and with pkgrm MARKlogic on Solaris). For details, see Install MarkLogic Server.

4. Install the new release of MarkLogic Server on each host (with the installer on Windows, rpm -i on Red Hat Linux, pkgadd MARKlogic on Solaris). For details, see Install MarkLogic Server.

5. Start up MarkLogic Server on the machine that hosts the security database.

6. Start up MarkLogic Server on all of the other hosts.

7. Access the Admin Interface on the machine in which the security database forest is hosted.

8. When prompted, enter the username and password.

9. If there is no configuration and/or security database upgrade and/or effective version change, you are done. If there is a configuration and/or security database upgrade and/or effective version change, the Admin Interface will prompt you to click OK to upgrade. Click OK.

When the Admin Interface returns, this concludes the upgrade, and the upgraded cluster is now available to accept requests.