Create a KVM/libvirt Site

Objective

Volterra supports site deployment for a Kernel-based Virtual Machine (KVM) with libvirt. Use the instructions provided in this document to perform Volterra node installation on a server using a KVM with libvirt and to perform site registration on VoltConsole.

Hypervisor Topology
Figure: Hypervisor Topology


Prerequisites

  • A Volterra Account. If you do not have an account, see Create a Volterra Account.
  • A server supporting hardware virtualization. The KVM will only work if the server CPU has hardware virtualization support (Intel VT or AMD-V).
  • An Operating System installed on the host:

    • Ubuntu -16.X/18.X
    • CentOS 7.x/RHEL 7.x
  • At least one interface with internet reachability.
  • Volterra Node Zero Touch Provisioning requires internet connectivity to VoltConsole.
  • A Volterra KVM image file. Click here to download.
  • By proceeding with the installation, download and/or access and use, as applicable, of the Volterra software, and/or Volterra platform, you acknowledge that you have read, understand, and agree to be bound by this agreement.

Create a Site Token

Create a site token or use an existing token. If you are configuring a multi-node site, use the same token for all nodes.

Step 1: Log into VoltConsole and navigate to site tokens.
  • Click on the System namespace.
  • Select Manage -> Site Management -> Site Tokens.

NameSpaceNavig
Figure: Site Tokens

Step 2: Generate a new site token.
  • Click Add site token to create a new token. This loads the Add site token form.
  • In the Name field, enter the token name.
  • In the Description field, enter a description for the token.
  • Click Add site token.

CreateSiteToken
Figure: Site Token Form

Step 3: Note down the new token.
  • Find the token previously created or choose an existing token from the list of tokens displayed.
  • Click > to expand the token details in JSON format and note down the value of the uid field.

SiteTokenUID
Figure: UID Field


Check for Virtualization Support

Check if your system supports virtualization.

  • To check if virtualization is enabled on Ubuntu or CentOS/RHEL:

    • Type egrep '(vmx|svm)' /proc/cpuinfo | wc -l. This command returns a non-zero number if virtualization is enabled.
egrep '(vmx|svm)' /proc/cpuinfo | wc -l

Note: For Ubuntu, you may need to run the sudo apt install cpu-checker command prior to continuing. This action will install the cpu-checker package.

  • For Ubuntu only:

    • To verify if KVM acceleration is available, type sudo kvm-ok. This command returns a message that confirms that KVM acceleration can be used.
sudo kvm-ok
KVM acceleration can be used

Install Packages

Install all required packages. You need admin/root privileges to update or install packages.

Install the required packages for Ubuntu:

  • Type sudo apt update.
sudo apt update
  • Type sudo apt install qemu qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils virt-manager.
sudo apt install qemu qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils virt-manager

Install the required packages for CentOS/RHEL:

  • Type yum update.
yum update
  • Confirm with y to perform the update.
  • Type yum install qemu-kvm qemu-img virt-manager libvirt libvirt-client virt-install virt-viewer libvirt-python bridge-utils.
yum install qemu-kvm qemu-img virt-manager libvirt libvirt-client virt-install virt-viewer libvirt-python bridge-utils
  • Confirm with y to perform the installation.

Enable HugePages

This section provides an example for setting the HugePages for a cluster of 3 nodes. The required number of HugePages per Volterra node is 400.

Note: You can use a text editor, such as vim or nano, to open the configuration file and make edits.

Step 1: Add HugePages configuration.
  • For the hypervisor host on Ubuntu, add the following in the Grub configuration file (/etc/default/grub):

    • GRUB_CMDLINE_LINUX="default_hugepagesz=2M hugepagesz=2M hugepages=1200"
GRUB_CMDLINE_LINUX="default_hugepagesz=2M hugepagesz=2M hugepages=1200"
  • For the hypervisor host on CentOS/RHEL, add the following to the /etc/sysctl.conf file:

    • vm.nr_hugepages = 1200
vm.nr_hugepages = 1200
Step 2: Update the configuration to make HugePages effective.

For Ubuntu, run the following commands in the terminal:

  • sudo update-grub
  • sudo grub-mkconfig -o /boot/grub/grub.cfg
