Get Started with Virtual Machine Roles: Walkthrough Guide

Applies To: System Center 2012 R2

Virtual Machine Roles enable a hosting provider to make offerings available to their tenants by using a standard and reusable artifact that can be used in both, in on-premises hosting environments and in Windows Azure. They can be authored in a standard format that can be easily copied and modified to suit different hosting scenarios.

This step-by-step walkthrough shows you how to inspect the contents of a sample Virtual Machine Role, install it in a Microsoft System Center 2012 R2 environment, and then use it to provision a new virtual machine.

This document assumes that you have a basic understanding of System Center 2012 R2 that includes how to use the Service Admin Portal and Tenant Portal. After you complete this walkthrough, you understand the contents of a Virtual Machine Role and how to install a Virtual Machine Role in a System Center 2012 R2 environment.

You'll learn:

• How to unpack the Resource Definition and Resource Extension packages that make up a Virtual Machine Role.

• How to interpret the contents of the Virtual Machine Role packages.

• How to prepare a virtual hard disk (VHD) to be used with a Virtual Machine Role.

• How to install a Virtual Machine Role and make it available to tenants.

• How to provision a new virtual machine from a Virtual Machine Role.

Time requirements

The procedures in this document require approximately 90 minutes for a new user to complete. This estimate assumes that the testing environment is already configured.

Walkthrough steps

• Prerequisites

• Step 1: Extract and inspect the Virtual Machine Role packages

• Step 2: Install the Resource Extension

• Step 3: Prepare the virtual hard disk

• Step 4: Install the Resource Definition

• Step 5: Add gallery item to a plan

• Step 6: Create a Virtual Machine Role by using Tenant Portal

• Step 7: Change the settings for the Virtual Machine Role

• Step 8: Scale out the Virtual Machine Role

• Step 9: Update the Virtual Machine Role

Prerequisites

The only prerequisite for this walkthrough is to have an operational version of System Center 2012 R2.

Step 1: Extract and inspect the Virtual Machine Role packages

You can obtain the sample Virtual Machine Packages that support this walkthrough the following location: https://download.microsoft.com/download/0/9/C/09C183EB-053F-40BF-AF8D-4E59A4EE0CA4/WS2012WebServer-VMRole-Pkg.zip.

To start, extract the packages that make up the Virtual Machine Role and then inspect their contents. The files in the packages are written in JavaScript Object Notation (JSON) which provides 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 less verbose. Hosting providers can either obtain Virtual Machine Roles from external parties or create their own to provide customized offerings to their tenants.

To extract the Virtual Machine Role packages

1. Open the Gallery Items folder.

2. Create a new subfolder with the name Gallery Items Unpacked.

3. Copy the files WS2012IISResExtV1.resextpkg and WS12IISV1.resdefpkg into the Gallery Items Unpacked folder.

4. Create two subfolders in the Gallery Items Unpacked folder and name them Resdef and Resext.

5. Change the file name extension for each package to .zip.

6. Extract the contents of WS12IISV1.resdefpkg.zip into the Resdef folder and the contents of WS2012IISResExtV1.resextpkg.zip into the Resext folder.

To inspect the contents of the Resource Extension

1. Open the Resextpkg folder.

2. Open WS2012IISResExt.resext in Notepad and explore its contents. This file is formatted in JSON and contains the definition of the application to install.

3. Note the different sections that include the following:

   • Name, Publisher, and Version that identify the particular Resource Extension.

   • Resource Extension Parameters that define parameters that are provided by the tenant when they provision a new Virtual Machine Role.

   • Resource Requirements that define the requirements of the virtual hard disks (VHDs) to be used with the Virtual Machine Role.

   • Application Profile that defines the required steps to install the application and the operating system resources that must be enabled to support it.

4. Explore the rest of the contents of the folder that includes the application payload in the IISWS2012 folder. This payload contains the required files for the installation of the application. In this case, it is a file with a single command that contains the script to perform the configuration.

To inspect the contents of the Resource Definition

1. Open the Resdefpkg folder.

2. Open WS2012IISResDef.resdef in Notepad and explore its contents. This file describes the virtual machine container that hosts the application as defined in the Resource Extension section.

3. Note the different sections that include the following:

   • Name, Publisher, Version, and Type that identify the particular Resource Definition.

   • Resource Parameters that define parameters that are provided by the tenant when they provision a new Virtual Machine Role.

   • Resource Extension References that define the Resource Extensions that can be used with this Resource Definition and the parameter values that they require.

   • Intrinsic Settings that specify the detailed configuration settings for the virtual machine.

