This topic is History
Resources For IT Professionals
This topic is History
The Microsoft System Center team has validated this content as of Revision #6. 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.
The Resource Definition package includes the following components:
These components are illustrated in the following diagram and discussed in detail in the following sections.
The View Definition File (VIEWDEF) defines the parameters that the user interface will present to the tenant who is provisioning a new Virtual Machine Role. This includes the information that is provided to the user to prompt them for required information.
The View Definition is not processed by SPF or VMM. It is completely used by Tenant Portal to present user interface to tenant in order to collect information required to provision the Virtual Machine Role. There is no requirement for the author to design the user interface. It will be constructed with a standard interface using the values provided in the View Definition.
The parameters that are collected from the user are organized into Sections and Categories. A separate step in the wizard is created for each section, with the Title of the section displayed at the top. Categories provide a way for parameters to be organized into groups. The Category Name of each category is displayed within the wizard step above the parameters in that category. The values for Title and Category Name often use a localized variable so that a language specific label can be displayed.
Each parameter to be collected from the tenant is defined by the attributes listed in the following table in the View Definition File. The parameters are displayed to tovided in the View Definition.
The parameters that are collected from the user are organized into Sections and Categories. A separate step in the wizard is created for each section, with the Title of the section displayed at the top. Categories provide a way for parameters to be organized into groups. The Category Name of each category is displayed within the wizard step above the parameters in that category. The values for Title and Category Name often use a localized variable so that a language specific label can be displayed.
Each parameter to be collected from the tenant is defined by the attributes listed in the following table in the View Definition File. The parameters are disphe user in the order they are defined in the file.
|
Attribute |
Description |
|
Name |
The name of the parameter. This must match with the name used in the declaration of the parameter I the Resource Definition File. |
|
Label |
The caption to display to the user in the dialog box. This can be a localized variable to display a language specific label. |
|
Type |
The data type of the parameter. Corresponds to one of the data types in the below table. |
|
DefaultValue |
The initial value to display in the field to be used if the user does not provide a value. If no default value should be used, then do not include this attribute. |
|
Description |
Description of the parameter being collected. This can be a localized variable to display a language specific description. The description is displayed to the user in the tenant console as a tooltip. |
|
Validation |
Settings to verify the validity of the value. The Required attribute specifies whether a value is required for the property or if it can be left blank. For numeric values, MinRange and MaxRange determine the range that the value must fall within. The Messages specifies the message that is presented to the user if the value of the parameter fails validation. The Required attribute specifies the message to display if a required attribute is left blank. The Range attribute specifies the message to display if a numeric value is out of range. |
All text that is presented to the tenant can be localized to the language of the tenant’s workstation. This is supported by localization files in the Resource Definition Package for each supported language. The localization files include a set of localization keys with corresponding text in the appropriate language. Rather than providing a value for a particular property in the View Definition, you can provide the key. When the text is displayed to the user, it will retrieve the text from the localization file of the language matching the user’s workstation. If that language is not available, then the default language specified in the View Definition will be used.
The syntax for using a localization tag is as follows:
{{KeyName}}For example, a section title with explicit text might look like the following:
"Title": "Virtual Machine Settings",If the localization file included a key called WS2012IISVMSettings, then the localized version of section title would look like the following;
"Title": "{{WS2012IISVMSettings}}",The Resource Definition Package can include a single file with the icon that should be displayed with it in the Virtual Machine Gallery. This file should be PNG format and measure 200x200 pixels.
Localization file contains a set of localization parameters and their corresponding text in the appropriate language. The Virtual Machine Role requires a separate localization file for each language that it will support. A sample of the contents of a localization
file
is shown below:
{ "IISWS2012Label": "WS2012 with IIS Role", "WS2012IISDescription": "Creates Windows Server 2012 VM with IIS role.", "WS2012IISVMSettings": "Virtual Machine Settings", "ScaleOutSettingGroup": "VM Configuration Settings", "VMRoleSizeDesc": "Computer Size", "VMROleSizeRequiredMessage": "Computer Size is required"}The localization file for each language can have any name but must use the extension .resources and placed in a folder in the Resource Definition Package. The name of the folder should be the language code for the appropriate language. For example, for United States English, the localization folder should be named EN-US. There should be only a single file in each localization folder.
A Resource Definition File (RESDEF) is a versioned template that describes how a resource should be provisioned. For a Virtual Machine resource, it includes such information as the following:
The contents of the Resource Definition File are illustrated in the following diagram and discussed in detail in the following sections.
Each Resource Definition must be uniquely identified by the following three properties. No two definitions may have the same values for these properties.
Virtual Machine Roles support versioning so that the newer version of a template may be installed to supersede the previous version. Note that the only Type currently allowed is MicrosoftCompute/VMRole which specifies a Virtual Machine Role. Other types may be supported in future versions.
The following JSON example shows the Identification section for a RESDEF called IIS_Demo_3.
"Name": "IIS_Demo_3","Publisher": "Microsoft","SchemaVersion": "1.0.0.0","Version": "1.0.0.0","Type": "MicrosoftCompute/VMRole",
Because a single Resource Definition can be used to provision multiple instances of a single resource, they can declare parameters which describe values that are used to configure the resource. Those parameters with values that should be provided by the tenant when they are provisioning a new Virtual Machine Role should also be included in the View Definition which describes the user interface for collecting these values.
The following JSON example shows the Resource Parameters for a sample Resource Definition. Note that the type for each parameter matches an entry in the table in the Parameters section above.
"ResourceParameters": [ { "Name": "VMRoleInitialInstanceCount", "Type&finition which describes the user interface for collecting these values.
Example
The following JSON example shows the Resource Parameters for a sample Resource Definition. Note that the type for each parameter matches an entry in the table in the Parameters section above.
"ResourceParameters": [
{
"Description": "Initial number of VMs to provision in VMRole."
},
{
"Name": "VMRoleMinimumInstanceCount",
"Type": "Number",
"Description": "Minimum number of VM instances in VMRole."
},
{
"Name": "VMRoleMaximumInstanceCount",
"Type": "Int",
"Description": "Maximum number of VM instances in VMRole."
},
{
"Name": "VMRoleUpgradeDomainCount",
"Type": "Int",
"Description": "Number of upgrade domains."
},
{
"Name": "VMRoleVMSize",
"Type": "String",
"Description": "Platform-specific VM size (for Blue: XS | S | M | L | XL)"
},
{
"Name": "VMRoleOSVHDImageNameVersion",
"Type": "String",
"Description": "Identifier of the virtual hard disk image to use in the form ge-name>:<version>.
Version is in format <major>.<minor>.<build>.<revision>"
},
&und-color:#f8f8f8;"> {
"Name": "VMRoleDataVHDNameVersion01",
"Type": "String",
"Description": "Identifier of the virtual hard disk image to use in the form <image-name>:<version>.
Version is in format <major>.<minor>.<build>.<revision>"
},
{
"Name": "VMRoleNetworkRef",
"Type": "String",
"Description": "Reference to network name to attach the NIC to."
},
{
"Name": "VMRoleNetworkIPAddressAllocationMethod",
"Type": "String",
"Description": "Static or Dynamic"
},
{
"Name": "VMRoleNetworkIPAddressType",
"Type": "String",
"Description": "IPv4 or IPv6"
},
{
"Name": "VMRoleComputerNamePattern",
"Type": "String",
"Description": "Pattern for computer name. # characters indicate sequentially-increasing numbers. * indicates randomly-generated
names."
},
{
"Name": "VMRoleAdminCredential",
"Type": "String",
"Description": "Local administrator credential in form <username>:<password>"
},
{
"Name": "VMRoleTimezone",
"Type": "String",
"Description": "Time zone. Allowed values are specified from tzutil.exe output (same as in current Azure specification
http://msdn.microsoft.com/en-us/library/windowsazure/jj157186.aspx)"
},
{
"Name": "VMRoleWindowsWorkGroupName",
"Type": "String",
"Description": "Name of workgroup. Use either WorkgroupName or DomainJoin but not both."
},
{
"Name": "IISPort",
"Type": "String",
"Description": "IISPort desc."
}
],
Resource Extension References
Each Resource Definition must declare a reference to any Resource Extension that it will work with. Since the same extension can be declared more than once, a Reference Name is required for each to uniquely identify it.
Each Resource Extension Reference must define values for parameters that are defined by the Resource Extension. Parametot;Type": "String",
"Description": "IISPort desc." }],The following JSON example shows the Resource Extension References for a sample Resource Definition. In this example, the Resource Extension is called IIS_Demo_2 and requires the value for a parameter called Port. The value from the Resource Parameter with the named IISPort is used for the value of the Resource Extension Parameter.
"ResourceExtensionReferences": [ { "ReferenceName": "IIS_Demo_2", "Name": "IIS_Demo_2", "Version": "1.0.0.0", "Publisher": "Microsoft", "ResourceExtensionParameterValues" : '{ "Port" : "[Param.IISPort]"}' }],
The Intrinsic Settings section of the Resource Definition File includes all of the settings for the virtual machines that are created by the Virtual Machine Role. This includes such information as the number of instances that will be created, the hardware
profile,
the virtual hard disks, network configuration, and configuration of the operating system. Most of these setting use parameters so that they can be provided by the tenant when they are provisioning a new Virtual Machine Role.
The Scale-Out Settings section of the Resource Definition File defines the initial number of instances of the virtual machine described by the Resource Definition File and how many instances are allowed.
The following JSON example shows the Scale-Out settings for a sample Resource Definition. In this example, Resource Parameter values are used so that the tenant can select the number of instances when they provision a new instance of the Virtual Machine Role.
"ScaleOutSettings": { "InitialInstanceCount": "[Param.VMRoleInitialInstanceCount]", "MaximumInstanceCount": "[Param.VMRoleMaximumInstanceCount]", "MinimumInstanceCount": "[Param.VMRoleMinimumInstanceCount]", "UpgradeDomainCount": "[Param.VMRoleUpgradeDomainCount]"},
The Hardware Profile section of the Resource Definition file specifies the size of virtual machine that will be deployed for instances of the Virtual Machine Role. A parameter can be used so that the size can be specified by the tenant when they provision a new Virtual Machine Role. In this case, you would create a parameter in the View Definition file with a parameter type of VMSize. This provides a dropdown list of the different sizes that are available.
The following JSON example shows the Hardware Profile settings for a sample Resource Definition. In this example, Resource Parameter values are used so that the tenant can specify the size of the virtual machine when they provision a new instance of the Virtual Machine Role. Assuming a parameter type of VMSize was used for this parameter, they could select from a drop down list of valid virtual machine sizes.
"HardwareProfile": { "VMSize": "[Param.VMRoleVMSize]"},
The Storage Profile section of the Resource Definition File describes the operating system and data VHDs that are used to provision the virtual machine. When a virtual machine is imaged, a copy of the source VHD is copied to the VM host.
The storage profile declares the VHD by specifying a name and version of the VHD object. A parameter can be used so that the VHD can be specified by the tenant when they provision a new Virtual Machine Role. In this case, you would create a parameter in
the VIEWDEF with
a type of OSVirtualHardDisk. This provides a dropdown list of all VHDs in the VMM Library that have the tags specified in the Resource Requirements section of the RESEXT.
The following JSON example shows the Storage Profile settings for a sample Resource Definition File. In this example, Resource Parameters values are used so that the tenant can select the specific OS and data VHDs when they provision a new instance of the Virtual Machine Role. Assuming a parameter type of OSVirtualHardDisk was used for either of these disks in the View Definition File, they could select from a drop down list of valid disks instead of typing in the name.
"StorageProfile": { "OSVirtualHardDiskImage": "[Param.VMRoleOSVHDImageNameVersion]", "DataVirtualHardDisks": [ { "DataVirtualHardDiskImage": "[Param.VMRoleDataVHDNameVersion01]", "Lun": "1" } ]},
The Network Profile section of the Resource Definition File specifies one or more virtual network adapters that should be attached to the VM. It specifies what network each adapter should be attached to as well as an array with the IP addresses. The IP addresses can be configured for the appropriate protocol as well as whether its allocation method is static or dynamic.
Each IP address can be associated with zero or one Load Balancer Configuration that describe the requirements for the load balancers needed for that IP address. The Load Balancer configuration specifies the required front end network, probe, and port configuration. Note that in the current release, the front end and back end ports must be identical.
The following JSON example shows the Network Profile settings for a sample Resource Definition File. In this example, Resource Parameters values are used so that the tenant can specify the IP configuration when they provision a new instance of the VM Role.
"NetworkProfile": {
"NetworkAdapters": [
{
"Name": "Nic1",
"NetworkRef": "[Param.VMRoleNetworkRef]"
"IPAddresses": [
{
"AllocationMethod": "[Param.VMRoleNetworkIPAddressAllocationMethod]",
"Type": "[Param.VMRoleNetworkIPAddressType]",
"ConfigurationName": "IPV4Config"
"LoadBalancerConfigurations" : [
{
"ConfigurationName" : "MyLBConfiguration"
"FrontEndNetwork" : "internet"
"PortConfig" : {
"Name" : "MyPortConfig",
"Protocol" : "HTTP",
"FrontEndPort" : 80,
"BackEndPort" : 80
},
"Probe": {
"MaxRetryCount" : 5,
"Port" : 8080,
"ProbeIntervalInSeconds" : 20,
"Protocol" : "HTTP",
"RequestPath" : "http://myrequest",
}
}
]
}
], //IPAddresses
}
]
},
The Operating System Profile specifies configuration of the operating system that is performed after the OS VHD is copied as part of provisioning the new Virtual Machine Role and before any applications are installed by the Resource Extension.
The Operating System Profile is not required. If it is not included, then the configuration of the operating system on the OS VHD is used without modification.
The following JSON example shows the Operating System Profile settings for a sample Resource Definition File. In this example, Resource Parameters values are used so that the tenant can specify the settings when they provision a new instance of the VM Role.
"OperatingSystemProfile": { "AdminCredential": "[Param.VMRoleAdminCredential]", "ComputerNamePattern": "[Param.VMRoleComputerNamePattern]", "LinuxOperatingSystemProfile": null, "TimeZone": "[Param.VMRoleTimezone]", "WindowsOperatingSystemProfile": { "WorkgroupName": "[Param.VMRoleWindowsWorkGroupName]" }}
Resource Extension Package
Parameters
VHD Tags
Installing a Virtual Machine Role
Sample Virtual Machine Role Packages
Virtual Machine Role Resource JSON Reference