grub-mkconfig -o /boot/grub/grub.cfg
  • sudo reboot

For CentOS/RHEL, run the following commands in the terminal.

  • sysctl -p.
sysctl -p
  • Confirm the output is correct.
  • Reboot your system.
Step 3: Check the HugePages configuration after the host reboot.
  • Type cat /proc/meminfo | grep Huge.
cat /proc/meminfo | grep Huge
  • Confirm the configuration settings are correct.
AnonHugePages:   6100992 kB
ShmemHugePages:        0 kB
HugePages_Total:    1200
HugePages_Free:     1200
HugePages_Rsvd:        0
HugePages_Surp:        0
HugePagesize:       2048 kB

Create a Virtual Network

Step 1: Create a new libvirt network.
  • In the terminal, use the touch command to create an XML file with a .xml extension.
  • Open the XML file using vim or nano text editors.
  • Populate the network fields. Set a different subnet other than the underlay network.

This example provides sample file entries:

<network>
  <name>virtualnetwork1</name>
  <forward mode='nat'>
    <nat>
      <port start='1024' end='65535'/>
    </nat>
  </forward>
  <bridge name='bridge1' stp='on' delay='0'/>
  <ip address='192.168.122.1' netmask='255.255.255.0'>
    <dhcp>
      <range start='192.168.122.2' end='192.168.122.254'/>
    </dhcp>
  </ip>
</network>
  • Save your information and close the text editor.
Step 2: Define the virtual network from the XML file created in Step 1.
  • In the terminal, type virsh net-define virtualnetwork1.xml.
virsh net-define virtualnetwork1.xml
Step 3: Start the virtual network and enable it for autostart.
  • To start the network, type virsh net-start virtualnetwork1.
virsh net-start virtualnetwork1
  • To enable autostart, type virsh net-autostart virtualnetwork1.
virsh net-autostart virtualnetwork1
Step 4: List the libvirt networks to verify that the virtual network was created.
  • To list the libvirt networks, type virsh net-list.
virsh net-list

This example provides sample output:

  Name                 State      Autostart     Persistent
  ----------------------------------------------------------------
  default            active        yes                 yes
  virtualnetwork1    active        yes                 yes
Step 5: Optionally, list your bridge devices.
  • Type, brctl show.
brctl show

This example provides sample output:

  bridge name     bridge id               STP enabled     interfaces
  virbr0          8000.5254003339b3       yes             virbr0-nic
  virbr1          8000.52540060f86e       yes             virbr1-nic

Install Node using Terminal

This procedure is only required when installing the virtual machine using the terminal.

Step 1: Create a Virtual Disk Image file.
  • In the terminal, type sudo qemu-img create /var/lib/libvirt/images/disk1.qcow2 30G.

This example creates a virtual disk file with name disk1.qcow2:

qemu-img create /var/lib/libvirt/images/disk1.qcow2 30G
Step 2: Create a new virtual machine.
  • Run the virt-install command with the following options set:
virt-install --name Volterra --ram 8192 --vcpus=4  --network network=default,model=virtio --accelerate –disk path=/var/lib/libvirt/images/volterra.qcow2,bus=virtio,cache=none,size=64 --cdrom /scratch/vsb-ves-ce-certifiedhw-generic-production-centos-7.2006.9-202010131432.1602604079.iso  --noautoconsole --noreboot

This list provides the option descriptions for the virt-install command:

  • name: Name of the guest virtual machine.
  • ram: RAM allocation for guest virtual machine (minimum 8 GB, recommended 16 GB).
  • vcpus: The CPU allocation for guest virtual machine (minimum 4).
  • network: The name of the virtual network that the Customer Edge (CE) server should be attached to. You can also specify bridge for network.
  • disk path: The virtual disk path.
  • cache: Ensure that the cache=none option is specified in the command.

Note: KVM installation is supported only for the SCSI disk type and e1000 model for network type.

Step 3: Optionally, start the virtual machine.

The virt-install command starts the virtual machine. Note that in some cases the virtual machine may not start yet.

  • To start the virtual machine, type virsh start volterra-node.
virsh start volterra-node
Step 4: Verify the status of the virtual machine.
  • Type virsh list –all.
virsh list --all

This example provides the sample output of the command:

 Id    Name                           State
