Virtual Machine Templates

In OpenNebula, VMs are defined with VM Templates. This section explains how to describe a Virtual Machine, and how users typically interact with the system.

OpenNebula administrators and users can register Virtual Machine definitions (VM Templates) in the system, to be instantiated later as Virtual Machine instances. These VM Templates can be instantiated several times and also shared with other users.

Defining a VM

A Virtual Machine Template, in basic terms, consists of:

• A capacity in terms of memory and CPU
• A set of NICs attached to one or more Virtual Networks
• A set of disk images
• Optional attributes like VNC graphics, the booting order, context information, etc.

VM Templates are stored in the system and can be easily browsed and used to instantiate VMs.

Capacity & Name

Defines the basic attributes of the VM including its NAME, amount of RAM (MEMORY), or number of Virtual CPUs.

See Capacity Section in the VM Template reference.

Disks

Each disk is defined with a DISK attribute. A VM can use three types of disk:

• Use a persistent Image: changes to the disk Image will persist after the VM is terminated.
• Use a non-persistent Image: a copy of the source Image is used, changes made to the VM disk will be lost.
• Volatile: disks are created on-the-fly on the target Host. After the VM is terminated the disk is disposed.

See Disks Section in the VM Template reference.

Network Interfaces & Alias

Network interfaces can be defined in two different ways:

• Manual selection: interfaces are attached to a pre-selected Virtual Network. Note that this may require building multiple templates that consider the available networks in each cluster.
• Automatic selection: Virtual Networks will be scheduled like other resources needed by the VM (like Hosts or datastores). This way, you can specify the type of network the VM will need and it will be automatically selected among those available in the cluster. See more details here.

Network interface alias allows you to have more than one IP on each network interface. This does not create a new virtual interface on the VM. The alias address is added to the network interface. An alias can be attached and detached. Note also that when an NIC with an alias is detached, all the associated aliases are also detached.

The alias takes a lease from the network which it belongs to. So, for the OpenNebula it is the same as an NIC and exposes the same management interface, it is just different in terms of the associated Virtual Network interface within the VM.

See Network Section in the VM Template reference.

A Complete Example

The following example shows a VM Template file with a couple of disks and a network interface. A VNC section and an alias were also added:

NAME   = test-vm
MEMORY = 128
CPU    = 1

DISK = [ IMAGE  = "Arch Linux" ]
DISK = [ TYPE     = swap,
         SIZE     = 1024 ]

NIC = [ NETWORK = "Public", NETWORK_UNAME="oneadmin" ]

NIC = [ NETWORK = "Private", NAME = "private_net" ]
NIC_ALIAS = [ NETWORK = "Public", PARENT = "private_net" ]

GRAPHICS = [
  TYPE    = "vnc",
  LISTEN  = "0.0.0.0"]

Simple Templates can be also created using the command line instead of creating a Template file. For example, a similar Template as the previous example can be created with the following command:

$ onetemplate create --name test-vm --memory 128 --cpu 1 --disk "Arch Linux" --nic Public

For a complete reference of all the available options for onetemplate create, go to the CLI reference, or run onetemplate create -h.

Virtual Machine Contextualization

OpenNebula uses a method called contextualization to send information to the VM at boot time. Its most basic usage is to share networking configuration and login credentials with the VM so it can be configured. More advanced cases can be starting a custom script on VM boot or preparing configuration to use OpenNebula Gate.

You can define contextualization data in the VM Template. See Context Section in the VM Template reference.

Preparing VM Templates for End Users

Besides the basic VM definition attributes, you can set up some extra options in your VM Template to make sharing it with other users easier.

Customizable Capacity

The capacity attributes (CPU, MEMORY, VCPU) can be modified each time a VM Template is instantiated. The Template owner can decide if and how each attribute can be customized. The modification options available are:

• fixed (fixed): The value cannot be modified.
• any value (text): The value can be changed to any number by the user instantiating the Template.
• range (range): Users will be offered a range slider between the given minimum and maximum values.
• list (list): Users will be offered a drop-down menu to select one of the given options.

If you are using a Template file instead of Sunstone, the modification is defined with user input (USER_INPUT) attributes (see below). The absence of user input is an implicit any value. For example:

