This guide is part of the System Center Authoring Hub.

The Microsoft System Center team has validated this content as of Revision #7.  We will continue to review any changes and periodically provide validations on later revisions as they are made.  Please feel free to make any corrections or additions to this content that you think would assist other users.


In System Center 2012 R2 with Windows Azure Pack, Virtual Machine Roles represent a scalable tier of Virtual Machines that can be provisioned by a tenant using a single process. Examples of workloads that can be created by Virtual Machine Roles could include a single virtual machine, an Active Directory Domain Controller, a SQL Cluster, or an IIS Web Farm.

The Virtual Machine Role model allow a hoster to provide offerings to their tenants using a standard and reusable artifact that will be able to be used in both on-premises hosting environments and within Windows Azure. They can be authored in a standard format that can be easily copied and modified to suit different hosting scenarios.

The author of a Virtual Machine Role model is able to define configuration information that the user interface must collect from the tenant. This information is then used to provision a new virtual machine or set of machines, configure it with required services, and then deploy specific applications that are part of the service offering being provided by the hoster.

The basic process of how Virtual Machine Roles are used and created is illustrated in the following diagram:

  1. Author creates a Resource Extension package that defines the requirements and installation instructions for the application.
  2. Author creates a Resource Definition package that defines the configuration of the virtual machine and the user interface for collecting parameter information from the tenant.
  3. Administrator creates one or more virtual hard disks (VHD) in the VMM Library with the required operating system and configures tags required by the Resource Extension.
  4. Administrator installs Resource Extension package in Virtual Machine Manager (VMM) using Windows PowerShell cmdlet.
  5. Administrator installs Resource Definition in Service Provider Foundation (SPF) as a Gallery Item using the Service Administration Portal.
  6. Administrator publishes Gallery Item to the Gallery where it can be accessed by tenants.
  7. Tenant requests new Virtual Machine Role and completes wizard.
  8. SPF sends request to VMM which provisions new Virtual Machine Role by copying VHDs, creating and configuring virtual machines, and installing applications.            

Virtual Machine Role Gallery

The Virtual Machine Role Gallery is a catalog of Gallery Items in SPF that offer Virtual Machine Roles to tenants. Tenants view a curated and role-scoped feed of Virtual Machine Roles in the Tenant Portal UI or through the gallery REST OData APIs. A Virtual Machine Role Gallery Item is created when a Resource Definition Package is imported into the VM Gallery. The tenant uses this template to create one or more Virtual Machine Role instances.

Components of a Virtual Machine Role

A Virtual Machine Role is comprised of two packages that are packaged using Open Packaging Conventions (OPC). These packages and their contents are listed in the following table and described in detail in the linked sections of this guide.

Package Description Contents File Extension 
Resource Definition Template for a Virtual Machine Role that is offered to tenants through Gallery Items. The template includes the configuration for hardware, network, and operating system in addition to the user interface required to collect specific information from the tenant. Resource Definitions are based on a consistent model across clouds, but may have platform-specific hardware and network elements as needed to support Virtual Machine Role deployment on each platform.
  • RESDEF file
  • Viewdef file
  • Icon
  • Localization files
Resource Extension Application template installation payload used to deploy an application into a Virtual Machine Role. Depending on the requirements of the application, this may include the installation files, an MSI package, scripts, or SQL DAC application. These components are imported into the VMM Library and used when Virtual Machine Roles are deployed from the Gallery.
  • RESEXT file
  • Payload

In the current release, a single Virtual Machine Role must contain one Resource Definition and may contain one Resource Extension. Future releases may support multiple Resource Extensions.

The primary contents of each of the packages are JSON files. JSON is an open, text based format for data exchange. It is similar to XML in that it is human readable and platform independent, but it is more lightweight.

This guide does not provide guidance on JSON syntax, but several public sources are available. An example of each JSON file used in a Virtual Machine Role is provided below which will assist in learning JSON structure and syntax. A complete JSON reference for Resource Definition Templates, Resource Extension Templates, and View Definitions is available at Virtual Machine Role Resource JSON Reference.

The following topics are part of this guide and provide further information on creating and using Virtual Machine Roles.




You define parameters in the Resource Definition Template to allow the user to select different options when they provision a new resource. Parameters are used in Resource Extensions to allow them to be applied to multiple scenarios.  This topic provides details of how parameters are used in addition to standard parameter names that you should use in your Virtual Machine Roles.

VHD Tags

Virtual Hard Disks that are used with Virtual Machine Roles must have tags that identify their configuration to the Resource Extension.  This topic provides best practices for implementing a tagging strategy and for standard tags to use.

Installing a Virtual Machine Role

This topic provides the steps for creating the Resource Definition and Resource Extension Packages.


See Also

Authoring Virtual Machine Roles

Using Virtual Machine Roles