----------------------------------------------------
 31    ce-volterra                  running
Step 5: Connect to the virtual machine using console.
  • Type virsh console 31.
virsh console 31

This example provides the sample output of the command:

Connected to domain ce-volterra
Escape character is ^]

This is localhost (Linux x86_64 4.19.56-coreos-r1) 22:53:47
SSH host key: SHA256:aIFHRiKcjFWaF47+9AAd6IGzCQ5M6suHzL0xH3QUaS4 (ECDSA)
SSH host key: SHA256:hmWTu9M5GYKDQcTgks7LDTkQK9LXKhQjSodVO14JICo (ED25519)
SSH host key: SHA256:ewojrrFELDNOZWIW+jp2UgSaQVikpnGupdbu9+ObgZw (RSA)
SSH host key: SHA256:dM0wUNcFqfJxVRGwwzOJBLtTY1JdptmtjyHXthnBKqY (DSA)
eth0: 192.168.122.197 fe80::5054:ff:fe89:abb8
Step 6: Optionally, connect to the virtual machine using IP address.
  • Type virsh domifaddr ce-volterra.
virsh domifaddr ce-volterra

This example provides the sample output of the command:

 Name       MAC address          Protocol     Address
-------------------------------------------------------------------------------
 vnet0      52:54:00:89:ab:b8    ipv4         192.168.122.197/24

Install Node Using the Virtual Machine Manager

You can use the Virtual Machine Manager UI application to interactively install a Volterra node on a hypervisor host. The Virtual Machine Manager application requires that you pre-install the virt-manager package.

Step 1: Initiate the Virtual Machine Manager on the hypervisor host.
  • For CentOS/RHEL: Launch the application from Applications -> System Tools -> Virtual Machine Manager.
  • For Ubuntu: Launch the application from Applications -> Virtual Machine Manager.
  • From terminal: type virt-manager.
Step 2: Create a virtual network.
Step 3: Create a virtual machine.
  • Click Create a new virtual machine.

Create Virtual Machine
Figure: Create Virtual Machine

  • Confirm the installation information is correct, and then click Forward.

Virtual Machine Creation
Figure: Virtual Machine Creation

Step 4: Select the Volterra node ISO file for installation.
  • Click Browse to navigate and select the ISO image file.

Installation Using ISO Option
Figure: Installation Using ISO Option

  • Click Forward.

Creation of Virtual Machine with ISO
Figure: Creation of Virtual Machine with ISO

Step 5: Configure memory and CPU settings.
  • In the Memory (RAM) field, use the + or buttons to set the memory amount.
  • In the CPUs field, use the + or buttons to set the number of CPU cores.
  • Click Forward.

Virtual Machine Memory and CPU Settings
Figure: Virtual Machine Memory and CPU Settings

Step 6: Configure the disk image settings.
  • Confirm the option for Enable storage for this virtual machine is enabled.
  • Under the Create a disk image for the virtual machine field, use the + or buttons to set the amount of storage.
  • Click Forward.

Disk Image Storage Setting
Figure: Disk Image Storage Setting

Step 7: Configure the network.
  • From the Network selection drop-down menu, select Virtual network ‘default’ : NAT.
  • Confirm all other settings are correct.
  • Click Finish.

Virtual Machine Network Setting
Figure: Virtual Machine Network Setting

Step 8: Configure the NIC driver and CPU.
  • For the NIC driver, confirm the settings are correct, or adjust them and then click Apply.

Virtual Machine NIC Setting
Figure: Virtual Machine NIC Setting

  • For the CPU(s), confirm the settings are correct, or adjust them and then click Apply.

Virtual Machine CPU Setting
Figure: Virtual Machine CPU Setting

Step 9: Complete the creation of the virtual machine.
  • Click Finish.
  • Start the virtual machine from the Virtual Machine Manager options.

Post-Install Node Parameter Configuration

At any point, you can login to the Volterra node via SSH using the admin user account and Volterra123 password to configure parameters.

Note: If you did not log in previously, you will be prompted to update the default password for the admin user account. Follow the instructions to update the default password.

Step 1: Log into the node using your credentials.

The login shell loads with different options to select for configuration.

  • Press the Tab key to select parameters to configure.