CPU    = "1"
MEMORY = "2048"
VCPU   = "2"
USER_INPUTS = [
  VCPU   = "O|fixed|| |2"
  CPU    = "M|list||0.5,1,2,4|1",
  MEMORY = "M|range||512..8192|2048" ]

User Inputs

The User Inputs functionality provides the VM Template creator with the possibility to ask for dynamic values. This is a convenient way to parametrize a base installation. These inputs will be presented to the user when the VM Template is instantiated. The VM guest needs to have the OpenNebula contextualization packages installed to make use of the values provided by the user. The following example shows how to pass some user inputs to a VM:

USER_INPUTS = [
  BLOG_TITLE="M|text|Blog Title",
  MYSQL_PASSWORD="M|password|MySQL Password",
]

CONTEXT=[
  BLOG_TITLE="$BLOG_TITLE",
  MYSQL_PASSWORD="$MYSQL_PASSWORD" ]

See User Inputs Section in the VM Template reference.

User Inputs in Sunstone

When a Virtual Machine template is instantiated using Sunstone, the user will be asked to fill in the user inputs that are defined in the Virtual Machine template. So, using the following user inputs:

USER_INPUTS = [
  BLOG_TITLE="M|text|Blog Title",
  BLOG_DESCRIPTION="O|text|Blog Description",
  MYSQL_ENDPOINT="M|text|MySQL Endpoint",
  MYSQL_USER="O|password|MySQL User",
  MYSQL_PASSWORD="O|password|MySQL Password",
  MYSQL_ADDITIONAL="O|boolean|Define additional parameters",
  MYSQL_SOCKET="O|text|MySQL Socket",
  MYSQL_CHARSET="O|text|MySQL Charset"
]

The result will be a step with all the user inputs that are defined in the Template:

In order to improve the user experience, Sunstone can render these user inputs in a different way that is easy to understand for the Sunstone user. To do that, Sunstone uses rules based on the name of the user inputs. These rules are:

• User input name has to meet the following convention ONEAPP_<APP>_<GROUP>_<FIELD> where all the user inputs that meet this convention will be grouped by APP and GROUP. An APP will be rendered as a tab in Sunstone and a GROUP will group the user inputs that belong to this group.
• If FIELD displays the word ENABLED and the user input type is boolean, all the user inputs that have the same APP and GROUP will be hidden until the ENABLED user input is turned on.
• If a user input does not meet the convention, it will be placed in a tab called Others.
• If all the user inputs do not meet the convention name, no tabs will be rendered (as in the previous example).

So, if the previous Template is modified as follows:

USER_INPUTS = [
  ONEAPP_BLOG_CONF_TITLE="M|text|Blog Title",
  ONEAPP_BLOG_CONF_DESCRIPTION="O|text|Blog Description",
  ONEAPP_MYSQL_CONFIG_ENDPOINT="M|text|MySQL Endpoint",
  ONEAPP_MYSQL_CONFIG_USER="O|password|MySQL User",
  ONEAPP_MYSQL_CONFIG_PASSWORD="O|password|MySQL Password",
  ONEAPP_MYSQL_ADDITIONAL_ENABLED="O|boolean|Define additional parameters",
  ONEAPP_MYSQL_ADDITIONAL_SOCKET="O|text|MySQL Socket",
  ONEAPP_MYSQL_ADDITIONAL_CHARSET="O|text|MySQL Charset"
]

The user inputs will be grouped in a tab called BLOG with a group called CONF:

Also, there will be a tab called MYSQL with two groups, CONFIG and ADDITIONAL:

To see the user inputs in the ADDITONAL group, the user must turn on the Define additional parameters user input:

Additional Data for User Inputs in Sunstone

In order to help the Sunstone user, the Virtual Machine templates can be extended with an attribute called USER_INPUTS_METADATA that will be adding some info to the APPS and GROUPS.

See User Inputs Section Metadata in the VM Template reference.

So, if we use the previous Template and add the following information:

USER_INPUTS_METADATA=[
  DESCRIPTION="This tab includes all the information about the blog section in this template.",
  NAME="BLOG",
  TITLE="Blog",
  TYPE="APP" ]
USER_INPUTS_METADATA=[
  NAME="MYSQL",
  TITLE="MySQL",
  TYPE="APP" ]
USER_INPUTS_METADATA=[
  DESCRIPTION="MySQL configuration parameters",
  NAME="CONFIG",
  TITLE="Configuration",
  TYPE="GROUP" ]
