VM Build Container Tutorial

Before starting the tutorial steps, read through the Introduction section to learn about VMBC and the tutorial, and then set up your development environment as per the Prerequisites and preparation section.

Once you are ready, start the tutorial with the Building the VM step.

VMBC is a tool in the Rhino VM automation solution for producing automated VMs that run your Rhino application.

Before starting to use the tool, learn about how the solution works at a high level by reading through the Rhino VM Automation solution documentation.

To begin the tutorial, ensure you have your development environment set up and all required files downloaded, as per the Prerequisites and preparation page. Then proceed to Building the VM.

You will need a VM host (referred to as the VNFI) to host the VMs created in this tutorial. Supported VM host platforms are VMware vSphere version 6.5 or later, or OpenStack release Newton or later.

You will also need:

You will need the following, which can be obtained from your Metaswitch Customer Care representative:

Create a directory called resources to store these files.

Expand each section below to view the detailed steps.

You created a CSAR containing your VM image. It will be in the target/images directory:

If you are using OpenStack, it will be named -openstack-csar.zip instead of -vsphere-csar.zip.

In the next step Setting up SIMPL VM and CDS, you will deploy the SIMPL VM and prepare for the deployment of the example VMs from the CSAR you created. Click here to progress to the next step.

Expand each section below to view the detailed steps.

You created a CDS node and a SIMPL VM, and unpacked your CSAR on the SIMPL VM.

In the next step, you will prepare configuration files and upload them to the SIMPL VM and to the CDS. Click here to progress to the next step.

Before starting, open a separate terminal, and in that terminal start an SSH session to the SIMPL VM with the command ssh -o ServerAliveInterval=30 admin@<SIMPL VM IP address>. The ServerAliveInterval option keeps the connection alive; by default the SIMPL VM terminates idle connections after a few minutes.

Expand each section below to view the detailed steps.

You created and configured three VMs, and verified that they work correctly.

This concludes the tutorial.

As optional extra steps, you can learn about:

If you want to try the tutorial again, for example with changes to the example application or configuration, be sure to first clean up the old VMs and CDS data by running the following commands:

This section assumes you are familiar with the basic concepts described in the Rhino documentation around Rhino declarative configuration. If you aren’t familiar with the concepts, read that documentation first.

You updated your application to support compression using declarative configuration and verified that this worked correctly.

While VMs can optionally be deployed in a lab environment without the use of MDM, Metaswitch mandates the use of MDM in production environments. MDM is an essential component of the lifecycle management in the Metaswitch Rhino VM automation solution. VMs cannot be upgraded without MDM. For more details, see the Rhino VM Automation Overview.

We recommend that you first familiarize yourself with the steps required to deploy MDM and configure your VMs to connect to MDM in your lab environment. Follow the instructions in the Install MDM section of the Custom VM Install Guide to install MDM and instructions in the MDM service group section of the guide to configure your VMs to connect to MDM.

The Metaswitch Rhino VM automation solution supports upgrading VMs using rolling replacement. That is, one by one, a downlevel (that is to say old version VM) gets shut down, followed by an uplevel (that is to say new version VM) being deployed. The architecture is described in the VM life cycle management section of the Rhino VM Automation Overview document, while the process to do the upgrades is documented in the Custom VM Install Guide (Rolling upgrade of custom nodes).

If your application is stateful, this could cause in-progress calls or sessions to fail, as the node that was handling it could have been deleted. To minimise this risk, enable replication in the node-parameters.yaml file.

Before a downlevel VM is deleted, it goes through a quiesce process, which cleans up any state relating to a VM that would otherwise persist outside of said VM. For example, for a clustered VM, the quiesce process removes the VM from the Rhino cluster.

If your initconf hooks created any side effects that need to be cleaned up when said VM is deleted, outside of the VM it ran on, you must use Quiesce hooks to achieve this.

As an example, you could add an initconf hook that registers the VM with an external load balancer. That would need an accompanying quiesce hook that unregisters the VM from the load balancer.