SafeKit quick installation guide with Hyper-V (hyperv.safe mirror module)

Overview of the solution

SafeKit quick installation guide with the Hyper-V module

Step by step configuration

1. Prerequisites

The VM1 virtual machine files (VM1 configuration file, virtual hard disk...) must be put in a same folder: this folder will be replicated by SafeKit.

Make sure the virtual switch name(s) referenced by the virtual machine exist on both Hyper-V servers and corresponds to the same physical network.

It is important that all the files representing a VM (Virtual Machines/, Virtual Hard Disks/, .vmcx, .vmgs, .vmrs, .vhdx, ...) are in the same directory replicated by SafeKit. Else your VM will not reboot after replication. If you are not sure, take a snapshot or your VM before starting the procedure.

If all the files of VM1 are not in the same folder, use Hyper-V manager:

Export VM1 in a folder, for example in D:\Repli-Hyper-V
This export will create a folder D:\Repli-Hyper-V\VM1\ containing all VM1 files
Remove VM1 from the inventory of Hyper-V manager
Import VM1, previously exported, into Hyper-V manager

3. Configure node addresses

Enter the node IP addresses, press the Tab key to check connectivity and fill node names.
Then, click on Save and apply to save the configuration.

If either node1 or node2 has a red color, check connectivity of the browser to both nodes and check firewall on both nodes for troubleshooting.

If you want, you can add a new LAN for a second heartbeat and for a dedicated replication network.

This operation will place the IP addresses in the cluster.xml file on both nodes (more information in the training with the command line).

5. Configure the module

Choose an Automatic start of the module at boot without delay.
Normally, you have a single Heartbeat network on which the replication is made. But, you can define a private network if necessary (by adding a LAN at step 3).
Put in VM_PATH, the root path of the replicated directory (D:\Repli-Hyper-V).
Enter in VM_NAME, the name of the virtual machine (VM1).

We assume that all VM1 files are in D:\Repli-Hyper-V\VM1\ (see prerequisites). This directory will be replicated in real-time by SafeKit.

The NORMAL_STOP and FORCE_STOP values can be "stop", "save" or "off":

"stop" shutdowns the VM when the module is stopped.
"save" saves the current state of the VM (suspend) when the module is stopped.
"off" turns off the VM (power off) when the module is stopped.

"stop" is recommended because it causes the shutdown then the reboot of the VM when the module is stopped and restarted. Thus, if the application inside the VM fails, it is restarted.

This will be the case, for example, when switching between primary and secondary roles.

You do not need to configure a virtual IP address. VM1 will be rebooted on the secondary Hyper-V with its physical IP address, and this IP address will be rerouted.

6. Custom checker to detect VM malfunction

The custom checker sends heartbeat messages from the host to the VM at regular intervals. It is then the job of the Hyper-V Heartbeat Service installed in the VM to send a response to each of these heartbeat messages.

If the Hyper-V Heartbeat Service does not respond to the message (VM locked up, crashed or ceased to function), then the custom checker executes an action to restart the VM on the same Hyper-V node or on the other.

Click on Checkers / Custom (see image).
Just set a name of your choice in Resource name (example VM1). Resource name identifies the virtual machine with a resource name in SafeKit: custom.VM1.
With restart in Action, the VM is restarted on the same Hyper-V node. After 3 unsuccessful restarts in 24 hours, the SafeKit hyperv module stops on the primary node and there is a failover of the VM on the secondary node.
If you set stopstart in Action, there is a direct failover on the other Hyper-V node as soon as the VM does not respond to heartbeats.

For maintenance, if you want to stop the virtual machine, the custom checker will restart it automatically. To avoid that, you can temporarly suspend the checker. Or you can remove it by deleting the configuration line in the console.

It’s the same when you want to restore a checkpoint. Hyper-V will stop the VM to perform the operation, and the VM checker may react negatively by automatically restarting the VM. To avoid this, suspend the checker before proceeding with the operation.

11. Start the node with up-to-date data

If node 1 has the up-to-date replicated directory for VM1/, select it and start it As primary.

When node 2 will be started, all data will be copied from node 1 to node 2.

If you make the wrong choice, you run the risk of synchronizing outdated data on both nodes.

It is also assumed that VM1 is stopped on node 1 so that SafeKit installs the replication mechanisms and then starts VM1 in the start_prim script.

