If you’ve started to use or evaluate the Windows Azure Pack (WAP), you may have noticed the different steps required to install a VM Role Gallery Item and to configure your environement to leverage this new artifact. These include:

1. Downloading the Gallery Resource from Web Platform Installer, or from the source blog.
2. Checking the virtual disks requirements (OS disk, and data disk if any) in the Gallery Item documentation, and configure disks accordingly in your environment (family, release, operating system, tags). Most of this can be done in the VMM, the tags require PowerShell.
3. Importing the Resource Extension in VMM, via PowerShell – possibly after editing the Resource Extension to add specific files/payloads (here also the information is in the Gallery Item documentation)
4. Importing the Resource Definition in the WAP administration portal

These steps are detailed here, and rely on specific information you can find in the documentation for each VM Role Role Gallery Item you wish to configure and import.

More specifically, the Resource Extension step can be seen starting at 16:36 of the VM Role Resource Extension video, and the Resource Definition step can be seen starting at 16:07 in the VM Role Resource Definition video. Both videos are part of the series published by Stephen Baron from the Virtual Machine Manager team.

To simplify, automate and assist with this process, we are happy to release today the “Gallery Resource Import Tool” (GRIT).

This post explains the goals and capabilities of the tool, as well as how to use it.

Note : Before reading further, I would recommend reading a bit about what makes up a VM Role Gallery Item, and mainly the notion of “Resource Extension” and “Resource Definition”. Michael Greene has written an excellent post on this topic, and it is available here.

How to use the tool

1. First download the tool from the link earlier in this blog post. The package contains a readme document – essentially redirecting you to this blog post - and the tool itself (a PS1 file)

2. Edit the $VMMServer and $SPFServer variables at the top of the PS1 file, to match your environment, or enter these variables on the command line when starting the tool

3. Please make sure that

• You are currently running this tool on a machine with VMM and SPF cmdlets. An easy location is the server running Service Provier Foundation (SPF).
• You are also running the tool from an elevated PowerShell/ISE invite, or some of the cmdlets might fail to import the packages

4. In the window that opens, select the Gallery Resource you want to configure and/or import. If network connectivity is available, you should see all Gallery Resources from Web Platform Installer (WebPI). If not, you should only see the option to browse and select a Resource Definition file on the local machine

5. The tool should then parse the chosen Gallery Resource, and open a new window with a welcome screen, similar to the ones you are reading right now.

6. In the "1.Virtual Disks Configuration" tab : Review the discovered requirements for the virtual disks, and pick the operating system you would like to use (it has to be one of the operating systems from the gallery item documentation). In the grid that opens, review virtual disks compatibility, and update disks as needed, until you get at least one “OS disk Match” and one “Data Disk Match”. While you can choose to import the resource extension/definition before configuring the disks, just remember the gallery item wizard and deployment may not work until valid disks are available.

Picking the Operating System for the OS disk

After picking an OS disk, this list comes up and displays the compatibility with your existing virtual hard disks. You can select the disks and apply OS/data disk settings to the selected disks.

7. In the "2.Gallery Resource Import" tab : You can choose to import the resource extension and/or import the resource definition. To import the resource extension, you must first select a VMM library share. The tool may also warn you if it detects potential missing payloads in the package to be imported, in which case we recommend you double check the Gallery Resource documentation, and only proceed if you are sure the extension is ready (Note : Don't worry, you can always remove the resource extension if you need to start over again). The tool also checks if the Resource Extension and Resource Definition are already imported and does not try to import them again if that’s the case.

Note : When updating disks/importing files, the tool will display progress in the PowerShell console (while the tool’s window will be waiting for the end of the job to display status).

In this example, a disk was tagged as a data disk, and both the Resource Extension and Resource Definition were imported.

You will also get a popup at the end of each major operations (disk tagging, or Resource Extension/Definition import):

Once you have imported the Resource Extension and Resurce Definition, you just have to go to the Windows Azure Pack (WAP) admin portal, set the gallery item to “public” and add it to a plan to test.

Tip : If you select a row and right click on it, the OS disk family and release fields will be populated with the currently highlighted values. You can use that tip to easily copy some values before assigning new tags, etc. This is essentially the same thing as writing the Family and Release fields manually, but just faster…

Detailed capabilities

This section covers in more details what happens under the hood when you run the tool, and you can see the corresponding script in the PS1 file.

The tool does the following:

1. Lets you select a Resource Definition from the local disk, or download one from the Services Model feed from Web Platform Installer (WebPI).

a. The Resource Definition file path can also be specified as a parameter. The VMM and SPF server are also script parameters.

b. If no internet connectivity is detected, only local Resource Definition files are presented

2. Copies/downloads the packages, unzip them in a temporary directory and parses JSON files to discover virtual disks requirements, if any (where the model allows).

a. By default, packages are downloaded to a “C:\GRIT_Downloads” folder, that will be created by the tool. You can change this default value in the tool variables in the PS1 script, by updating the $DownloadFolder varialble.

b. Specific situations are also handled, like a Resource Definition file not relying on a Resource Extension file, or multiple Resource Definition files in a WebPI package (such as a “domain” and a “workgroup” Resource Definition, both leveraging the same Resource Extension).

3. Displays the computed requirements for virtual hard disks, and gives the option for the user to specify the OS disk operating system (this is the only thing remaining that you would still have to check in the documentation, as this is not part of the current VM Role model)

4. Based on these requirements, existing virtual hard disks are listed, explaining which ones are matches for OS disks and Data Disks (if any)

a. All different cases are handled : OS disk parameterized or specified through family:release ; Data disk parameterized, specified through family:release, or not required

5. As a user, you can then choose to apply required settings for OS or data disks, and see if they become “matches”

a. Items like “OS Disk Operating System” are read directly from VMM, both for convenience and to minimize errors

b. When applicable, items are grayed out to limit user errors (for example, data disks must have “None” as the Operating System)

6. In the same user interface, you can choose to import the Resource Extension and/or the Resource Definition

a. The tool does some checks in the Resource Extension, to warn you when it detects the need for manual configuration before import (external payload declared in JSON, folders with a single readme file). A warning is displayed in that case, and the option to import the Resource Extension is unchecked by default. You can choose to bypass this and import the Resource Extension, once you’re sure you’ve made the corresponding changes, if needed. You can also choose to disable this check, by setting the $CheckResExtContent variable to $false in the PS1 file (by default, the variable exists and it set to $true)

b. Since Resource Extensions are imported as VMM custom resources in a specific library share, VMM library shares are automatically detected and listed

7. When finished, the tool cleans up temporary files (zip and copies)

Summary and Wrap-up

We hope you will find this tool useful, and really encourage you to send feedback !

A special thanks to MVP Kaido Järvemets. His blog post on color coding a datagrid inspired the look and feel of the disk configuration grid in this tool.

Thanks again for reading our blog.