USER_INPUTS_METADATA=[
  DESCRIPTION="Additional MySQL parameters",
  NAME="ADDITIONAL",
  TITLE="Additional parameters",
  TYPE="GROUP" ]

Due to the elements with TYPE equal to APP, the BLOG tab has the title Blog and the MYSQL tab has the title MySQL (TITLE attribute). Also, due to these elements we have an info note in the Blog tab (DESCRIPTION attribute):

Due to the elements with TYPE equal to GROUP, CONFIG group has the title Configuration and ADDITIONAL group has the title Additional parameters (TTILE attribute). Also, due to these elements Sunstone shows an info text in both groups (DESCRIPTION attribute):

Schedule Actions

If you want to perform a pre-defined operation on a VM, you can use the Scheduled Actions. The selected operation will be performed on the VM at a specific time, e.g., “Shut down the VM 5 hours after it started”. You can also add a Scheduled action at VM instantiation.

See Schedule Actions Section in the VM Template reference.

Set a Cost

Each VM Template can have a cost per hour. This cost is set by the CPU unit and MEMORY MB, and disk MB. VMs with a cost will appear in the showback reports.

See Showback Section in the VM Template reference.

Enable End User Features

There are a few features of the Cloud View that will work if you configure the Template to make use of them:

• The Cloud View gives access to the VM’s VNC, but only if it is configured in the Template.
• End users can upload their public ssh key. This requires the VM guest to be contextualized, and the Template must have the ssh contextualization enabled.

Make the Images Non-Persistent

If a Template is meant to be consumed by end users, its Images should not be persistent. A persistent Image can only be used by one VM at a time. The next user will find the changes made by the previous user.

If the users need persistent storage, they can use the “instantiate to persistent” functionality.

Prepare the Network Interfaces

End users can select the VM network interfaces when launching new VMs. You can create templates without any NIC or set the default ones. If the Template contains any NIC, users will still be able to remove them and select new ones.

When users add network interfaces, you need to define a default NIC model in case the VM guest needs a specific one (e.g., virtio for KVM). This can be done with the NIC_DEFAULT attribute, or through the Template wizard. Alternatively, you can change the default value for all VMs in the driver configuration file (see the KVM one for example).

Instantiating Templates

You can create a VM out of an existing VM Template using the onetemplate instantiate command . It accepts a Template ID or name, and creates a VM instance from the given Template. You can create more than one instance simultaneously with the --multiple num_of_instances option.

$ onetemplate instantiate 6
VM ID: 0

$ onevm list
    ID USER     GROUP    NAME         STAT CPU     MEM        HOSTNAME        TIME
     0 oneuser1 users    one-0        pend   0      0K                 00 00:00:16

Overwrite VM Template Values

Users can overwrite some of the VM Template values, limited to those not listed in the restricted attributes. This allows users some safe, degree of customization for predefined templates.

Let’s say the administrator wants to provide base Templates that the users can customize, but with some restrictions. Having the following restricted attributes in oned.conf:

VM_RESTRICTED_ATTR = "CPU"
VM_RESTRICTED_ATTR = "VPU"
VM_RESTRICTED_ATTR = "NIC"

And the following Template:

CPU     = "1"
VCPU    = "1"
MEMORY  = "512"
DISK=[
  IMAGE = "BaseOS" ]
NIC=[
  NETWORK_ID = "0" ]

Users can instantiate it and customize anything except the CPU, VCPU, and NIC. To create a VM with different memory and disks:

$ onetemplate instantiate 0 --memory 1G --disk "Ubuntu 16.04"

Also, a user cannot delete any element of a list that has any restricted attributes. By having the following restricted attributes in oned.conf:

VM_RESTRICTED_ATTR = "DISK/TOTAL_BYTES_SEC"

And the following template:

CPU     = "1"
VCPU    = "1"
MEMORY  = "512"
DISK=[
  IMAGE = "BaseOS"
  TOTAL_BYTES_SEC = 1 ]
DISK=[
  IMAGE = "BaseOS2" ]
NIC=[
  NETWORK_ID = "0" ]

A user can delete the second disk but cannot delete the first disk because it has a restricted attribute.

$ onetemplate instantiate 0 --disk BaseOS,"Ubuntu 16.04"

