Virtual Machine Role Example Kit
This post is part of a series for the Building Clouds Blog Gallery Items for Collaboration Workloads. For more information see the following Table of Contents post - https://aka.ms/bcbgicw.
Overview
This project is meant as a resource for someone interested in building their own VMRole Gallery Item based on the Building Clouds Blog Gallery Items for Collaboration Workloads. The Resource Definition and Resource Extension packages have been generalized by removing all application specific information to create a quick-start template that can reduce the time to build something new.
Download the Virtual Machine Role Example Kit
Notes
This download serves as a reference that can be used as a template when starting a new project. It is not intended to be imported and deployed as-is, since nothing would actually be installed other than the operating system with a data disk.
It is also recommended that if this set of resources is duplicated, it is performed in a copy/paste method via the authoring tool UI so that new unique identifiers are created.
All lessons-learned and best practices developed during the process of creating the BCB Gallery Items for Collaboration Workloads are incorporated and shared through this Example Kit. This blog post is meant to build on current documentation to describe anything unique about that work. For a more general understanding of Virtual Machine Roles, see the articles below.
System Center 2012 R2 Virtual Machine Role Authoring Guide
https://social.technet.microsoft.com/wiki/contents/articles/18272.system-center-2012-r2-virtual-machine-role-authoring-guide.aspx
For most of this post we will be explaining the Example Kit in the context of viewing it through the Authoring Tool with the assumption that the reader has the files open and is able to view settings.
VM Role Authoring Tool
https://vmroleauthor.codeplex.com/VM Role Authoring Tool How To Videos
https://www.youtube.com/playlist?list=PLjbVGPEELuaSuM-0eh9GO05zDFUudydJ1
Best Practices
This document will describe unique items configured in both the resource extension and resource definition.
Resource Extension Package
A few practices were developed here. I would not say they are hard and fast rules but they work well.
- Use of .cmd files
- Folder structure within payload
- Organized logging across scripts
The first is to encapsulate the commands that will be run in a .cmd file and load that as app payload. This allowed for minor tweaks to the command without needing to edit the ResExt file. It also would make it easy to trap error codes and introduce some recovery actions or redirect output. Notice that both parameters are based in the ScriptApplication. The ApplicationSetting is just intended to demonstrate that with a ResExt you can accept a parameter directly in to a ScriptBlock and how it would be accepted by a command file and passed to an executable.
The second was creation of a folder structure for the app payload. It worked well to put the application install in a folder, the prerequisite installer files in a folder, and then the base scripts that will do work in the root.
The third was using a common logging folder across all scripts. Whenever possible I would separate app installs and log them independently.
Note – the scripts are combined payload. The was just for simplicity in organizing work.
Actual Script Content
DataDisk.cmd – executes PowerShell script with execution policy set to RemoteSigned in the scope of the process.
C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -Command "if ((Get-ExecutionPolicy) -eq 'Restricted'){Set-ExecutionPolicy RemoteSigned -Scope Process -Force };.\DataDiskScript.ps1"
DataDiskScript.ps1 – brings the data disk online and sets it to not read-only. Sleeps for 15 seconds just to make sure the disk has adequate time.
| 001 002 003 004 | # Disk Management get-disk | ? OperationalStatus -eq 'Offline' | set-disk -IsOffline 0 get-disk | ? IsReadOnly -eq $true | set-disk -IsReadOnly 0 start-sleep -seconds 15 |
Prereq_install.cmd – launch mock installer files for prerequisites.
.\prereqs\Setup.exe /quiet /noreboot
Application_install.cmd – launch mock installer files for application.
.\InstallFiles\Setup.exe /param %1
Resource Definition Package
The ViewDefinition section in the Example Kit is organized in to two sections which act as pages in the wizard.
- Local Machine Settings – collect any values that apply to things going on LOCALLY within the VM. This made it simple to ensure the tenant understands that the administrative credentials are for the local administrator account and not for joining the domain or installing apps.
- Run As Settings –
- Domain Category - this section collects any information having to do with work that will require network access. In all cases, which domain to join and what credentials to use are collected but it is noted in the description that the same credentials will also be used for the application installation.
- Application Category - This also contains any parameters unique to the application being installed. This could be customized to collect much more information such as another set of credentials, additional parameters via input boxes or drop-down lists, or removed completely if no application parameters are required.
Each section title is named according to the above bullet points which makes the intention clear for each page. The category name becomes important because it provides additional context.
Default values are populated wherever possible to minimize required input. Note that default values may not be the same as the text displayed. As an example, VM Size is based on the profiles in VMM. You can view these by running the following command.
| 001 | get-cloudvmrolesizeprofile |
Building a New VMRole
You could absolutely take the Example Kit and use it to construct a VMRole of your own. In fact that is the intention. These steps should get you started.
Start by opening the resource extension in the authoring tool, then the resource definition. You can perform edits with both open. After you have made changes in the resource extension, open Extension References under resource definition to make sure values and parameter names are in sync.
Cosmetic
Go through the resource extension first and update the names to describe your intended role. If you decide to rename parameters such as param.ApplicationSetting, make sure you also update the fields where they are used. This is easy to find, click on the Validate button on the ribbon and it will alert you to orphaned values.
After names are set, most of the cosmetic changes would occur in the Resource Definition section. You can add your own icons by clicking on the ViewDefinition section header. You will need the same icon sized to 120, 60, and 30 pixels. I usually just do this in Paint. 
You will see in the Sections/Categories that most of the values are “localized” meaning the values are parameters and everything flows back to the Resources part of the UI. This is so that if you need to handle multiple languages, your customizations can be set for each. If you want to change the actual text labels in the Example Kit, click on en-US and review the text for each.
Functional
When making functional changes I would take this approach.
Start with OS changes.
- In the resource extension under Resource Requirements set your tags so you load the correct OS.
- Also in the RE under Application Profile open Roles & Features and select your OS, then which items you require to bring online. This is accomplished using Sysprep.
- In the resource definition open Operating System Profile and decide whether you need to make any changes such as not joining a domain.
Setup your data disk requirements.
- In the Example Kit one data disk is mapped. You will find this under the resource definition in Storage Profile. If you do not require a data disk you can remove this entry or change the name to point to the FamilyName and Version of another disk you have stored in the VMM library.
Configure your application.
- In the resource extension under Application Profile, add additional scripts to install more than one prerequisite by clicking on Application Profile and then Add on the ribbon and selecting Provisioning Script. You should be able to most copy and paste settings from the first except your deployment order, log names, and scriptblock will be different. If necessary, don’t forget to select your application payload and add it.
- You can also just make changes to the .cmd files if your prereqs and application install allow it.
- Finally, you might consider post-install scripts to complete tasks such as configuring firewall ports if that meets your organizational standards and policies for security.
Scale
- If your application needs to start with multiple instances or can be scaled out, click on Scale Out under the RD and set the min/max number of VM’s.
Summary
The Virtual Machine Role Example kit offers a simple way to get started building your own VMRole Gallery Item. I look forward to your comments. Please feel free to visit our forum to discuss your own work and lessons learned for building new gallery items.
https://aka.ms/BuildingCloudsForum
Stay tune to Building Clouds!
Comments
- Anonymous
December 20, 2013
Pingback from Windows Azure Pack Blog Post Overview on Building Clouds & TechNet - Building Clouds Blog - Site Home - TechNet Blogs - Anonymous
January 06, 2014
Pingback from Windows Azure Pack Blog Post Overview on Building Clouds & TechNet - Anonymous
January 21, 2014
Hi, is it possible to create 3 VMs as a set in one vm role ? Thank you and Regards - Anonymous
January 21, 2014
No, the closest would be to have the tenant kick off a script that provisions 3 vm roles.