PR

https://github.com/apache/cloudstack/pull/3748

Introduction

There are a number of occasions when a cloud operator must register and make active a system VM template, including:

  • When creating the first zone in CloudStack.
  • When adding a new zone in CloudStack.
  • When adding a new hypervisor to a CloudStack zone.
  • When replacing the existing template with a one containing newly applied security patches.
  • Changing to a custom System VM templates. For example, opening a specific port on a System VM for monitoring purposes or installing a monitoring agent that needs to run in the System VM template.
  • Downgrading to a previous version of a System VM template. For example, reverting a security patch that is causing errors.

The system VM template APIs will do the work of getting the required template image into secondary storage in these cases.

Purpose

This is the functional specification of the system VM template API

Document History

VersionAuthor/ReviewerDate
1.0Darrin Hüsselmann

 

Feature Specifications

This feature adds an Application Programming Interface (API) and User Interface (UI) that will enable an administrator to:

  • Upload a system VM template to the management server and into secondary storage from a web browser.
  • Register a system VM template by specifying a URL or choosing an official Cloudstack system VM template to download.
  • Copy a system VM template from an existing zone.
  • Activate a system VM template.
  • List inactive system VM templates.

Functional Abilities

  • Upload a system VM template from a browser running on a local machine to secondary storage (via the management server).
  • Install a system VM template from a URL.
  • Install a system VM template from the official template locations stored in the database.
  • Copy a system VM template from one zone to another (via the management server)

These options are available from the add zone wizard and the template upload and register forms.

Architecture and Design description

An administrator will have the option to install a system VM template from the zone creation wizard, the "Register template" form, the "Upload from local" form and by calling the seedSystemVMTemplate API command. 

Multiple system VM templates can be uploaded to the management server, but only one can be active per hypervisor. Once a system VM template is activated, all other system VM templates for the specific hypervisor is deactivated. Deactivated system VM templates are not returned by the listTemplates command, unless the templateFilter parameter is set to "Inactive".

Web Services APIs

getSystemVMTemplateDefaultURL - Returns the URL where to download the official Cloudstack system VM template for a specific hypervisor. This API was used to populate the name and description fields when selecting a hypervisor in the web UI.

seedSystemVMTemplate - Copies a system VM template into secondary storage.

activateSystemVMTemplate - Sets a specific system VM template to be used for a specific hypervisor. 


NameParametersRequiredUsage

Name 

Parameters 

Required 

Usage 

ActivateTemplate 

templateId 

Yes 

The id of the template to be set as the system VM template to use.

SeedSystemVMTemplate 

fileuuid 

No 

The uuid of the file that was uploaded to the management server for seeding the template. 

 

hypervisor 

Yes 

The target hypervisor 

 

zoneid 

Yes 

Destination zone id 

 

url 

No 

URL where to download the system VM template from. 

 

localfile 

Yes 

Boolean indicating if a file was uploaded to the management server 

GetSystemVMTemplateDefaultUrl 

 

hypervisor 

Yes 

The target hypervisor. 

UI flow

The "Upload from local" and "Register template" forms have been extended to allow the installation of the system VM template:

A new template type dropdown has been added to choose between a system or user template:

In the "Register Template" form, "Template Type" and an "Official Cloudstack Template" option have been added to the source template dropdown.


The add zone wizard has been extended to allow an opportunity to install the system VM template from the 4 different sources:

A new filter option allows the listing of inactive templates:

The need for a new filter was identified to allow an admin to see deactivated templates. When activating a template for a specific hypervisor, all other templates for that hypervisor becomes inactive and removed from the list of templates. Using the inactive filter will then list those inactive templates.

IP Clearance

N/A

Usage Impact

N/A



  • No labels