$ cat /tmp/file
MEMORY = 512
COMMENT = "This is a bigger instance"

$ onetemplate instantiate 6 /tmp/file
VM ID: 1

Deployment

The OpenNebula Scheduler will automatically deploy the VMs in one of the available Hosts, if they meet the requirements. The deployment can be forced by an administrator using the onevm deploy command.

Use onevm terminate to shutdown and delete a running VM.

Continue to the Managing Virtual Machine Instances Guide to learn more about the VM States and the available operations that can be performed.

Instantiating as Another User and/or Group

The onetemplate instantiate command accepts option --as_uid and --as_gid with the User ID or Group ID to define the owner or group for the new VM.

$ onetemplate instantiate 6 --as_uid 2 --as_gid 1
VM ID: 0

$ onevm list
    ID USER      GROUP    NAME         STAT CPU     MEM        HOSTNAME        TIME
     0 test_user users    one-0        pend   0      0K                 00 00:00:16

Managing Templates

Users can manage the VM Templates using the command onetemplate, or the graphical interface Sunstone. For each user, the actual list of templates available are determined by the ownership and permissions of the Templates.

Adding and Deleting Templates

Using onetemplate create, users can create new Templates for private or shared use. The onetemplate delete command allows the owner -or the OpenNebula administrator- to delete it from the repository.

For instance, if the previous example Template is written in the vm-example.txt file:

$ onetemplate create vm-example.txt
ID: 6

Via Sunstone, you can easily add Templates using the provided wizards and delete them by clicking on the delete button.

Cloning Templates

You can also clone an existing Template with the onetemplate clone command:

$ onetemplate clone 6 new_template
ID: 7

If you use the onetemplate clone --recursive option, OpenNebula will clone each one of the Images used in the Template Disks. These Images are made persistent and the cloned template DISK/IMAGE_ID attributes are replaced to point to the new Images.

Updating a Template

It is possible to update a Template by using the onetemplate update. This will launch the editor defined in the variable EDITOR and let you edit the template.

$ onetemplate update 3

Restricted Attributes When Creating or Updating a Template

When a user creates or updates a Template, there are some restricted attributes that they cannot create or update. By having the following restricted attributes in oned.conf:

VM_RESTRICTED_ATTR = "CPU"
VM_RESTRICTED_ATTR = "VPU"
VM_RESTRICTED_ATTR = "NIC"

And the following Template:

CPU     = "1"
VCPU    = "1"
MEMORY  = "512"
DISK=[
  IMAGE = "BaseOS" ]
NIC=[
  NETWORK_ID = "0" ]

Users can create or update a Template and customize anything except the CPU, VCPU, and NIC.

Also, a user cannot delete any element of a list that has a restricted attributes. By having the following restricted attributes in oned.conf:

VM_RESTRICTED_ATTR = "DISK/TOTAL_BYTES_SEC"

And the following Template:

CPU     = "1"
VCPU    = "1"
MEMORY  = "512"
DISK=[
  IMAGE = "BaseOS"
  TOTAL_BYTES_SEC = 1 ]
DISK=[
  IMAGE = "BaseOS2" ]
NIC=[
  NETWORK_ID = "0" ]

A user can delete the second disk but cannot delete the first disk because it contains a restricted attribute.

Sharing Templates with Other Users

The users can share their Templates with other users in their group or with all the users in OpenNebula. See the Managing Permissions documentation for more information.

Let’s see a quick example. To share the Template 0 with users in the group, the USE right bit for GROUP must be set with the chmod command:

$ onetemplate show 0
...
PERMISSIONS
OWNER          : um-
GROUP          : ---
OTHER          : ---

$ onetemplate chmod 0 640

$ onetemplate show 0
...
PERMISSIONS
OWNER          : um-
GROUP          : u--
OTHER          : ---

The following command allows users in the same group to USE and MANAGE the Template, and the rest of the users to USE it:

$ onetemplate chmod 0 664

$ onetemplate show 0
...
PERMISSIONS
OWNER          : um-
GROUP          : um-
OTHER          : u--

The onetemplate chmod --recursive option will also perform the chmod action on each one of the Images used in the Template disks.

Sunstone offers an “alias” for onetemplate chmod --recursive 640, the share action:

Managing VM Templates with Sunstone

Sunstone exposes the above functionality in the Templates > VM Templates tab:

< Previous page Next page >