Node Login Shell Menu Options
Figure: Node Login Shell Menu Options

Step 2: Verify the configuration.
  • Select get-config.
  • Confirm the settings are correct.
Step 3: Optionally, perform network configuration.
  • Select configure-network.
  • Follow the prompts to configure network settings.
  • Optionally, enter Y for Do you want to configure wifi?.

Note: You cannot change an IP address for a registered node for a multi-node site. You must use fixed IP addresses or DHCP addresses with a fixed lease.

Step 4: Enter the SSID and password for your Wi-Fi network.

Configuring the network is optional. If you want to apply static configuration, then this option can be used.

Step 5: Configure the main options.
  • Press the Tab key to select the configure option.
  • Enter a cluster name.
  • Enter the registration token.
  • Enter a hostname. This option is set to master0 by default.

Note: Ensure that hostnames are unique if you are installing nodes for a multi-node site.

  • Enter the longitude and latitude information.
  • Select kvm-voltmesh for the certified hardware.

Note: You must first perform network configuration using the configure-network option before setting the other fields using the configure option in case you are applying static configuration for the network. Also, note that changing the assigned IP address after the successful registration of the node is not supported in cases of multi-node sites.

Step 6: Confirm configuration.
  • Enter Y to confirm configuration.

Generic Configuration
Figure: Generic Configuration

Step 7: Verify configuration status.
  • Press the Tab key to select the health option.
  • Verify your Wi-Fi configuration and registration status.

Node WiFi Information
Figure: Node Wi-Fi Information

Note: You can select the factory-reset option to perform a configuration reset and repeat the registration process again per the instructions below.

Node Registration Status
Figure: Node Registration Status


Register the KVM/libvirt Site

After the Volterra Node is installed on a KVM, it must be registered as a Site in VoltConsole.

Note: The USB allowlist is enabled by default. If you change a USB device, such as a keyboard after registration, the device will not function.

Single-node Site Registration

Step 1: Navigate to the site registration page.
  • Log into VoltConsole and then navigate to the System namespace.
  • Click Manage -> Site Management -> Registrations.

AcceptReg
Figure: Site Registration

Step 2: Complete site registration.
  • Under Pending Registrations, find your node name and then click the blue checkmark.

  • In the form that appears, fill in all required fields with the asterisk symbol (*).
  • Enter a latitude value and a longitude value.

  • Enter other configuration information, if needed.
  • Click Save and Exit.
Step 3: Check site status and health.

It may take a few minutes for the site health and connectivity score information to update.

  • In the System namespace, click Sites -> Site List.
  • Click on your site name. The Dashboard tab appears, along with many other tabs to inspect your site.
  • Click the Site Status tab to verify the following:

    • The Update Status field has a Successful value for the Volterra OS Status section.
    • The Update Status field has a Successful value for the Volterra Software Status section.
    • The Tunnel status and Control Plane fields under the RE Connectivity section have up values.

Multi-node Site Registration

Step 1: Navigate to the site registration page.
  • Log into VoltConsole and then navigate to the System namespace.
  • Click Manage -> Site Management -> Registrations.

AcceptReg
Figure: Site Registration

Step 2: Accept the registration requests.

Registration requests are displayed in the Pending Registrations tab.

  • Click Accept to accept the registration requests from the master-0, master-1, and master-2 nodes.
  • Enter the same values for the following parameters for all the registration requests:

    • In the Cluster name field, enter a name for the cluster. Ensure that all master nodes have the same name.
    • In the Cluster size field, enter 3. Ensure that all master nodes have the same cluster size.
  • Enter all mandatory fields marked with the asterisk (*) character.
Step 3: Check site status and health.

It may take a few minutes for the site health and connectivity score information to update.

  • In the System namespace, click Sites -> Site List.
  • Click on your site name. The Dashboard tab appears, along with many other tabs to inspect your site.
  • Click the Site Status tab to verify the following:

    • The Update Status field has a Successful value for the Volterra OS Status section.
    • The Update Status field has a Successful value for the Volterra Software Status section.
    • The Tunnel status and Control Plane fields under the RE Connectivity section have up values.

Note: You can log into your Node’s Volterra command-line interface (CLI) via SSH with username centos and your private key.


Concepts