To inspect the contents of the View Definition

1. Open the Resdefpkg folder.

2. Open WS2012IISViewdef.viewdef in Notepad and explore its contents. This file describes the user interface to present to the tenant to collect values for the parameters in the Resource Definition.

3. Note the different sections that include the following:

   • Label, Publisher, and Description that identify the particular Resource Definition.

   • Sections that define the different dialog boxes in the user interface.

   • Categories that provide a logical grouping for settings.

   • Parameters that define the different values to be collected from the tenant.

Now that you have inspected the contents of the packages, install them in the Gallery and make them available to tenants.

Step 2: Install the Resource Extension

The Resource Extension package is installed in Virtual Machine Manager (VMM). There is currently no user interface to support this process, and it is performed with Windows PowerShell commands.

To import the Resource Extension into Virtual Machine Manager

1. Run the VMM command shell as an administrator.

2. Run the following Windows PowerShell commands:

   1. Set-executionpolicy remotesigned
      

      When prompted about Execution Policy Change, select Y.

   2. $libraryShare = Get-SCLibraryShare | Where-Object {$_.Name -eq 'MSSCVMMLibrary'}
      

      Modify the path according to the folder that you created.

   3. Import-CloudResourceExtension -ResourceExtensionPath $respkgPath -Description "IIS resext" -SharePath $libraryShare
      

3. You should receive various messages that report that the gallery item is imported.

4. Verify that the gallery item has been imported by running the following Windows PowerShell command:

   Get-CloudResourceExtension
   

With the Resource Extension installed, you next prepare the virtual hard disk (VHD) that is to be used with the Virtual Machine Role.

Step 3: Prepare the virtual hard disk

The Resource Extension specifies tags that it requires to identify a VHD as valid for it to use. In this step, you add the required tags to a VHD so that it can be used with the Virtual Machine Role. You also need to set the product key on the VHD.

If you use a volume license key, then you should have a KMS server on the same network as the virtual machine so that it can be automatically activated.

To add tags to the virtual hard disk

1. Look again at the View Definition file and find the parameter with the name VMRoleOSVHDImageNameVersion.

2. Note that the parameter includes two tags which are both required on the VHD for it to be used with the Virtual Machine Role. The tags in this case are WindowsServer2012 and Datacenter.

3. Run the following Windows PowerShell commands to add the tags to the VHD:

   $vhd = Get-SCVirtualHardDisk | where {$_.Name –eq 'WINDOWS SERVER 2012 DATACENTER.vhd'}
   $tags = $vhd.tag
   if ( $tags -cnotcontains "WindowsServer2012" ) { $tags += @("WindowsServer2012") }
   if ( $tags -cnotcontains "Datacenter" ) { $tags += @("Datacenter") }
   Set-SCVirtualHardDisk –VirtualHardDisk $vhd –Tag $tags
   

4. Verify that the tags were set correctly by running the following command:

   $vhd.Tag
   

   The output should include the two tags WindowsServer2012 and Datacenter.

To set the product key for the virtual hard disk

1. Obtain your Windows Server 2012 product key.

2. Run the following Windows PowerShell commands to set the product key on the VHD replacing the text assigned to the $productKey variable with the actual product key:

   $productKey = 'xxxxx-xxxxx-xxxxx-xxxxx'
   Set-SCVirtualHardDisk –VirtualHardDisk $vhd –ProductKey $productKey
   

With the Resource Extension installed and the virtual hard disk prepared, you can now install the Resource Definition.

Step 4: Install the Resource Definition

The Resource Definition is imported by using the Service Admin Portal. Install two versions of the same definition so that you can test the update procedure in a later procedure.

To import the Resource Definition

1. Open the Service Admin Portal.

2. Navigate to the VM Clouds workspace.

3. Click the Gallery tab.

4. Click Import.

5. Select and import the WS12IISV1.resdefpkg file in the Gallery Items folder.

6. Note that the gallery item now is listed on the Gallery tab.

7. Select and import the WS12IISV2.resdefpkg file in the Gallery Items folder.

8. Note that the gallery item now is listed on the Gallery tab.

Now that the packages for the Virtual Machine Role have been installed, you can publish the gallery item to make it available to tenants.

Step 5: Add gallery item to a plan

