How to instantiate an OpenNebula virtual machine

OpenNebula VM templates turn a saved machine definition into new running workloads. Instantiating a template is the handoff from catalog metadata, image disks, and virtual networks to an actual VM that the scheduler can place on a host.

The CLI path uses onetemplate instantiate from a shell that already authenticates to the OpenNebula frontend. A usable template should have its disk image, network, and contextualization settings resolved before launch because restricted attributes and template defaults decide what the user may override.

A VM is not ready when the instantiate command only returns an ID. The instance should move from pend to runn in onevm list, show ACTIVE and RUNNING in onevm show, and expose the network or console path expected by the template.

1. List the VM templates available to the current account.

   $ onetemplate list
     ID USER     GROUP    NAME               REGTIME
      6 oneadmin oneadmin ubuntu-24.04-base  06/25 09:14:22

   Use a template ID or name that the account can USE. A template can be visible but still fail at instantiation if image, network, quota, or group permissions are missing.

2. Inspect the template before creating the VM.

   $ onetemplate show ubuntu-24.04-base
   VIRTUAL MACHINE TEMPLATE 6 INFORMATION
   ID             : 6
   NAME           : ubuntu-24.04-base
   USER           : oneadmin
   GROUP          : oneadmin
   ##### snipped #####
   TEMPLATE CONTENTS
   CPU="1"
   MEMORY="2048"
   DISK=[
     IMAGE="Ubuntu 24.04"]
   NIC=[
     NETWORK="prod-lan"]
   CONTEXT=[
     NETWORK="YES",
     SSH_PUBLIC_KEY="$USER[SSH_PUBLIC_KEY]"]

   Confirm the image, virtual network, capacity, and contextualization values before launch. Template user inputs may prompt interactively unless the values are supplied with --user-inputs.

3. Instantiate the template with a VM name.

   $ onetemplate instantiate ubuntu-24.04-base --name web-01
   VM ID: 42

   --name sets the VM instance name. Use --multiple only when every generated VM can safely share the same template inputs, image behavior, and network selection.

4. Check the VM immediately after creation.

   $ onevm list
     ID USER     GROUP    NAME   STAT CPU     MEM        HOSTNAME        TIME
     42 oneadmin oneadmin web-01 pend   0      0K                 00 00:00:08

   pend means the VM exists but has not yet been placed on a host.

5. List the VM again after the scheduler places it.

   $ onevm list
     ID USER     GROUP    NAME   STAT CPU     MEM        HOSTNAME        TIME
     42 oneadmin oneadmin web-01 runn   1      2G         kvm-01   00 00:02:40

   If the VM remains pend or moves to a failure state, inspect scheduler capacity, host, datastore, network, quota, and template restrictions before forcing a deployment.
   Related: How to troubleshoot OpenNebula scheduling

6. Inspect the VM details after it reaches running state.

   $ onevm show 42
   VIRTUAL MACHINE 42 INFORMATION
   ID                  : 42
   NAME                : web-01
   USER                : oneadmin
   GROUP               : oneadmin
   STATE               : ACTIVE
   LCM_STATE           : RUNNING
   START TIME          : 06/25 09:18:02
   END TIME            : -
   ##### snipped #####
   VIRTUAL MACHINE TEMPLATE
   NIC=[
     NETWORK="prod-lan",
     IP="192.0.2.45"]
   
   VIRTUAL MACHINE HISTORY
    SEQ HOSTNAME REASON START        TIME       PTIME
      0 kvm-01   none   06/25 09:18 00 00:03:12 00 00:00:18

   The LCM_STATE value should be RUNNING, and the history should show the host that received the VM.

7. Test the access path provided by the template.

   $ onevm ssh 42 clouduser --cmd hostname
   web-01

   Use onevm ssh only when the template injects an SSH key and the VM network is reachable from the shell running the command. For templates that rely on console access, open the VM console after LCM_STATE reaches RUNNING.
   Related: How to open an OpenNebula VM console