How to install and update nodes in the cluster

Overview

The purpose of this section is to go beyond the baseline of Matrix42 Software Clustering Basics and see what the possible options are to extend the existing single Matrix42 instance and transform it into a highly available and scalable multi-server infrastructure. 

Before we proceed further, we must consider the fact that the current single Matrix42 instance installation or update is complete using well-defined steps provided at Installation: Step by Step guide.

In the context of the current topic, we denote the very first instance installed as the primary node (which is the same as node 1 in the cluster if using numerical order). It is important to declare the primary node as a basis and generator for all others despite the way we deploy new instances. 

It is important to highlight core distinctions between single Matrix42 applications and clustered Matrix42 environments. Any further node included in the farm must utilize the same databases (production, file storage, history, warehouse, monitoring, persistence, reporting services, and cube), distributed cache, and set of configuration files located on a primary node. Thus, the installation procedure of additional nodes conceptually must go differently. There are at least a few steps that become irrelevant for additional nodes: 

• databases installation 

• engines installation 

Now and onwards, we’re considering these components already available on a primary node, therefore skipping the steps above to avoid excessive operations. 

However, to guarantee all additional nodes in the cluster reflects primary node behavior, it is mandatory to share the following components among them: 

• Security configuration files (securityCryptography.config, Matrix42.Auth.STS.config) 

• Certificates  

• Installed packages 

Eventually, the goal is to achieve identical data security mechanisms, users' authorization, utilization of the same certificates and packages throughout the cluster. Any changes to the files listed above must be immediately applied to the rest of the cluster nodes to retain the entire system's consistency and stable work. The load balancer forces the system to process user requests on different instances, hence, regardless of the processing node the outcome of the same request must always be identical to the one processed by another node. 

 

As stated above, while cloning the primary node all the files are getting copied automatically. The clean distributive installation will require cluster nodes to be synced. This will require the files to be copied manually from primary to all subsequent nodes: 

• {Installation Directory}/bin/securityCryptography.config 

• {Installation Directory}/bin/Matrix42.Auth.STS.config 

• {Installation Directory}/Certificates 

• {Installation Directory}/InstalledPackages  

Additionally, all the installed packages copied from the primary must be unzipped and moved to appropriate directories according to the folder tree contained in the archive, i.e., the package archive could contain folders bin and Workspaces. Unzipped files must be placed in the same folders in the root directory.  

Considering that, the primary node should take a leading role in providing the required information while extending the cluster. The availability of the primary node becomes very crucial and qualifies the entire system's stability. 

To start running the installation process, the load balancer must be configured, up and running. It should be able to accept external requests forwarding them to the primary node. To add load balancer host to the primary node, follow the next steps: 

1. Run Matrix42.Setup.exe in configuration mode on a primary node (node 1);

2. Go to Change Security Configuration → Next → Next;

3. Enable Advanced settings;

4. Enter Load Balancer hostname;

5. Enable Override REST API hostname with Load Balancer;

6. Click Apply.

  

Installing the nodes

Use this video tutorial as a reference: 

We assume new environments are completely ready for new installations, all prerequisites are met to install Matrix42 Software from scratch. Overall, there are two possible options to propagate subsequent nodes in the cluster: 

1. Cloning the primary node (recommended) 
   To run the installation based on the primary node clone, zip the installation directory on the primary node and unzip on the target environment to a custom directory (should not be the same as the installation directory). Most of the settings are eventually getting copied to a subsequent node, including security settings, connection strings, packages, etc.

2. Using clean distributive (requires more manual interventions during configuration) 
   To run the installation based on clean distributive, unzip distribution files to a custom directory on the target machine (should not be the same as installation directory). In opposite to cloning, we must handle all the movements manually if installing from a clean distributive, which includes security settings, connection strings, packages, etc. 

In any of the cases above, any additional node in the cluster must be installed using the dedicated PowerShell script located at: 

{Cloned or Clean Distributive Directory}/Deployment/WMInstallNewNode.ps1 

The script itself accepts a set of input parameters to customize further installation procedures. Most of the parameters become optional if the process goes based on the primary node clone. The installer script will recognize the parameters from the copied source and offer the same to be configured on the new node.

For the clean distributive, we must set the initial values manually to let the script recognize the required settings.  

See the complete list of parameters below. The parameters are self-descriptive and are as follows: 

1. $InstallerDirectory: source path to grab installation files. Default is the current directory from where the script is invoked;

2. $InstallationDirectory: target path of installation. Default is "C:\Program Files (x86)\Matrix42\Matrix42 Workplace Management";

3. $ServiceAccount: username of service account;

4. $ServiceAccountPassword: password of service account;

5. $HostName: hostname; 

6. $ConnectionString: connection string to production database (must be entered if using clean distributive, otherwise obtained from SPS.config if using clone option); 

7. $CertificatesDirectory: path to directory with certificates (certificates must be copied from a primary node if using clean distributive, otherwise already present is using clone option); 

8. $AuthSTSConfigPath: path to Matrix42.Auth.STS.config (must be copied from a primary node if using clean distributive, otherwise already present if using clone option);

9. $SecurityCryptographyConfig: path to securityCryptography.config (must be copied from a primary node if using clean distributive, otherwise already present if using clone option);

10. $CertificatePassword: password for SSL certificate;  

11. $MonitoringDatabaseName: name of monitoring database (must be entered if using clean distributive, otherwise obtained from production database if using clone option); 

12. $PersistenceDatabaseName: name of persistence database (must be entered if using clean distributive, otherwise obtained from production database if using clone option). 

To run the script, execute the following commands: 

cd {Cloned or Clean Distributive Directory}/Deployment 
./WMInstallNewNode.ps1

The script will prompt for the input parameters and offer the default values if available. Click Enter to use the default value and proceed. 

Alternatively, all parameters can be provided instantly as arguments to the script. To invoke it, run the script as shown below (all the values are fake ones, just to give a sample): 

cd {Cloned or Clean Distributive Directory}/Deployment
./WMInstallNewNode.ps1 -InstallerDirectory “C:\temp”,
 -InstallationDirectory "C:\Program Files (x86)\Matrix42\Matrix42 Workplace Management", 
 - ServiceAccount “username”, -ServiceAccountPassword “password”, -HostName “node2.domain.com”, 
 - ConnectionString “data source=.;initial catalog=M42Production;user id=matrix;password=password”, 
 - CertificatesDirectory “C:\temp\Certificates”, -AuthSTSConfigPath “C:\temp\bin\Matrix42.Auth.STS.config”, 
 -SecurityCryptographyConfig “C:\temp\bin\securityCryptography.config”, - CertificatePassword “password”, 
 -MonitoringDatabaseName “M42Monitoring”, -PersistenceDatabaseName “M42Persistence” 

Updating the nodes

Similarly, the update process will require WMUpdateNode.ps1 to be executed in the target environment.  

Update script supports the following parameters:  

1. $InstallerDirectory: source path to grab installation files. Default is the current directory from where the script is invoked;

2. $InstallationDirectory: target path of installation. Default is "C:\Program Files (x86)\Matrix42\Matrix42 Workplace Management";

3. $ServiceAccount: username of the service account;

4. $ServiceAccountPassword: password of the service account. 

Normally, the update script will not require customization in the values above unless the installation has not been executed with the default values. 

To run the script, execute the following commands: 

cd {Cloned or Clean Distributive Directory}/Deployment 
./WMUpdateNode.ps1 -InstallerDirectory “C:\temp”,  
-InstallationDirectory "C:\Program Files (x86)\Matrix42\Matrix42 Workplace Management", 
- ServiceAccount “username”, -ServiceAccountPassword “password”