21.2.1.2 Using the NDB Cluster Auto-Installer

The NDB Cluster Auto-Installer consists of several pages, each corresponding to a step in the process used to configure and deploy an NDB Cluster, and listed here:

  • Welcome: Begin using the Auto-Installer by choosing either to configure a new NDB Cluster, or to continue configuring an existing one.

  • Define Cluster: Set basic information about the cluster as a whole, such as name, hosts, and load type. Here you can also set the SSH authentication type for accessing remote hosts, if needed.

  • Define Hosts: Identify the hosts where you intend to run NDB Cluster processes.

  • Define Processes: Assign one or more processes of a given type or types to each cluster host.

  • Define Attributes: Set configuration attributes for processes or types of processes.

  • Deploy Cluster: Deploy the cluster with the configuration set previously; start and stop the deployed cluster.

The following sections describe in greater detail the purpose and function of each of these pages, in the order just listed.

Starting the NDB Cluster Auto-Installer

The Auto-Installer is provided together with the NDB Cluster software. (See Section 21.2, “NDB Cluster Installation”.) The present section explains how to start the installer. You can do by invoking the ndb_setup.py executable.

Important

You should run the ndb_setup.py as a normal user; no special privileges are needed to do so. You should not run this program as the mysql user, or using the system root or Administrator account; doing so may cause the installation to fail.

ndb_setup.py is found in the bin within the NDB Cluster installation directory; a typical location might be /usr/local/mysql/bin on a Linux system or C:\Program Files\MySQL\MySQL Server 5.6\bin on a Windows system, but this can vary according to where the NDB Cluster software is installed on your system.

On Windows, you can also start the installer by running setup.bat in the NDB Cluster installation directory. When invoked from the command line, it accepts the same options as does ndb_setup.py.

ndb_setup.py can be started with any of several options that affect its operation, but it is usually sufficient to allow the default settings be used, in which case you can start ndb_setup.py by either of the following two methods:

  1. Navigate to the NDB Cluster bin directory in a terminal and invoke it from the command line, without any additional arguments or options, like this:

    shell> ndb_setup

    This works regardless of operating platform.

  2. Navigate to the NDB Cluster bin directory in a file browser (such Windows Explorer on Windows, or Konqueror, Dolphin, or Nautilus on Linux) and activate (usually by double-clicking) the ndb_setup.py file icon. This works on Windows, and should work with most common Linux desktops as well.

    On Windows, you can also navigate to the NDB Cluster installation directory and activate the setup.bat file icon.

In either case, once ndb_setup.py is invoked, the Auto-Installer's Welcome screen should open in the system's default Web browser.

In some cases, you may wish to use non-default settings for the installer, such as specifying a different port for the Auto-Installer's included Web server to run on, in which case you must invoke ndb_setup.py with one or more startup options with values overriding the necessary defaults. The same startup options can be used on Windows systems with the setup.bat file supplied for such platforms in the NDB Cluster software distribution. This can be done using the command line, but if you want or need to start the installer from a desktop or file browser while emplying one or more of these options, it is also possible to create a script or batch file containing the proper invocation, then to double-click its file icon in the file browser to start the installer. (On Linux systems, you might also need to make the script file executable first.) For information about advanced startup options for the NDB Cluster Auto-Installer, see Section 21.4.27, “ndb_setup.py — Start browser-based Auto-Installer for NDB Cluster”.

NDB Cluster Auto-Installer Welcome Screen

The Welcome screen is loaded in the default browser when ndb_setup.py is invoked, as shown here:

Figure 21.5 The NDB Cluster Auto-Installer Welcome screen (Closeup)

Content is described in the surrounding text.

This screen provides the following two choices for entering the installer, one of which must be selected to continue:

  1. Create New NDB Cluster: Start the Auto-Installer with a completely new cluster to be set up and deployed.

  2. Continue Previous Cluster Configuration: Start the Auto-Installer at the same point where the previous session ended, with all previous settings preserved.

The second option requires that the browser be able to access its cookies from the previous session, as these provide the mechanism by which configuration and other information generated during a session is stored. In other words, to continue the previous session with the Auto-Installer, you must use the same web browser running on the same host as you did for the previous session.

NDB Cluster Auto-Installer Define Cluster Screen

The Define Cluster screen is the first screen to appear following the choice made in the Welcome screen, and is used for setting general properties of the cluster. The layout of the Define Cluster screen is shown here:

Figure 21.6 The NDB Cluster Auto-Installer Define Cluster screen

Content is described in the surrounding text.

