Journey to a Windows Azure Pack VM Role DSC Resource: Introduction

In this series,

Part 1 – Journey to a Windows Azure Pack VM Role DSC Resource: Introduction (this article)

Part 2 – Journey to a Windows Azure Pack VM Role DSC Resource: PowerShell module usage

Part 3 - Journey to a Windows Azure Pack VM Role DSC Resource: Inside the module

Part 4 - Journey to a Windows Azure Pack VM Role DSC Resource: The DSC resource

In this series, I’ll take you on a journey of developing a DSC resource to deploy Windows Azure Pack VM Roles. There is already the xAzurePack DSC resource module created by Microsoft. It deals with deployment and configuration of Windows Azure pack itself and not with tenant operations like deploying VM Roles.

Why should you want to do this with a DSC resource? Well, the DSC resource actually is a side effect of a PowerShell module I’ve created to make it easier and a whole lot faster to mass deploy VM Roles without clicking through the tenant portal UI. Once you have a good PowerShell module, why not take the extra mile and lay a DSC resource on top to enable VM Role as Code deployments!

I’ve created this DSC resource as an experiment. Other resources which would be obvious for this resource module are “missing” because I’ve only focused on VM Roles. In other words, you will have to go in as the tenant and setup your VM Network manually if the Azure Pack Admin did not provide one for you already.

If you want this “experiment” to be developed more, please visit the PowerShell module repository on GitHub here and the DSC resource module here. You can log issues or contribute by forking and creating a pull request (if you want to learn how to do that, please look at an excellent set of articles by Ravikanth Chaganti starting here). This way I know if there is any interest to promote these modules from experiment to a more generic asset.

If you want to get started deploying VM Roles to Windows Azure Pack right away and you use WMF 5.0 you can get both–the PowerShell module and the DSC module–via the PowerShell Gallery.

1
2

Install-Module -Name WAPTenantPublicAPI
Install-Module -Name CWAPack

If you are on an older version, go to the GitHub repositories and download them as ZIP files. And then, unblock the ZIP archives and extract the files to your module directory of choice.

Why not base it on Azure PowerShell module?

The reason why I base the DSC resource on my own PowerShell module is because I wanted to enable the scenario of authentication with bearer (JWT) tokens instead of certificates or publish settings files. Bearer tokens are used by the Windows Azure Pack portals and are generated by either the Windows Azure Pack Authentication website or ADFS. By default, the tenant public API (the API exposed to the internet/public) does not accept bearer tokens, only certificates. This behavior can however be modified. The tenant API does accept bearer tokens by default. Bearer tokens are more easy to work with (especially in the Enterprise scenario) then certificates/publish settings files as they are acquired on the spot. No need to make sure the certificates are in the store, etc.

Another reason is that the Azure PowerShell module, although suitable to work with Windows Azure Pack, does not have a way to interrogate the view and resource definition of a VM Role Gallery Item. The lack of this functionality makes it difficult for the tenant user to generate the correct JSON needed by the New-WAPackVMRole cmdlet.

Let’s have a look on how things would be done via the tenant portal first and then look at using the Azure module so we have a good grasp of what we are trying to do.

The Tenant Portal Experience

After you logon either through the Authentication Site or via ADFS, you deploy a VM Role via the NEW menu on the bottom of the Tenant Portal and select “Virtual Machine Role” -> “From Gallery”.

You will be presented with a gallery list of VM Roles that have been made available to the subscriptions you are a member of. You select one and press the next button.

When clicking through the UI View Definition of the VM Role, the JSON needed to deploy the VM Role is constructed by the web application. Once the “wizard” is finished and you click deploy, a cloud service is created with the same name as the one you gave to the VM Role (Azure Pack Tenant Portal has a 1:1 relation between a cloud service and a cloud resource, aka VM Role). Then the VM Role is deployed to it. But who wants to click right?

The Azure Module Experience

As I’ve already stated, to use the Azure PowerShell module with Windows Azure Pack you first need to get your publish settings file. First go to the Windows Azure Pack tenant portal address but append “/publishsettings” to the URL.

After login, you will be presented with this site:

The publish settings file will be automatically downloaded (if it is not, hit the here link).

Let’s take a look at the content of this file so we know what we are actually working with.

As you can see, the file is actually an XML file. The XML holds the subscription data I have access to including Azure Pack generated management certificates.

When looking at the certificate data, you see that it holds both a public and a private key and it’s valid for one year (the certificate is generated on the spot when you download the publish settings file).

When looking in the tenant portal you can see the certificates have been added there as well.

You can see that for every subscription you have access to, a certificate will be generated so you need to download a new publish settings file every time you enroll into a new subscription.

Now we have the file, we can start using the Azure module (make sure you have installed the Azure module first).

First we import the publish settings file to import the certificates into the User Cert store and make the subscriptions data available to us. Then we select the subscription we want to work with (in my case, I have 2 subscriptions and I want to work with “test”). If you like, you could use the commands aliases: Import-WAPackPublishSettingsFile, Get-WAPackSubscription, etc.

Now everything is into place to start deploying a VM Role. Let’s look what native WAPack cmdlets we have available to figure out how to do this.

The cmdlet we are after is New-WAPackVMRole. If we look at the help example you know this is going to be difficult. The help does not specify how to create the content of the $resdef variable for good reason. The Azure module has nothing native to generate the correct JSON data.

Luckily we can generate the JSON data ourselves. We interrogate the API for the gallery items. A gallery item provides us with the links to acquire the needed data from the resource definition and view definition (you can learn all about the inner workings of VM Roles by going to Marc van Eijk’s excellent blog posts here). From this definition data we construct the JSON needed for the $resdef variable.

Since we need to create a bunch of new functions, plus the dependency on the Azure module and the publish settings file, you start to notice this is not really a friendly approach.

In the next article, we’ll look at working with my PowerShell module which would give us everything we need in one place.