Use Start for subsequent starts: SafeKit retains the most up-to-date server. Starting As primary is a special start-up the first time or during exceptional operations.

12. Wait for the transition to ALONE (green)

Node 1 should reach the ALONE (green) state, which means that the start_prim script has been executed on node 1.

If ALONE (green) is not reached or if VM1 is not started, analyze why with the module log of node 1.

click the "log" icon of node1 to open the module log and look for error messages such as a checker detecting an error and stopping the module.
click on start_prim in the log: output messages of the script are displayed on the right and errors can be detected such as VM1 incorrectly started.

If the cluster is in WAIT (red) not uptodate, STOP (red) not uptodate state, stop the WAIT node and force its start as primary.

13. Start node 2

Start node 2 with its contextual menu.
Wait for the SECOND (green) state.

Node 2 stays in the SECOND (orange) state while resynchronizing the replicated directories (copy from node 1 to node 2).

This may take a while depending on the size of files to resynchronize in replicated directories and the network bandwidth.

To see the progress of the copy, see the module log and the replication resources of node 2.

When using Hyper-V differencing disks, only the differencing disk needs resynchronization after the initial sync, saving time for large virtual hard disks.

15. Testing

Stop the PRIM node by scrolling down its contextual menu and clicking Stop.
Verify that there is a failover on the SECOND node which should become ALONE (green).
Check with Hyper-V manager that VM1 is running on node 2.

If ALONE (green) is not reached on node2 or if VM1 is not started, analyze why with the module log of node 2.

click the "log" icon of node2 to open the module log and look for error messages such as a checker detecting an error and stopping the module.
click on start_prim in the log: output messages of the script are displayed on the right and errors can be detected such as VM1 incorrectly started.

As the start_prim script imports the virtual machine on node 2, the failover can fail because of Hyper-V settings (see this article).

If everything is okay, initiate a start on node1, which will resynchronize the replicated directories from node2.

If things go wrong, stop node2 and force the start as primary of node1, which will restart with its locally healthy data at the time of the stop.

More information on tests in the User's Guide.

16. Automatic restart if a critical service fails inside the VM

If you want an automatic restart or failover when a critical service inside the VM fails, you can configure the Recovery properties of the service (see image).

First you must configure the custom checker previously described.

And then in Microsoft Service Manager inside the VM, select your critical service and in the recovery property of the service, you just have to configure shutdown of the VM when the critical service fails.

For that, in the Recovery options of your critical service, choose "Run a Program" on failures and in Run program options, set"C:\Windows\System32\shutdown.exe" and in "Command line parameters", set /s /c "service fails".

Of course, you can implement more subtle recovery with your own scripts. But just be aware that shutting down the VM will enable the custom checker in the host. The custom checker will detect that the Hyper-V heartbeat is no more responding and will restart the VM on the same Hyper-V server or will make a failover on the other Hyper-V server (depending on its configuration).

To test the feature, use Task Manager and kill the process (End task) associated to the critical service. A clean stop of the service through Service Manager or the "net stop" command does not trigger the recovery action inside Windows Service Manager.

19. If necessary, configure a splitbrain checker

See below "What are the different scenarios in case of network isolation in a cluster?" to know if you need to configure a splitbrain checker.
Go to the module configuration and click on Checkers / Splitbrain (see image) to edit the splitbrain parameters.
Save and apply the new configuration to redeploy it on both nodes (module must be stopped on both nodes to save and apply).

Parameters:

Resource name identifies the witness with a resource name: splitbrain.witness. You can change this value to identify the witness.
Witness address is the argument for a ping when a node goes from PRIM to ALONE or from SECOND to ALONE. Change this value with the IP of the witness (a robust element, typically a router).
Note: you can set several IPs separated by white spaces. Pay attention that the IP addresses must be accessible from one node but not from the other in the event of network isolation.

When there is a network isolation, the behavior with a split-brain checker is:

a split-brain checker has been configured with the IP address of a witness (typically a router),
the split-brain checker operates when a server goes from PRIM to ALONE or from SECOND to ALONE,
in case of network isolation, before going to ALONE, both nodes test the IP address,
the node which can access the IP address goes to ALONE, the other one goes to WAIT,
when the isolation is repaired, the WAIT node resynchronizes its data and becomes SECOND.

Note: If the witness is down or disconnected, both nodes go to WAIT and the application is no more running. That's why you must choose a robust witness like a router.

Demonstration