The Define Cluster screen allows you to set a number of general properties for the cluster, as described in this list:

  • Cluster name: A name that identifies the cluster. The default is MyCluster.

  • Host list: A comma-delimited list of one or more hosts where cluster processes should run. By default, this is 127.0.0.1. If you add remote hosts to the list, you must be able to connect to them using the SSH Credentials supplied.

  • Application type: Choose one of the following:

    1. Simple testing: Minimal resource usage for small-scale testing. This the default. Not intended for production environments.

    2. Web: Maximize performance for the given hardware.

    3. Real-time: Maximize performance while maximizing sensitivity to timeouts in order to minimize the time needed to detect failed cluster processes.

  • Write load: Choose a level for the anticipated number of writes for the cluster as a whole. You can choose any one of the following levels:

    1. Low: The expected load includes fewer than 100 write transactions for second.

    2. Medium: The expected load includes 100 to 1000 write transactions per second.

    3. High: The expected load includes more than 1000 write transactions per second.

  • SSH Credentials: Choose Key-Based SSH or enter User and Password credentials. The SSH key or a user name with password is required for connecting to any remote hosts specified in the Host list. By default, Key-Based SSH is selected, and the User and Password fields are blank.

NDB Cluster Auto-Installer Define Hosts Screen

The Define Hosts screen, shown here, provides a means of viewing and specifying several key properties of each cluster host:

Figure 21.7 NDB Cluster Define Hosts screen

Content is described in the surrounding text.

The hosts currently entered are displayed in the grid with various pieces of information. You can add hosts by clicking the Add hosts button and entering a list of one or more comma-separated host names, IP addresses, or both (as when editing the host list on the Define Cluster screen).

Similarly, you can remove one or more hosts using the button labelled Remove selected host(s). When you remove a host in this fashion, any process which was configured for that host is also removed.

If Automatically get resource information for new hosts is checked in the Settings menu, the Auto-Installer attempts to retrieve the platform name, amount of memory, and number of CPU cores and to fill these in automatically. The status of this is displayed in the Resource info column. Fetching the information from remote hosts is not instantaneous and may take some time, particularly from remote hosts running Windows.

If the SSH user credentials on the Define Cluster screen are changed, the tool tries to refresh the hardware information from any hosts for which information is missing. However, if a given field has already been edited, the user-supplied information is not overwritten by any value fetched from that host.

The hardware resource information, platform name, installation directory, and data directory can be edited by the user by clicking the corresponding cell in the grid, by selecting one or more hosts and clicking the button labelled Edit selected host(s). This causes a dialog box to appear, in which these fields can be edited, as shown here:

Figure 21.8 NDB Cluster Auto-Installer Edit Hosts dialog

Content is described in the surrounding text.

When more than one host is selected, any edited values are applied to all selected hosts.

NDB Cluster Auto-Installer Define Processes Screen

The Define Processes screen, shown here, provides a way to assign NDB Cluster processes (nodes) to cluster hosts:

Figure 21.9 NDB Cluster Auto-Installer Define Processes dialog

Content is described in the surrounding text. The example process tree topology includes "Any host" and "127.0.0.1", as defined earlier. The 127.0.0.1 example includes the following processes: Management mode 1, API node 1, API node 2, API node 3, SQL node 1, SQL node 2, Multi threaded data node 1, and Multi threaded data node 2. This panel also includes "Add process" and "Delete process" buttons.

This screen contains a process tree showing cluster hosts and processes set up to run on each one, as well as a panel which displays information about the item currently selected in the tree.

When this screen is accessed for the first time for a given cluster, a default set of processes is defined for you, based on the number of hosts. If you later return to the Define Hosts screen, remove all hosts, and add new hosts, this also causes a new default set of processes to be defined.

NDB Cluster processes are of the following types:

  • Management node.  Performs administrative tasks such as stopping individual data nodes, querying node and cluster status, and making backups. Executable: ndb_mgmd.

  • Single-threaded data node.  Stores data and executes queries. Executable: ndbd.

  • Multi threaded data node.  Stores data and executes queries with multiple worker threads executing in parallel. Executable: ndbmtd.

  • SQL node.  MySQL server for executing SQL queries against NDB. Executable: mysqld.

  • API node.  A client accessing data in NDB by means of the NDB API or other low-level client API, rather than by using SQL. See MySQL NDB Cluster API Developer Guide , for more information.

For more information about process (node) types, see Section 21.1.1, “NDB Cluster Core Concepts”.

Processes shown in the tree are numbered sequentially by type, for each host—for example, SQL node 1, SQL node 2, and so on—to simplify identification.

Each management node, data node, or SQL process must be assigned to a specific host, and is not allowed to run on any other host. An API node may be assigned to a single host, but this is not required. Instead, you can assign it to the special Any host entry which the tree also contains in addition to any other hosts, and which acts as a placeholder for processes that are allowed to run on any host. Only API processes may use this Any host entry.

Adding processes.  To add a new process to a given host, either right-click that host's entry in the tree, then select the Add process popup when it appears, or select a host in the process tree, and press the Add process button below the process tree. Performing either of these actions opens the add process dialog, as shown here:

Figure 21.10 NDB Cluster Auto-Installer Add Process Dialog

Most content is described in the surrounding text. Shows a window titled "Add new process" with two options: "Select process type:" that shows a select box with "API node" selected, and "Enter process name:" with "API node 4" entered as plain text. Action buttons include "Cancel" and "Add".

Here you can select from among the available process types described earlier this section; you can also enter an arbitrary process name to take the place of the suggested value, if desired.

