This is part 3 from the blog series written by MVP Marc van Eijk (@_marcvaneijk)
In the previous blog post of this series we looked at the VM Role from a high level. In this part the Resource Definition package will be discussed. There is a lot of ground to cover and for an average blog I would cut this one into five or six different parts. But for this type of blog I think it is very useful to have all the information related to the Resource Definition in one part. So please bear with me as we dive into every detail of the Resource Definition package.
The Resource Definition package is imported in Windows Azure Pack. This package is a compressed file. Renaming the .resdefpkg extension to .zip allows you to browse the content of the Resource Definition Package with Windows Explorer.
The following files are part of the Resource Definition Package
- Resource Definition File (RESDEF) is a template that contains all parameters required for the VM Role deployment engine (System Center Virtual Machine Manager).
- View Definition File (VIEWDEF) defines the form used to collect parameters from the user at deployment time.
- Icon is used display an image on the VM Role gallery item.
- Localization Files are used to display the gallery item deployment wizard with localized values.
When you open the VM Role Authoring Tool to create a new Resource Definition, the first thing you will notice is that the menu bar provides two choices that are related to the Resource Definition. The first option is a new Resource Definition Package and the second option is the Resource Definition File. The Resource Definition File is part of the Resource Definition Package.
Select new Resource Definition Package. In the navigation pane a new Resource Definition is created.
The Resource Definition package consists of 8 entries.
- Extension References
- Parameters
- ScaleOut
- Hardware Profile
- Storage Profile
- Network Profile
- Operating System Profile
- View Definition
Parameterized or Hard-coded
An important task for the Resource Definition is to gather information. For most fields you can choose in what way information is gathered. This information can be hard-coded or entered by the tenant.
Parameterized
It is possible to parameterize the field. This parameter is then made available in the view definition that is presented to the tenant in the gallery item wizard at deployment time. The View Definition provides many options for customizing how a field is presented during the deployment wizard as we will see later in this blog.
The VM Role Authoring Tool provides easy guidance to what fields can be parameterized. If there is a dropdown icon at the right site of a field, the value can be parameterized. Parameters are referenced by specifying the format [param.ParameterName] as the field value. If you parameterize a value, a parameter is created that will be visible to the tenant in the gallery item deployment wizard.
Hard-coded
If you enter the required information directly in a field of the Resource Definition, there is no parameter created and that field will not be visible to the tenant in the gallery item deployment wizard.
When you create a new Resource Definition package in the VM Role Authoring Tool, a couple of fields are parameterized by default. If you set all these fields to fixed values, the tenant will only be asked for the name of the VM Role object in the gallery item deployment wizard.
Some values are required. These fields are marked with a * throughout this blog
Extension Reference
The resource definition can contain a reference to a resource extension. The resource extension is optional for the VM Role. If you create a Resource Definition Package without a reference to a resource extension, you only have to import the Resource Definition in Windows Azure Pack. You do not have to import a resource extension package in System Center Virtual Machine Manager.
All application logic is configured within the resource extension, so this reference is configured in most scenarios.
It is possible to define all the reference values manually or you can use the build in feature of the VM Role Authoring Tool to reference an extension reference that is currently opened in the VM Role Authoring Tool.
Select to Auto Populate | Allows you to select the Resource Extension packages that are currently open in the VM Role Authoring Tool. When you select a Resource Extension the reference fields are populated automatically and it creates parameters in the Resource Definition that map to the parameters in the Resource Extension. When you have a Resource Extension referenced you can also select to unbind. This removes the reference to the Resource Extension and also removes the parameters in the Resource Definition that are mapped to the parameters in the Resource Extension. Please note that all customization on these parameters in the View Definition is also lost. |
Reference Name | The reference name describes the Resource Extension. |
Name | The Name referenced must match the Name defined in the Resource Extension. |
Publisher | The Publisher referenced must match the Publisher defined in the Resource Extension. |
Version | The Version referenced must match the Version defined in the Resource Extension. |
Resource Extension Parameters | For each parameter in the Resource Extension a mapping must be created to a Parameters in the Resource Definition. The built-in feature of the VM Role Authoring Tool to Auto Populate a Resource Extension reference, creates parameters with format [param.<Resource Extension Name><Parameter>]. If the Resource Extension has a name of marcvaneijk and the Parameter in the Resource Extension is called PRM01 then the VM Role Authoring Tool will generate the following parameter in the Resource Definition [param.marcvaneijkPRM01]. If you want to use a different naming convention you can change the parameter value directly after the values are generated. |
Parameters
The Parameters tab in the Navigation pane displays all parameters within in the Resource Definition. These parameters are passed to the View Definition and visible to the tenant in the gallery item deployment wizard. The parameters consist of the parameterized values in the Resource Definition and the parameters that are mapped to parameters in the Resource Extension.
Name | The name column displays the name of the parameter. Parameters are referenced by specifying the format [param.ParameterName] as the field value. The name field displays the Parameter name without the [param.] format. |
Type | The type column allows you to select the type of parameter with a dropdown. The VM Role has five Parameter types. Each type has a different effect on the working of a parameter.
|
Description | User friendly description that is only used in this table. It is recommended to give clear descriptions for easy reference later. Notice that descriptions for parameters generated in the Resource Definition are configured with good description by the VM Role Authoring Tool automatically. Descriptions for parameters that map to parameters in the Resource Extension are created in the format Resource Extension <Resource Extension Name>. Parameter <Parameter Name>. <Parameter Description in the Resource Extension>. This can create long descriptions that are not always very clear. You can change the description at any time. |
Scale Out
A VM Role is a single tier. A tier consists of one or more instances. Each instance is a virtual machine that is considered equal to other instances within the tier. A tier can be scaled out, which will create additional instances within the same tier. The Scale Out tab in the navigation pane allows you to configure the Scale Out settings for a gallery item. All values can be hard-coded or parameterized. If you do not want to use the Scale Out option for a gallery item, hard-code all values to the value of 1.
InitialInstanceCount * | This value specifies the number of instances that will be deployed within the tier at provisioning time. |
MaximumInstanceCount * | The maximum number of instances that can be scaled out to within the tier. |
MinimumInstanceCount * | The minimum number of instances that is required within this tier. |
UpgradeDomainCount * | The upgrade domain is used for updating a gallery item. VMM upgrades one upgrade domain at a time, shutting down the virtual machines running within the upgrade domain, updating them, bringing them back online, and then moving on to the next upgrade domain. By shutting down only the virtual machines running within the current upgrade domain, VMM ensures that an upgrade takes place with the least possible impact to the running service.
|
Hardware Profile
The Hardware profile allows you to hard-code or parameterize the Cpu and Memory combination that will be assigned to each instance in the tier. The list of VM sizes for the VM Role are predefined in Virtual Machine Manager. You can retrieve the existing values by running the following command on the VMM server.
Get-CloudVMRoleSizeProfile | ft Name, Description, CpuCount, MemoryInMB –AutoSize
Name | Description | CpuCount | MemoryInMB |
ExtraSmall | Extra Small Size VM | 1 | 768 |
Small | Small Size VM | 1 | 1792 |
Medium | Medium Size VM | 2 | 3584 |
Large | Large Size VM | 4 | 7168 |
ExtraLarge | Extra Large Size VM | 8 | 14336 |
A6 | A6 Size VM | 4 | 28672 |
A7 | A7 Size VM | 8 | 57344 |
The built-in CloudVMRoleSizeProfiles cannot be removed with the Remove-CloudVMRoleSizeProfile. It is possible to change these built-in profiles with the Set-CloudVMRoleSizeProfile. You are able to set CpuCount, MemoryInMB and Description. The name cannot be changed. To change the CpuCount, MemoryInMB and Description for the built-in ExtraLarge profile run the following cmdlet
Get-CloudVMRoleSizeProfile -name ExtraLarge | Set-CloudVMRoleSizeProfile -CPUCount 10 -Description “Some Other Description” -MemoryMB 28672
In addition to the built-in CloudVMRoleSizeProfiles, it is possible to add, change and delete new profiles. Take note that the Name parameter can only contain alphabet letters, numbers, underscores (_), and dashes (-) and has a maximum value of 100 characters.
To create a new hardware profile run the following cmdlet on the VMM server.
New-CloudVMRoleSizeProfile -Name "A8" -Description "A8 Size VM" -CPUCount 32 -MemoryMB 131072
Storage Profile
The storage profile tab in the Navigation pane displays the configuration of the disk(s) for the instances in the tier. Disk that are referenced here must be present in the VMM Library. Before disks can be used some values must be configured within VMM.
The following disk properties in VMM are relevant to the VM Role
- Family name is a text field that should indicate the contents of the virtual hard disk. This value can be set to anything, but it is recommended to configure a meaningful value.
- Version allows you to configure multiple versions of the same Operating System disk. This field is configured in the x.x.x.x number format (for example 1.0.2.1). A version increment in useful for internal tracking if you for instance update an image with new windows updates. The original disk has version 1.0.0.1 and the new disk with the same family name and operating system has version 1.0.0.2. In later blogs on versioning and life cycle management this process is discussed in more detail.
- Operating System describes the Operating System that is present within the virtual hard disk
- Tags are configured on virtual hard disk containing an Operating System for filtering and validation purposes. In the view definition tags can be configured to filter field where the tenant can select the Operating System disk (if that value was parameterized), so only disks that have matching tags are displayed in the deployment wizard. You can also configure tags in the resource extension. These tags must match the disk selected by the tenant in the deployment wizard. If these tags do not match, the deployment fails.
The combination of the family name and the version makes a disk unique for the VM Role in Windows Azure Pack. If two disks with the same family name and version number are referenced in the same VM Role configuration the deployment will fail.
All settings can be configured in the VMM console except the tags that must be configured through PowerShell. To configure the name, version and operating system open the properties tab of disk located in the VMM Library.
For a Windows based gallery item the Operating System must be set to a Windows Server setting. When the Operating System entry is set to a Windows client or a non-Microsoft Operating System, the disk will not be displayed in the gallery item deployment wizard.
To configure the tags on a disk run the following cmdlets on the VMM server.
# Get a list of all disks in the VMM library. Display the id, the current tags (if available) and the path of the disk.
get-scvirtualharddisk | ft name, id, tag, location -Autosize
# Set the tags on a disk with ID a52a3ce6-155c-4eb0-9213-674c73565e4d.
$myVHD = get-scvirtualharddisk -id a52a3ce6-155c-4eb0-9213-674c73565e4d
Set-SCVirtualHardDisk –virtualharddisk $myVHD –Tag "WindowsServer2012","R2"
The storage entry in the VM Role Authoring Tool contains an entry for the virtual hard disk with the Operating System and a table for one or more data virtual hard disks.
OS Virtual Hard Disk Image * | This field specifies the disk that contains a sysprepped Operating System. The OS Virtual Hard Disk Image is required. By default this field is parameterized. Requirements in VMM
|
Data Virtual Hard Disks | The data virtual hard disks are optional and configured in this table. A data virtual hard disk can contain data or just be empty disks. Data Virtual Hard Disks have the following requirements in VMM
|
Data disks can also be used to contain the installation bits for applications. The advantage of this configuration is that the installer can be executed locally (within the VM) instead of accessing the installation bits on some share using Runas credentials.
A virtual machine configured with multiple data disks is not an uncommon configuration. If you want to allow the tenant to select multiple data disks from different data disk sizes you will quickly find out that creates some challenges. Consider the following scenario. You want to provide the tenant the option to select two data disks choosing between a 50, 100 and 150 GB disk. You configure three disks with the correct sizes and copy the disks to the VMM library. In VMM you configure each disk with a family name and a version number.
Disk | Family Name | Version | Operating System |
50GB.vhdx | 50GB_Data_Disk | 1.0.0.0 | None |
100GB.vhdx | 100GB_Data_Disk | 1.0.0.0 | None |
150GB.vhdx | 150GB_Data_Disk | 1.0.0.0 | None |
On the storage tab in the resource definition you configure two Data Virtual Hard Disks and you parameterize each entry with a different parameter. The Lun values can be hard-coded.
When a tenant selects this gallery item, the deployment wizard presents two data disk dropdown fields displaying the same three disks for each dropdown. When a tenant selects the same data disk on both dropdown fields the deployment will fail because two disks with the same family name and version are selected. This issue is even more complicated if multiple gallery items are required to have a different disk selections. For instance a 200GB disk and a 300 GB disk. When these disks are configured with the correct properties in VMM each gallery item will display all the data disks in the dropdown fields (50,100,150,200 and 300GB). There is no option to filter the data disks.
The OS virtual Hard Disks can be filtered with tags. The view definition only allows you to filter on these tags for the parameter type OSVirtualHardDisk. However it is possible to change the parameter type for the Data Disks from DataVirtualHardDisk to OSVirtualHardDisk in the View Definition. Enabling filtering on tags for a data disk.
Before a data disk will surface in the deployment wizard with the parameter set to OSVirtualHardDisk in the View Definition a couple of things need to be configured.
· The data disk must be configured with an operating system in VMM. The operating system value must be set to a Windows Server value, otherwise the disk will not show in the deployment wizard. It is recommended to select a value that you will never use for a VM Role operating system, like Windows NT Server 4.0
· The data disk must be configured with one or more tags in VMM. Instead of using the predefined tags from the View Definition, create tags that reflect the purpose. For instance "50GB", "Datadisk" and "Lun2"
· The parameter in the view definition must be configured with the same tags configured on the data disk in VMM. In the View Definition add some or all tags that you created on the data disks. For instance "Datadisk" and "Lun2"
Network Profile
Network Profile contains the configuration of the network. One network adapter is prepopulated. You can add additional NICs.
Name * | The name specified in this field is displayed in the devices entry on the dashboard tab of a deployed VM Role. This field is informational and the value is not used within the Operating System to rename the NIC. |
NetworkRef * | A tenant can have access to multiple network within his subscription. These networks could be based on VLANs predefined by the admin or using network virtualization created by the tenant from Windows Azure Pack. The NetworkRef field references the network that should be connected to this network adapter. It is recommended to parameterize this field so the tenant is able to select what network is required in the VM Role deployment wizard. It is possible to hardcode this field, but if the tenant does not have access to that network within his subscription the deployment will fail. |
IPV4 Address Enabled? | This checkmark allows you to enable the IPV4 configuration for this network adapter. This field cannot be parameterized in the VM Role Authoring Tool. This checkmark is enabled by default. |
IPV4 Address ConfigurationName | This field describes the identification for this IP address configuration and must be unique in this resource definition. |
IPV4 Address Allocation Method | The allocation method can be set to static or dynamic. Based on the type of VM Network and IP Pool configuration in VMM this settings can have different results. A VM Network based on a VLAN that is configured by the Admin in VMM with an IP Pool, has the following result when settings this value to
A VM Network based on network virtualization that is configured by the tenant with an IP Pool automatically configured in VMM by Windows Azure Pack, has the following result when settings this value to
|
LoadBalanced Behind IPV4 VIP? | The VM Role allows you to scale within the tier. Scaling a tier is useful for high availability and load balancing. Some applications provide an inbox load balancing mechanism other applications required an external load balancer. Some load balancers can be integrated with System Center Virtual Machine Manager. The VM Role can use this integration to interact with the Load Balancer to create/update/delete a configuration. When you enable this checkmark the following prerequisites in VMM apply:
Note: service templates in System Center Virtual Machine Manager require a VIP template for a deployment with a Load Balancer. The VM Role creates the VIP template ate deployment time based on the values specified in the following fields so a VIP template is not required in VMM. Within the VM Role a Load Balancer configuration is currently only possible with VM Networks based on VLANs as FrontEnd and BackEnd network. This limitation is caused by the lack of support for network virtualization by the Load Balancers that can integrate with System Center Virtual Machine Manager. When a deployed VM Role is configured with a Load Balancer Configuration an additional entry with virtual IP (VIP) is displayed in the devices table on the dashboard tab.
|
Configuration Name | This field describes the identification for this Load Balancer configuration and must be unique in this resource definition. |
FrontEnd Network | The FrontEnd Network is a similar field type as the NetworkRef and defines the network that receives inbound connections for the Load balanced VM Role instances. It is recommended that this field is parameterized, which allows the tenant to select the network for inbound connections. If you hard-code this field and the tenant does not have access to this FrontEnd Network in his subscription the deployment will fail. The FrontEnd network can be set to the same network configured on the instances in the VM Role. This configuration enables internal Load Balancing. Inbound connection are located on the same subnet as the VM Role instances. The FrontEnd network can also be set to an external network. This configuration enables external Load Balancing. Inbound connections are located on the public internet and the VM Role instances are configured on an internal VLAN. This configuration requires the tenant to have access to the External VM Network in his subscription, which can result in an undesired selection of the external network for the NetworkRef in the VM Role. |
PortConfig Name | This field describes the identification for this Port Configuration and must be unique in this resource definition. |
PortConfig Protocol | The load balancer configuration in the VM Role can be configured with the HTTP or HTTPS protocol. You can only choose one protocol per IPV4 configuration for each NIC. If you parameterize this field a parameter (type Option) is created in the View Definition with Http and Https as an option. This parameter type presents the two values as a dropdown to the tenant in the VM Role deployment wizard. Please note that the deployment fails if the tenant does not change this field in the VM Role deployment wizard. Add a default value to the parameter in the View Definition matching the Option Key value of the first option to prevent the issue. |
FrontEnd Port | The FrontEnd port defines the port that is used for inbound connection on the virtual IP (VIP). It is possible to deviate from the standard ports for Http and Https. For instance you can define the PortConfig Protocol to Http and the FrontEnd Port to 81. |
BackEnd Port | The BackEnd Port is used for the load balanced connections to the instances in the VM Role. The FrontEnd and BackEnd Port must be identical for the current release of Windows Azure Pack. |
Probe Enabled? | This checkmark allows you to configure Probing for this Load Balancer configuration. This field cannot be parameterized in the VM Role Authoring Tool. This checkmark is unchecked by default. |
Probe Interval (sec) | The interval between probes in seconds. |
Probe Protocol | The Protocol that is used for the Probe. If you parameterize this field, it is set to the same parameter used PortConfig Protocol field. It is possible to define an alternative parameter. In the view definition a parameter (type Option) is created with HTTP, HTTPS and TCP as an option. This parameter type presents the three values as a dropdown to the tenant in the VM Role deployment wizard. Please note that the deployment fails if the tenant does not change this field in the VM Role deployment wizard. Add a default value to the parameter in the View Definition matching the Option Key value of the first option to prevent the issue. The probe must return 200 for Http and Https, and must return ACK for TCP. |
Probe Port | The port that is used for the Probe. |
Probe Max Retry Count | The maximum retry count for incoming probe requests. |
Probe Request Path | The path that the load balanced probes. For example a path for a probe configured with Http as Probe Protocol can be http://VMRoleInstance/healthcheck.aspx. |
IPV6 Address Enabled? | All the settings for the IPV6 are the same as the he IPV4 settings. It is possible to configure IPV4 and IPV6 for the same network adapter. But the network adapter can only be load balanced behind either an IPV4 VIP or an IPV6 VIP, but not both. |
OS Profile
The OS Profile tab defines the operating system type, the computer name and if the instances are part of a workgroup or a domain.
Select * |
|
ComputerNamePattern * | The VM Role can be scaled out with additional instances in the same tier. The computer name pattern defines the computer names for the individual instances. A computer name pattern ending with one or more # characters will result in an incremental number. For instance a computer name pattern of MyVM## results in the first deployed instance with the computer name MyVM01 if you scale out a tier the next instance is called MyVM02. The incremental number is defined by Virtual Machine Manager and is maintained over all deployed VM Roles. The following example describes the working of the computer name pattern. If Tenant A deploys a gallery item with a computer name pattern of MyVM## with an initial instance count of one, the instance is named MyVM01. If Tenant B deploys a gallery item after that with the same computer name pattern of MyVM## and an initial instance count of two, these instances are called MyVM02 and MyVM03. System Center Virtual Machine Manager will always generate a new computer name by incrementing the latest deployed instance. So if Tenant B deleted MyVM02 and Tenant A scales with an additional instance, that instance will be assigned the computer name MyVM04 and not MyVM02. If a tenant specifies a computer name without one or more # characters at the end of the computer the tier can only consist of one instance and cannot be scaled out afterwards. |
TimeZone * | The TimeZone field is used to set the time zone in the Operating System during the customization phase. By default this value is parameterized and the tenant is asked for the time zone at deployment time. A dropdown with all possible time zones is displayed. It is also possible to hardcode a time zone, which hides this field from the deployment wizard in Windows Azure Pack and sets the time zone to the hardcoded value. For a complete list of all valid values run tzutil.exe /l from a command prompt. |
AdminCredential * | This credential is configured as local administrator on the VM Role instance. When you create a new resource definition package and import that in Windows Azure Pack you will notice that the username field is set to Administrator and greyed out, although that value was not configured as a default value neither was it set to not configurable in the view definition. If you want to allow the tenant to define the username for the AdminCredential as well move the AdminCredential parameter to a different section in the view definition. |
Select * |
|
WorkgroupName | Only valid for WorkGroup selection. Specifies the name of the Workgroup that will be configured in the customization phase. |
DomainToJoin | Only valid for JoinDomain selection. The domain that this computer is joined to. |
DomainJoinCredentials | Only valid for JoinDomain selection. These credentials are used to join the computer to the domain. If you parameterize this value the wizard asked the tenant for these credentials. It is also possible to hardcode the credentials in this field by using the domain\user:password format. Hardcoding the credentials hides this field from the provisioning wizard in Windows Azure Pack and allows a tenant to add a computer to the domain without knowing the required credentials. Just like a RunAs in System Center Virtual Machine Manager. Note that hardcoded credentials are stored in plain text in the resource definition. Access to the resource definition file itself, also gives access to hardcoded credentials stored in the file.
|
DNSDomainName | This value is only valid and accessible in a Resource Definition file when Linux is the selected Operating System |
SSHPublicKey | This value is only valid and accessible in a Resource Definition file when Linux is the selected Operating System |
View Definition
The View Definition is used to create the tabs and fields in the gallery item deployment wizard. When you parameterize a field in the Resource Definition, the parameter shows up in the View Definition. The View Definition has the following entries in the VM Role Authoring Tool.
- Section represents a tab in the gallery item deployment wizard. You can create multiple sections. A Section must contain at least one Category.
- Category defines a selection of parameters in tab. You can create multiple Categories in a single section. A category must at least contain one parameter.
- Parameter is used to render the field in the gallery item deployment wizard. You can assign multiple parameters to a category.
- Category defines a selection of parameters in tab. You can create multiple Categories in a single section. A category must at least contain one parameter.
- Resources contains one or more languages for localizing the View Definition.
- Language matches variables set in the View Definition to localized values.
The View Definition tab in the Navigation pane contains general settings and icons.
Label * | The label is used in Windows Azure Pack to display the name of the VM Role. The field is displayed in the gallery tab on the VM Clouds entry in the Admin Portal. It is displayed in the VM Role gallery in the Tenant Portal allowing the tenant easily select the correct VM Role. The dashboard tab of a deployed VM Role also displays this field. By default this field is localized in the View Definition. For more information on localization refer to the Resources entry later in this blog. It is possible to hard-code this field. |
PublisherLabel * | The PublisherLabel is used in Windows Azure Pack to display the publisher of the VM Role. The field is displayed in the gallery tab on the VM Clouds entry in the Admin Portal. It is displayed when a Tenant selects a gallery item in the VM Role gallery in the Tenant Portal. The dashboard tab of a deployed VM Role also displays this field. By default this field is localized in the View Definition. For more information on localization refer to the Resources entry later in this blog. It is possible to hard-code this field. |
Description * | The Description is used in Windows Azure Pack to display the description of the VM Role. For Example the operating system and the application. The field is displayed when the Admin select a gallery item in the gallery tab on the VM Clouds entry in the Admin Portal. It is displayed when a Tenant selects a gallery item in the VM Role gallery in the Tenant Portal. The dashboard tab of a deployed VM Role also displays this field. By default this field is localized in the View Definition. For more information on localization refer to the Resources entry later in this blog. It is possible to hard-code this field. |
DefaultLanguageCode * | Localization allows for localized fields. If the browser settings define a language that is not configured within the view definition the language is set to the value specified in the DefaultLanguageCode. By default the VM Role Authoring Tool set the DefaultLanguageCode to the prepopulated language resource en-US. |
Version * | The version number is only used within the View Definition. The version displayed in Windows Azure Pack is the version set in Resource Definition. Versioning depends on versions set in the Resource Definition, Resource Extension Reference and the Resource Extension. |
Small Icon (30x30) * | The small icon is used in Windows Azure Pack to display an image of the VM Role in the VM Role gallery in the Tenant Portal allowing the tenant easily select the correct VM Role. It is recommended to create a transparent PNG with the exact size of 30px by 30px for best quality. Select the browse button to select the correct .png file. After selecting the correct image, click update to copy the image to the working directory and update the path to a relative value. |
Medium Icon (60x60) * | The medium icon is used in Windows Azure Pack to display an image of the VM Role when the Admin select a gallery item in the gallery tab on the VM Clouds entry in the Admin Portal. It also is displayed when a Tenant selects a gallery item in the VM Role gallery in the Tenant Portal. It is recommended to create a transparent PNG with the exact size of 60px by 60px for best quality. Select the browse button to select the correct .png file. After selecting the correct image, click update to copy the image to the working directory and update the path to a relative value. |
Large Icon (120x120) * | The large icon is used in Windows Azure Pack to display an image of the VM Role in the dashboard tab of a deployed VM Role. It is recommended to create a transparent PNG with the exact size of 120px by 120px for best quality. Select the browse button to select the correct .png file. After selecting the correct image, click update to copy the image to the working directory and update the path to a relative value. |
Section
A section presents a tab in the VM Role gallery item deployment wizard. If you do not specify any parameters in the Resource Definition, it is not possible to create a section in the view definition. In that case the deployment wizard presents a single tab to ask the tenant for the name of the VMRole, the subscription (if multiple subscriptions are available) and the version (if multiple versions are available).
When parameters are configured within the Resource Definition, the View Definition requires at least one Section and at least one Category. When many parameters are configured in the Resource Definition the Tenant is displayed with a long list of questions that in an unordered format is not very compelling to complete. To add a Section, select the ViewDefinition entry in the navigation pane open the Add menu on the menu bar and select View Definition Section.
Create additional Sections to separate the parameters amongst different tabs in the gallery item deployment wizard. For instance, create a section with parameters related to the virtual machine and an additional section with parameters related to the application.
By default this field is localized in the View Definition. For more information on localization refer to the Resources entry later in this blog. It is possible to hard-code this field.
Category
A category is a selection of parameters in section. You can create multiple categories in a single section. A category must at least contain one parameter. When many parameters are configured in the Resource Definition, categories can be used to group parameters. For instance a category with networking parameters and a category with disk parameters. To add a Category, select the Section entry (that requires the new Category) in the navigation pane open the Add menu on the menu bar and select View Definition Category.
By default this field is localized in the View Definition.
For more information on localization refer to the Resources entry later in this blog. It is possible to hard-code this field.
Parameter
Each parameter that is configured in Resource Definition is part of the View Definition. Each parameter in the View Definition is configured with a parameter type. The parameter type defines the options that are available for configuring how the field is presented to the user in the gallery item deployment wizard in Windows Azure Pack. The following parameter types available in the View Definition.
String | The parameter type renders a text field that accepts a string value.
|
Number | Displays the field to capture an integer.
|
Boolean | A Boolean is rendered as a checkmark that accepts TRUE (checked) or FALSE (unchecked).
|
Credential | This parameter type displays one field to capture the username value and two fields to capture the password. The password must be re-entered in the second field for confirmation. The password must contain 3 of the following:
Note: The credential field captures the value in the format user:password or domain\user:password. If you want to prepopulate the information, only specify the username as the default value. Setting the default value to user:password, the password is displayed in plain text in the gallery item deployment wizard. If you want to predefine the username and password hard-code the information in the Resource Definition. The Resource Definition is not rendered in the gallery item deployment wizard, but appended to the captured values from the View Definition after the user submits the VM Role. |
SecureString | A secure string consists of two fields. The value must be re-entered in the second field for confirmation.
The SecureString prevents other users from eavesdropping, when the tenant submits confidential information. The information is made available to the Resource Extension in plain text. |
Option | The parameter type option is rendered as a dropdown field. Multiple entries in the dropdown field can be configured. Each option consists of two values. The value that is passed as the parameter when selected and the user friendly value that is displayed in the dropdown field.
It is important to configure a default value for the option parameter type. If you do not configure the default value and the user does not click this field in the gallery item deployment wizard, the value that is displayed in the dropdown field is not captured. It is possible to set the default value to a valid value that is not the first in the option list. The dropdown will then default to that value when rendered. The default value must match the Option Key and not the user friendly name. |
ComputerNamePattern | This is a special purpose field and only applied to the computer name pattern.
The ## signs in the ComputerNamePattern are replaced by numbers by VMM at deployment time. |
VMSize | The VMSize field connects to the CloudVMRoleSizeProfile table from the VMM database and allows the user to select the hardware profile for the virtual machine instances.
|
OSVirtualHardDisk | This field displays the virtual hard disks in the VMM library in a dropdown list. It only displays the disks that have a family name, a version, an operating system value and matching tags.
All the tags specified in the OSVirtualHardDisk parameter in the View Definition must be present on the disk in VMM. |
DataVirtualHardDisk | The DataVirtualHardDisk parameter type displays the virtual hard disks in the VMM library in a dropdown list. It only displays the disks that have a family name, a version and where the operating system value is set to none.
|
Network | The network parameter type displays a dropdown list with the available networks in the subscription. These networks are retrieved from VMM and can be predefined VM networks based on VLANs or VM networks created by the tenant in Windows Azure Pack using network virtualization.
|
OSTimeZone | To set the time zone in the VM Role instances this parameter type presents a dropdown list with all available time zones.
If you want to set a default value you can run tzutil.exe /l to get a list of all possible values. You can also use these values to hard-code the time zone. |
Each parameter type had different options. Clicking the Details button directly below the parameter type will expand all related options. The following matrix displays the available options for each parameter type.
|
|
|
|
|
|
|
|
|
|
|
|
| |
Label* | x | x | x | x | x | x | x | x | x | x | x | x | x |
DefaultValue | x | x | x | x | x | x | x | x | x | x | x | x | x |
Description* | x | x | x | x | x | x | x | x | x | x | x | x | x |
Configurable | x | x | x | x | x | x | x | x | x | x | x | x | x |
Options | x | ||||||||||||
Add Image Tag | x | ||||||||||||
Image Tags | x | ||||||||||||
Required | x | x | x | x | x | x | x | x | x | x | x | x | x |
MinLength | x | x | x | x | x | ||||||||
MaxLength | x | x | x | x | x | ||||||||
MinRange | x | ||||||||||||
MaxRange | x | ||||||||||||
RegExp | x | x | x | x | x | ||||||||
RequiredMessage* | x | x | x | x | x | x | x | x | x | x | x | x | x |
LengthMessage | x | x | x | x | x | ||||||||
RegExpMessage | x | x | x | x | x | ||||||||
RangeMessage | x |
The options for the parameter types are explained in the following table. Some fields are required, these fields are marked with an asterisk in the table. The VM Role Authoring Tool will also display the required fields. Fields that are rendered in the gallery item deployment wizard can be configured for localization of the value. See the resources entry in this blog for more information on localization.
Label* | The label is displayed in the gallery item deployment wizard as the name of the field.
The label can be localized. |
DefaultValue | The DefaultValue is prepopulated in the value field.
The DefaultValue can be localized. Note: the default value for the parameter type Option and Boolean must be configured. If you do not configure the default value and the user does not click this field in the gallery item deployment wizard, the value that is displayed in the field is not captured. |
Description* | The description is displayed when a tenant hovers over the question mark directly next to the Label.
The Description can be localized. |
Configurable | This option defines if the value in the field can be configured by the tenant or is rendered as read only. This value can be set to Yes or No. The default value is Yes. If the value is set to No the field will be greyed out in the gallery item deployment wizard.
|
Options | The options table consists of two columns. The Option Key is captured as the value when selected. The Option Value is used to display a user friendly value in the dropdown list in the gallery item deployment wizard. The Option Value can also be localized. Note: set the default value to a matching value in the Option Key.
|
Image Tags | Image tags are used by the OSVirtualHardDisk parameter type to filter the virtual hard disks by matching the tags that are set on in this field to the tags that are configured on the virtual hard disks in VMM. All the tags specified must also be present on the disk in VMM. If the virtual hard disk has the tags “WindowsServer2012” and “R2” set in VMM and the OSVirtualHardDisk requires “WindowsServer2012”, “R2” and “Datacenter” the disk will not be displayed. If the virtual hard disk has the tags “WindowsServer2012” and “R2” set in VMM and the OSVirtualHardDisk requires only “WindowsServer2012”, the disk will be displayed. The VM Role Authoring Tool is preconfigured with a list of common tags. You can also define you own tags.
|
Required | The checkmark defines if a value is required. If this checkmark is enabled and the user does not submit a value for this field, the RequiredMessage is displayed and the tenant is unable to submit the gallery item deployment wizard. |
MinLength | This field defines the minimum length of a string. If the tenant enters a value that contains less characters than the minimum length, the LengthMessage is displayed and the tenant is unable to submit the gallery item deployment wizard. |
MaxLength | This field defines the maximum length of a string. If the tenant enters a value that contains more characters than the maximum length, the LengthMessage is displayed and the tenant is unable to submit the gallery item deployment wizard. |
MinRange | This field defines the lowest allowed number in a range. If the tenant enters a value that is lower than the value specified here, the RangeMessage is displayed and the tenant is unable to submit the gallery item deployment wizard. |
MaxRange | This field defines the highest allowed number in a range. If the tenant enters a value that is higher than the value specified here, the RangeMessage is displayed and the tenant is unable to submit the gallery item deployment wizard. |
RegExp | Allows you to configure a regular expression. The value submitted by the tenant in the gallery item deployment wizard must comply with the regular expression. If the value does not comply the RegExpMessage is dsiplayed. For instance when the user needs to submit an IP Address, you can specify the regular expression \b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b More information on regular expressions can be found in the Regular Expression Language - Quick Reference |
RequiredMessage* | This message is displayed if the required checkmark is enabled and the user does not submit a value for the parameter.
The RequiredMessage can be localized. |
LengthMessage | The LengthMessage is displayed when the tenant enters a value that contains less characters than the minimum length or more characters than the maximum length.
The LengthMessage can be localized. |
RegExpMessage | The ReExpMessage is displayed when the tenant enters a value that not complies with the RexExp.
The RegExpMessage can be localized. |
RangeMessage | The RangeMessage is displayed when the tenant enters a value hat is lower than the MinRange value or higher than the MaxRange value.
The RangeMessagemessage can be localized. |
When multiple messages apply these messages are displayed in one message box.
Resources
In the View Definition all the values that displayed in the gallery item deployment wizard can be localized. Localizing enables the gallery item deployment wizard to render the values in the language that the client browser is configured in. Since you can define your own custom fields, you are required to translate the values for the targeted language. You can consider the resources entry as language tables that map a variable to a localized value.
The VM Role Authoring Tool displays a field that can be localized with a dropdown button and a Loc? (Localize) checkmark.
You can hard-code the value. In the gallery item deployment wizard this field is always rendered with the hard-coded value, ignoring the language settings of browser that the tenant is using. A more dynamic approach is to create a localized property. A localized property starts with two curly brackets, the variable name and two curly brackets. For instance {{VMRoleVMSizeLabel}}. The VM Role Authoring Tool provides a dropdown button to generate a localized property.
You can also type the localized property yourself, as long as it meets the format requirements and you have not used the localized property before (unless you want to re-use the value on multiple locations in the View Definition). When a localized property is created it is added to the mapping table for each language resource that is added to the resources entry. When you create a new Resource Definition package in the VM Role Authoring Tool the View Definition is prepopulated with the language resource en-US. You can add additional languages by selecting the Resources entry in the navigation pane and adding the language from the dropdown field.
en-US
The mapping table in each language resource contains two columns. The Parameter Name column contains the parameters that are configured as localized property in the View Definition. The Localized Parameter Value column holds the translated value. You can type your own values in this column.
What's next?
In this blog post we discussed the Resource Definition Package. In the next part we will dive into the Resource Extension Package.