To make the Virtual Machine Role available to the tenant, you need to add it to a plan. In this procedure, you publish the Virtual Machine Role that you installed. Only the original version is available in this step. You make the update available in a later procedure.

To publish the gallery item

1. On the Gallery tab, select the 1.0.0.0 version of the WS2012 with IIS Role gallery item that you just imported.

2. Click the arrow next to the gallery item name.

3. Explore the details of the gallery item.

4. Navigate back and click Make Public.

5. Select the Plans workspace in the Service Admin Portal.

6. Select the plan that you created in the previous exercise.

7. Select the Virtual Machine Clouds service.

8. Scroll to the Gallery section.

9. Click Add Gallery Items.

10. Select both of the gallery items that you imported, and then click Save.

The Virtual Machine Role is now available to the tenant as part of the Airlift plan.

Step 6: Create a Virtual Machine Role by using Tenant Portal

You now take the role as a tenant and provision a new virtual machine that is based on the Virtual Machine Role that you just installed. You then inspect the details of the instance that you created.

To create a virtual machine based on a Virtual Machine Role

1. Log on with a tenant user account.

2. Open the Tenant Portal.

3. Select the Gallery workspace.

4. Select New, and then select Virtual Machine Role.

5. Select version 1.0.0.0 of the gallery item that you added in the previous procedure.

6. Type a name for your Virtual Machine Role such as IISRole. The name cannot contain spaces, or the creation fails.

7. Follow the wizard to provide values for each of the settings by using the following guidelines:

   1. Keep the default Instance Count of 1.

   2. Select a VM Size of Extra Small.

   3. Note that the only VHD that you can select is the one that you tagged in the previous procedure.

8. After several minutes, the Virtual Machine Role appears in a provisioning state. The primary reason for the delay is waiting for the VHD to be copied.

To view the dashboard for the Virtual Machine Role

1. After provisioning is completed, click the arrow next to the Virtual Machine Role that you created in the previous procedure.

2. Click the Dashboard tab.

3. Note how the Virtual Machine Role uses a portion of your quota by looking at the green bars and reading details for CPU, memory, storage, and number of virtual machines.

To view the details of the VM instance in a Virtual Machine Role

1. Click the Instances tab of the Virtual Machine Role.

2. Click the arrow next to the virtual machine name.

3. On the Dashboard page, note the usage graph, quota, devices, and details about the virtual machine on the right side.

4. Click Connect, and then select Desktop to connect to the desktop by opening the .rdp file that is downloaded to your client.

5. Click Stop to stop the virtual machine.

6. Click the Configure tab.

7. Note that you can change the virtual machine size when the virtual machine is stopped.

8. Note that you can attach and detach devices when the virtual machine is stopped.

9. You can also expand a disk if it is using the VHDX format.

10. Select the Dashboard tab and start the virtual machine again.

You now have an instance of the Virtual Machine Role and have viewed its details. In the next steps, you make changes to the instance of the Virtual Machine Role.

Step 7: Change the settings for the Virtual Machine Role

In this procedure, you change the settings for the Virtual Machine Role instance that you just created.

To update settings for the Virtual Machine Role

1. Click the Configure tab of the Virtual Machine Role.

2. Note that you can review the settings that you previously provided.

3. Note the settings that can be updated such as the setting for VM Size.

4. Change the VM Size to Small.

Step 8: Scale out the Virtual Machine Role

In this procedure, you increase the instance count of the Virtual Machine Role.

To scale out the Virtual Machine Role

1. Select the Scale tab of the Virtual Machine Role.

2. Increase the instance count from 1 to 2 and save your change.

   Note

   Ignore any error messages about failed operation and refresh the portal. You should see an instance count of 2.

3. Note that the new virtual machine instance uses the new VM Size setting that you selected in the previous step.

Step 9: Update the Virtual Machine Role

In this procedure, you offer the updated version of the Virtual Machine Role to the tenant and then act as the tenant to update the instance that you provisioned.

To change the version of a Virtual Machine Role

1. In the Service Admin Portal, select version 1.1.0.0 of the gallery item that you installed in the previous procedure.

2. Click Make Public.

3. Open the Tenant Admin Portal.

4. Locate and select the Virtual Machine Role that you created.

5. Select the Dashboard tab.

6. Note that there is a message at the top of the screen that notifies you of the new version.

7. Click Make Public to change the version of the Virtual Machine Role. Note that you must complete the wizard again in case you must make changes to the Resource Definition.