SafeKit quick installation guide with KVM (kvm.safe mirror module)

Overview of the solution

SafeKit quick installation guide with KVM

Step by step configuration

1. Prerequisites

The VM1 virtual machine image is in the file /var/lib/libvirt/images/vm1.qcow2. Before configuring SafeKit, you must perform the following configuration to place the virtual machine in a vm1-specific directory that will be replicated by SafeKit.

On node 1:

Stop vm1:
```
virsh shutdown vm1
```
Create a vm1/ directory:
```
mkdir -p /var/lib/libvirt/images/vm1/
```
Copy the vm1 image to the new location:
```
cp -a /var/lib/libvirt/images/vm1.qcow2 /var/lib/libvirt/images/vm1/
```
The original vm1 image can be deleted as soon as tests with the new location are successfull.

Edit the vm1 configuration file:

EDITOR=vi virsh edit vm1

And change the line:

<source file='/var/lib/libvirt/images/vm1.qcow2'>

by :

<source file='/var/lib/libvirt/images/vm1/vm1.qcow2'>

Set the cache option to 'none' in the same file, for data integrity in case of crash:

<disk type='file' device='disk'> <driver name='qemu' type=’qcow2’ cache='none'/>

Close the vm1 configuration file
Disable vm1 automatic start:
```
virsh autostart vm1 --disable
```
Create a vm1.xml configuration file for vm1:
```
virsh dumpxml vm1 > vm1.xml
```

On node 2:

Copy the vm1.xml configuration file from node 1.

Note: whenever vm1 configuration is changed on node 1, you must reapply the new configuration on node 2.
Create vm1 but do not start it:
```
virsh define vm1.xml
```
Disable vm1 automatic start:
```
virsh autostart vm1 --disable
```
Create the directory for the image location:
```
mkdir -p /var/lib/libvirt/images/vm1/
```

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 (/var/lib/libvirt/images).
Enter in VM_NAME, the name of the virtual machine (vm1).

We assume that the VM1 files are in /var/lib/libvirt/image/vm1/ (see prerequisites). This directory will be replicated in real-time by SafeKit.

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

6. Custom checker to detect VM malfunction

The custom checker checks if the VM is running (with the 'virsh domstate' command). If the VM is not running, the custom checker automatically restarts the VM on the same KVM node or on the other.

Click on Checkers / Custom (see image).
Resource name identifies the virtual machine with a resource name in SafeKit: custom.VM_NAME_check.
With restart in Action, the VM is restarted on the same KVM node. After 3 unsuccessful restarts in 24 hours, the SafeKit kvm 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 KVM node as soon as the VM is not running.

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.

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.

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 KVM tools 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.

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. Replicating snapshots

The directory that contains the snapshot xml files is:

/var/lib/libvirt/qemu/snapshot/%VM_NAME%

where VM_NAME is the name of the virtual machine (vm1).

Note: If no snapshot has been created, create one to generate the directory (else the SafeKit configuration will fail).

To replicate it:

In the module configuration, click on Advanced Configuration (see image) to edit userconfig.xml.

Insert the lines below into the <rfs> section of userconfig.xml:

<replicated dir="/var/lib/libvirt/qemu/snapshot/%VM_NAME%" mode="read_only"> </replicated>

Save and apply the new configuration to redeploy the modified userconfig.xml file on both nodes (module must be stopped on both nodes to save and apply).
Create snapshots on the PRIM node either through virt-manager or a command line:
```
virsh snapshot-create-as vm1 snapshot-name
```
Note: when creating a snapshot with a command line, you have to refresh the snapshot view into virt-manager.

Snapshots created on the PRIM node are operationnal on node 2 after failover, but not listed on node 2.

For importing a snapshot on node 2, you have to run the command:

virsh snapshot-create --redefine vm1 /var/lib/libvirt/qemu/snapshot/vm1/snapshot-name

The command line for listing all snapshots of vm1 is:
```
virsh snapshot-list vm1
```

18. 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.

Internals

