SystemVM Templates - Upgrade Imrpovements

When upgrading Apache CloudStack (ACS) to a newer version one must manually register new SystemVM templates before upgrading the packages. Failing to do so means having to roll back the database to the previous version, register the new template and start the upgrade again. We’ve developed a process (available as of CloudStack 4.16.0) to automate SystemVM template registration at the point the packages are upgraded (if not already registered).

Manual SystemVM template registration will still be supported, but not mandatory. Instead, if you update the link to the packages (eg. /etc/yum.repos.d/cloudstack.repo on a RHEL based system), and run the command ‘yum upgrade cloudstack-management’, then CloudStack will check if the systemVM templates for the specific code version are registered, and if not will automatically register the templates.

SystemVM templates for the 3 most widely supported hypervisors (KVM, XenServer and VMWare) in CloudStack are bundled into the cloudstack-management package. Once the new packages are installed, the templates will be made available on the management server at ‘/usr/share/cloudstack-management/templates/systemvm/’.


Template Location


A metadata.ini file is packaged along with the templates, holding information about the template (name, checksums, download URL and file name). The purpose of this file is to provide input to the upgrade path. These details are used to populate the tables vm_template and template_store_ref during template registration. It looks something like this:



A benefit of this metadata.ini file is that we no longer need to hardcode these details. They are dynamically fetched and collated during the build phase. A crucial point is that the templates are included as part of the cloudstack-management package only if the build is initiated with the ‘noredist’ flag.

Prior to this feature, CloudStack would verify if systemVM templates for all supported hypervisors are registered, and if not, the upgrade would terminate. From Apache CloudStack 4.16, instead of terminating the upgrade, CloudStack is attempting to register the templates automatically for the various hypervisors present across all zones.

If the templates have not been registered, CloudStack validates if the required hypervisors’ systemVM templates are available on the management server and their checksums match the value present in metadata.ini.

The next set of steps are performed on a per zone basis:

• A temporary path is created on the management server and a secondary store is mounted from the zone
• A list of all distinct hypervisors present is obtained in that zone and template registration is initiated
• Check if the template is already registered (i.e., a record is present in the vm_template table). If yes, then it validates if the template is seeded (is it present on the respective secondary store). This is especially required in freshly deployed ACS environments, where despite not having seeded the template (using the cloud-install-sys-tmplt script) the template is registered in the DB during DB setup.
• If the template isn’t registered then ACS creates a record in the tables (vm_template and template_store_ref). It then initiates copying and/or extraction of the systemVM template based on the hypervisor type from the Management Server to the mounted secondary storage path. Finally, it creates the file and un-mounts the store.
• If the template is already registered, but is not seeded, then the same steps as above are performed, except, no entry is created in the vm_template table.

Once the templates have been registered for all hypervisors across all zones, the management server starts and everything follows as usual.

In case of a fresh deployment, the systemVM template is registered during the addition of the first secondary store to the zone. The same checks are performed as above, however, any failure in setting up the required templates will not fail the secondary storage addition operation. In this situation, the administrator/user will need to seed the template the usual way using the cloud-install-sys-tmplt script.

Overall, this feature aims at making the upgrade process more seamless and the end users happy. It is available in the CloudStack 4.16 release. Hope you find it useful!