Removing processes.  To delete a process, right-click on a process in the tree and select delete process from the pop up menu that appears, or select a process, then use the delete process button below the process tree.

When a process is selected in the process tree, information about that process is displayed in the information panel, where you can change the process name and possibly its type. Important: Currently, you can change a single-threaded data node (ndbd) to a multithreaded data node (ndbmtd), or the reverse, only; no other process type changes are allowed. If you want to make a change between any other process types, you must delete the original process first, then add a new process of the desired type.

NDB Cluster Auto-Installer Define Attributes Screen

This screen has a layout similar to that of the Define Processes screen, including a process tree. Unlike that screen's tree, the Define Attributes process tree is organized by process or node type, with single-threaded and multithreaded data nodes considered to be of the same type for this purpose, in groups labelled Management Layer, Data Layer, SQL Layer, and API Layer. An information panel displays information regarding the item currently selected. The Define Attributes screen is shown here:

Figure 21.11 NDB Cluster Auto-Installer Define Attributes screen

Content is described in the surrounding text.

The checkbox labelled Show advanced configuration, when checked, makes advanced options visible in the information pane. These options are set and used whether or not they are visible.

You can edit attributes for a single process by selecting that process from the tree, or for all processes of the same type in the cluster by selecting one of the Layer folders. A per-process value set for a given attribute overrides any per-group setting for that attribute that would otherwise apply to the process in question. An example of such an information panel (for an SQL process) is shown here:

Figure 21.12 Define Attributes Detail With SQL Process Attributes

Most content is described in the surrounding text. SQL Node 1 is selected and displays property fields for "NodeId", "HostName", "DataDir", "Port", and "Socket". The "DataDir", "Port", and "Socket" rows include a green plus sign button on the right indicating that they can be edited.

For some of the attributes shown in the information panel, a button bearing a plus sign is displayed, which means that the value of the attribute can be overridden. This + button activates an input widget for the attribute, enabling you to change its value. When the value has been overridden, this button changes into a button showing an X, as shown here:

Figure 21.13 Define Attributes Detail, Overriding Attribute Default Value

Most content is described in the surrounding text. Is like the previous image but with the green plus sign button was clicked and its entry can now be edited. The green plus sign was replaced with a red X.

Clicking the X button next to an attribute undoes any changes made to it; it immediately reverts to the predefined value.

All configuration attributes have predefined values calculated by the installer, based such factors as host name, node ID, node type, and so on. In most cases, these values may be left as they are. If you are not familiar with it already, it is highly recommended that you read the applicable documentation before making changes to any of the attribute values. To make finding this information easier, each attribute name shown in the information panel is linked to its description in the online NDB Cluster documentation.

NDB Cluster Auto-Installer Deploy Cluster Screen

This screen allows you to perform the following tasks:

  • Review process startup commands and configuration files to be applied

  • Distribute configuration files by creating any necessary files and directories on all cluster hosts—that is, deploy the cluster as presently configured

  • Start and stop the cluster

The Deploy Cluster screen is shown here:

Figure 21.14 NDB Cluster Auto-Installer Deploy Cluster Configuration screen

Content is described in the surrounding text.

Like the Define Attributes screen, this screen features a process tree which is organized by process type. Next to each process in the tree is a status icon indicating the current status of the process: connected (CONNECTED), starting (STARTING), running (STARTED), stopping (STOPPING), or disconnected (NO_CONTACT). The icon shows green if the process is connected or running; yellow if it is starting or stopping; red if the process is stopped or cannot be contacted by the management server.

This screen also contains two information panels, one showing the startup command or commands needed to start the selected process. (For some processes, more than one command may be required—for example, if initialization is necessary.) The other panel shows the contents of the configuration file, if any, for the given process; currently, the management node process is only type of process having a configuration file. Other process types are configured using command-line parameters when starting the process, or by obtaining configuration information from the management nodes as needed in real time.

This screen also contains three buttons, labelled as and performing the functions described in the following list:

  • Deploy cluster: Verify that the configuration is valid. Create any directories required on the cluster hosts, and distribute the configuration files onto the hosts. A progress bar shows how far the deployment has proceeded.

  • Start cluster: The cluster is deployed as with Deploy cluster, after which all cluster processes are started in the correct order.

    Starting these processes may take some time. If the estimated time to completion is too large, the installer provides an opportunity to cancel or to continue of the startup procedure. A progress bar indicates the current status of the startup procedure, as shown here:

    Figure 21.15 Progress Bar With Status of Node Startup Process

    Progress bar showing status of node startup process. The small window is titled "Starting cluster" with a progress bar at 40% in the "Starting Cluster processes" phase of the operation.

    The process status icons adjoining the process tree mentioned previously also update with the status of each process.

  • Stop cluster: After the cluster has been started, you can stop it using this. As with starting the cluster, cluster shutdown is not instantaneous, and may require some time complete. A progress bar, similar to that displayed during cluster startup, shows the approximate current status of the cluster shutdown procedure, as do the process status icons adjoining the process tree.

The Auto-Installer generates a my.cnf file containing the appropriate options for each mysqld process in the cluster.