Internals of a SafeKit / KVM high availability cluster with synchronous replication and failover

Go to the Advanced Configuration tab in the console, for editing these files

Internal files of the Linux kvm.safe module

userconfig.xml (description in the User's Guide)

<!-- Mirror Architecture with Real Time File Replication and Failover for KVM -->

<!DOCTYPE safe>
<safe>
  <!-- Set value to the path of the virtual machines repository -->
  <macro name="VM_PATH" value="/var/lib/libvirt/images" />
  <!-- Set value to the name of the virtual machine -->
  <macro name="VM_NAME" value="vm1" />

 <service mode="mirror" defaultprim="alone" maxloop="3" loop_interval="24" failover="on">
  <!-- Heartbeat Configuration --> 
  <heart>
    <heartbeat name="">
    </heartbeat>
  </heart>

  <!-- File Mirroring Configuration -->
  <rfs mountover="off" async="second" locktimeout="200" nbrei="3">
	<replicated dir="%VM_PATH%/%VM_NAME%" mode="read_only">
	</replicated>
	<!-- Uncomment for replicating the directory that contains snapshot xml files of the virtual machine
	<replicated dir="/var/lib/libvirt/qemu/snapshot/%VM_NAME%" mode="read_only">
	</replicated>
	-->	
  </rfs>

  <!-- User scripts Configuration -->
  <user>
    <var name="VM_PATH" value="%VM_PATH%/%VM_NAME%" />
    <var name="VM_NAME" value="%VM_NAME%" />
  </user>

 </service>
</safe>

start_prim

#!/bin/sh
# Script called on the primary server for starting application

# For logging into SafeKit log use:
# $SAFE/safekit printi | printe "message" 

# stdout goes into Application log
echo "Running start_prim $*" 

res=0

# Start VM_NAME
virsh start $VM_NAME
state=$(virsh list --all | grep " $VM_NAME " | awk '{ print $3}')
if ([ "x$state" == "x" ]) ; then
	res=1
	$SAFE/safekit printe "$VM_NAME not found"
else
	let i=1
	while ( [ $i -le 5 ] && [ "x$state" != "xrunning" ]); do
      sleep 5
      state=$(virsh list --all | grep " $VM_NAME " | awk '{ print $3}')
      let i=i+1
	done
	if ([ "x$state" != "xrunning" ]) ; then
		res=1
		$SAFE/safekit printe "$VM_NAME start failed"
	fi
fi

if [ $res -ne 0 ] ; then
  $SAFE/safekit printe "start_prim failed"
  
  # uncomment to stop SafeKit when critical
  $SAFE/safekit stop -i "start_prim"
fi

stop_prim

#!/bin/sh
# Script called on the primary server for stopping application

# For logging into SafeKit log use:
# $SAFE/safekit printi | printe "message" 

#----------------------------------------------------------
#
# 2 stop modes:
#
# - graceful stop
#   call standard application stop
#
# - force stop ($1=force)
#   kill application's processes
#
#----------------------------------------------------------

# stdout goes into Application log
echo "Running stop_prim $*" 

# Stop VM_NAME
virsh shutdown $VM_NAME
state=$(virsh list --all | grep " $VM_NAME " | awk '{ print $3}')
if ([ "x$state" == "x" ]) ; then
	res=1
	$SAFE/safekit printe "$VM_NAME not found"
else
	let i=1
	while ( [ $i -le 5 ] && [ "x$state" == "xrunning" ]); do
		# Stop VM_NAME
		virsh shutdown $VM_NAME
		sleep 5
      		state=$(virsh list --all | grep " $VM_NAME " | awk '{ print $3}')
      		let i=i+1
	done
	if ([ "x$state" == "xrunning" ]) ; then
		res=1
		$SAFE/safekit printe "$VM_NAME stop failed"
	fi
fi

res=0

# default: no action on forcestop
[ "$1" = "force" ] && exit 0

# Fill with your application stop call

[ $res -ne 0 ] && $SAFE/safekit printe "stop_prim failed"