...building hybrid clouds that can support any device from anywhere
Hello once again!
So, here we are, Part 2 of The New World of Tenant Provisioning with Windows Azure Pack blog series (find Part 1: Intro & TOC here). Finally, some PowerShell/SMA Runbook examples!
What does that mean, exactly?
Well for the context of this blog series, it means I am going to provide the PowerShell/SMA Runbook scripts necessary to create a Tenant Virtual Network (Isolated Software Defined Network (SDN)) & Active Directory VM Role. So, for organization’s sake, this blog post will be split into two main sections – one for automated Tenant Virtual Network deployment, and one for automated VM Role deployment.
For the most part, the PowerShell/SMA Runbook example for this already exists. Granted, you would have to be a Building Clouds Blog super-fan to know exactly where it is, but it does exist on this very blog. That said, for this series, we want to promote it much more, and underline the significance of it in this example solution.
So where did this example live before being reestablished here?
In this blog post: Automation–PowerShell Workflow Script Spotlight–Deploying Virtual Machine Manager Service Templates “OnBehalfOf” Tenant Administrator User Roles
An admittedly, under-promoted yet valuable blog post on the automation of various VMM resources via PowerShell workflow, from the Service Administrator “OnBehalfOf” the Tenant Administrator.
In fact, I believe now is a great time to take a moment and describe the “Scope of Management” for these two personas in an image:
The reason I believe this is important, is that I will be referring to each persona as this blog series continues. Now, this is not a comprehensive list of all the potential areas each persona has management over, but it covers what we need here.
Note There may be other uses or ways to access the WAP Tenant API (non-Public) than just as a Service Administrator. From what I have seen, it requires bearer token authorization. And since the best way to get this token is via the WAP Admin PowerShell Cmdlet (Get-MgmtSvcToken), I made some assumptions.
Okay, let’s knock this Tenant Virtual Network stuff out…
The following PowerShell workflow script (Create-VMNetwork) will create a VMM VM Network with the following settings (leveraging VMM PowerShell Commands):
Note You may keep these example settings, or modify to fit your deployment specifications.
Note In general, the Create-VMNetwork workflow gets called once per Tenant Admin (Owner User Role, which is the equivalent of User + Plan Subscription). In fact, this workflow is most often called as part of the SMA Runbook linked to the Subscription.Create event within WAP/SPF, meaning that as soon as a Tenant Admin User Subscribes to the related Plan, the Tenant Virtual Network is created automatically for that Subscription. For more information (and a specific example) about how WAP leverages SPF events to initiate SMA Runbooks, see the following TechNet Article: Using automation with Virtual Machine Clouds and blog post: Automation–Monitoring and Notifying in Windows Azure Pack with SMA
For instance, what if you wanted to configure NAT with a specific Gateway Device and External IP Address Pool?
Well, add the following PowerShell to the above example script:
Note Many other options are available, these are just the most common for a given scenario. The simple way to keep adding to this script is to make modifications in VMM, capture the generated script(s) and work the new portions in to the existing script.
Also Note While the Add-SCVMNetworkGateway and Add-SCNATConnection commands do allow for -OnBehalfOfUser and -OnBehalfOfUserRole the user and user role specified may not have the necessary permissions to complete the operation (likely to the Gateway). The command execution may fail with a “You do not have permission to access one or more of the objects required by this operation.” error message. In this case, you may want to consider granting that access, or forgoing the “OnBehalfOf” for these two commands.
The following is a very basic example for calling this workflow:
Again, there are lots of options here, choose the one that makes sense for your deployment. And I am not going to dive into the details for this example, but obviously you can leverage alternate objects/variables to collect/pass the parameter data within this call (as it is a 1:1 Tenant Admin User Role:VMNetwork in this example where Tenant Admin User Role = User + Subscription to a Plan).
For two reasons, really – First, I wanted to highlight and leverage existing known-good and well-used scripts; Second, the only available and published documentation / examples on the VM Network API are written in C#, not PowerShell.This documentation can be found here: http://msdn.microsoft.com/en-us/library/dn765986.aspx.
So, the above script is what we have been using on my team in our Demo/Test/Dev environment for months now.
Also, one might argue that Network belongs to Fabric Management, which in turn belongs in VMM. Either way, based on what I could find, VMM is your [current] best bet.
Note All this being said, I do have confirmation that this API does exist, and as soon as I have a public link for the API Reference for creating Virtual Networks in WAP, I will update this post right here.
Let’s break this down…
In fact, this is another great time to illustrate this in image form, for these two personas:
Note These options are the same for any Automated VM Role Deployment, Active Directory happens to be the first one to be deployed, so it gets all the attention.
Before we get started on the process, now is the perfect time to give a shout out to one of my WSSC CAT teammates: Nader Benmessaoud [MSFT], for whom I would like to thank for paving the way towards my understanding this process, with early work against the Public Tenant API, PowerShell examples, and foundational support in this effort. That said, I believe it is important for everyone to understand the current step-by-step process necessary to automatically deploy a VM Role via PowerShell against the available endpoints. It will let you appreciate the script that much more.
Step #11 (Cloud Service Creation/Verification) has several Sub-Steps:
Some people like images better, so here is one that represents the text above:
The magic here really exists in handling the data from JSON to Dictionary, Hashtable to JSON, etc. In fact, as you will see in the final script, JSON is the preferred method for data storage and transfer between sections of the script (from InlineScript to InlineScript and workflow to workflow).
As a reference, be sure to review the following TechNet Article: Windows Azure Pack VM Roles Tenant API
I realize I keep using this word to emphasize technical significance, but when I find something so useful and so “simple”, I label it as such. That said, there is a CRITICAL piece in this process that HAS to be pointed out specifically:
I mention it in passing above, but this really makes everything work from a “Service Administrator leveraging the WAP Tenant API (non-public)” perspective.
Here is the TechNet Library Article on the WAP command used to retrieve the token: Get-MgmtSvcToken
Here is the snippet of script (you will see it within the larger script below) where the token is retrieved from WAP, and then placed in a $Headers Hashtable, along with the identity of the User (essentially the WAP Tenant API’s version of “OnBehalfOf”):
Note This $Headers Hashtable gets reused over and over, each time an Invoke-WebRequest is made against the WAP Tenant API (non-Public). In fact, this bit of script is the only reason the InlineScript is leveraged, remoting to the WAP Admin Server – the rest of the calls are 100% Invoke-WebRequests and do not require the WAP Cmdlet. It is also important to note, this functionality is not restricted to VM Clouds, but can be leveraged for WAP Tenant API (non-public) calls, in general.
Based on the various options listed above, and considering the already tremendous length of this blog post, I am going to choose a [hopefully] winning combination that will satisfy the masses. Here goes…
Colonel Mustard In The Study (With A Candlestick)
Oh wait - wrong combination!
So, what does this mean?
Let’s get started…
As you know, using SMA means using PowerShell workflow. It is a bit more complex than just “regular PowerShell”, but many liberties can be taken when leveraging the InlineScript functionality. Taking liberties, making my life easier, and built-in PowerShell Remoting are the three main reasons I chose to go with InlineScript in these examples. I am not opposed to other methods, this is just the one I chose.
So, the overall structure of my SMA Runbooks is as follows:
And to help with the overall visualization as well as where these SMA Runbooks fit in the all-up process, here is another image:
Yeah, yeah. I am getting there. Remember, it is not only about the “code”, but also how that “code” came to be. Or at least that is my reasoning for taking you on this journey.
I am going to start with the Lowest Tier Sub-Runbook (Deploy-VMRole), and work up.
The following PowerShell workflow script (Deploy-VMRole) will deploy a WAP Gallery Item VM Role with the following settings (with the WAP Tenant API Only):
Note Each of these parameters are leveraged throughout the Deploy-VMRole workflow and are configured for maximum re-use and flexibility. The intention of this Low Tier Sub-Runbook is to remain as generic as possible. Specific parameter setting occurs at the Top and Middle Tier Runbooks.
Note There are a ton of nuances within this example workflow. It is because of this, I outlined The Process above. In fact, this example workflow includes the following process steps: 1-5, 8-13 and all Cloud Service Creation sub-steps. Steps 6 and 7 occur in the Middle Tier Sub-Runbook.
The following PowerShell workflow script (Deploy-TenantVMRole) will call the Deploy-VMRole workflow with the following settings:
Note You may keep these example settings, or modify to fit your deployment specifications. Each of these parameters/variables are leveraged in the Deploy-VMRole workflow call and are configured for maximum re-use and flexibility. The intention of this Middle Tier Sub-Runbook is to balance common and Gallery Item VM Role specific data so that the line between them is clear and updates are simple (as the number of Gallery Item VM Roles in your environment grows). Even more specific parameter settings occur in the Top Tier Runbook.
Up to this point, you have been inundated with “generic” workflow examples to Deploy any Gallery Item VM Role. So, you may have actually missed where this post went from “generic” to “specific”. If you did, look up at the Deploy-TenantVMRole workflow script again, and check out lines 34-40ish. For this Middle Tier Sub-Runbook, that is the extent of the “specific”. Believe me, I would have loved to make this and the Lowest Tier Sub-Runbook 100% Generic, but it is just not possible. More about this, and the decisions I made are in the note below.
Note The Gallery Item VM Role specific data (as it relates to the other Gallery Item VM Roles in this blog series, and from the Building Clouds Blog Gallery) is kept in a separate section (lines 34-40ish above) and is surrounded by “if” logic. The intention of this section is to logically store the Gallery Item VM Role specific data by $GalleryItemName. I put quite a bit of thought on where the best place for this “unique” data should live within these example workflows, as well as more dynamic ways to process it – this happens to be where it landed and what it looks like. And obviously, this will not work for every possible VM Role created. But it is one idea/implementation that has worked for my team’s deployment scenario. Oh, and before I forget, this is the portion of the examples where Steps 6 and 7 of The Process take place.
The following PowerShell workflow script (Subscription-Create-Dispatcher) will call the Deploy-TenantVMRole workflow with the following settings:
Note The data entered here is completely customizable and should fit your deployment specifications. The intention of this Top Tier Runbook is to set Gallery Item VM Role specific variables and parameters to be passed on to the much more generic Middle and Lowest Tier Sub-Runbooks. In fact, this Top Tier Runbook is where the Tenant configuration is built out:
Remember, as the Top Tier Runbook, it is the one called by the Subscription.Create WAP/SPF event, configured in the VM Clouds Resource Provider:
It is the main “hook” for the Tenant Provisioning Process of “Subscribe to a Plan, Get a Fully Deployed Set of Collaborative Workloads”.
Note This example is exactly what we have been using on my team in our Demo/Test/Dev environment. As you can see, it includes more than just a call to the Deploy-TenantVMRole workflow. In fact, it also includes:
By the way - I realize that some of the direct text output and use of hardcoded values could be better served in Write-Verbose commands and usage of variables (respectively), but for our environment, and for this example, this is what I went with. That said, you may keep these example settings, or modify to fit your deployment specifications.
Oh, and if you are wondering about Job Monitoring, our environment has that too – it just so happens to be hooked to a different Top Level Dispatch Runbook: VMRole-Create-Dispatcher. And because the Deploy-VMRole workflow leverages the same exact method for VM Role creation as the Tenant Portal, the WAP/SPF event for MicrosoftCompute.VMRole works the same:
Example PowerShell workflow script for VMRole-Create-Dispatcher
The combination of Job Monitoring and Notifications allow for the creation of emails like this:
Oh, alright…Here is another example script.
What does it do?
It is the portion of the Deploy-VMRole required if you wanted to leverage the VMM Cmdlet command Add-CloudResource instead of going WAP Tenant API Only
Note If you want to go this route, this example script replaces the existing script portion within the Deploy-VMRole starting around line 45, right through to the end (before the workflow’s end bracket).
Alternate Example PowerShell workflow script for a portion of the Deploy-VMRole
Note Again, this is still example workflow script to be executed as the Service Admin, this time against VMM directly, instead of leveraging the WAP Tenant API. You will see that I leveraged a second InlineScript, this time to connect to the VMM Server (as the WAP Tenant API calls that come before it execute via InlineScript connected to the WAP Server). You will also see that we are still leveraging “OnBehalfOf” functionality for the VMM commands, this is required if you want proper Tenant ownership of the deployed resources.
The biggest thing to know about the Add-CloudResource command is that the -ResourceDefinition and –ResourceConfiguration parameters require Dictionary Objects. This is why I have both the ResDef and ResDefConfig convert/deserialization steps in this section. In fact, this portion of the script includes steps 8-13 and all Cloud Service Creation sub-steps from The Process described above.
Finally, it is worth restating - JSON is the preferred method for data storage and transfer between sections of the script (from InlineScript to InlineScript and workflow to workflow).
Well, from the Service Admin perspective, nothing really. Sure, I did not provide a non-workflow PS script example, but that is easy enough to generate based on the above examples.
From the Tenant Admin perspective, that is another story. In fact, I think it is time for another visual aid:
Well, it is not for a lack of trying. And actually, the scripts are 99% complete. So are my thoughts on how to deliver the information…It came down to a question of prioritization - for both this blog post series, as well as product demos/videos on my plate. In the end, the Tenant Provisioning Process of “Subscribe to a Plan, Get a Fully Deployed Set of Collaborative Workloads” took precedence.
Besides, isn’t this blog post long enough already?
The very next blog post in this series! And thus, I have updated the Table of Contents below…
Great question! Here are some use cases (all from the Service Admin persona):
Note These are just some of the use cases I could come up with off the top of my head. I am sure you have many more scenarios in mind.
The download (Windows Azure Pack Tenant Provisioning Automation Toolkit.zip) includes (14) files.
For more information please refer to Part 4 of this blog series (near the bottom of the post), or in the description of the TechNet Gallery Contribution itself.
Download the Windows Azure Pack Tenant Provisioning Automation Toolkit from TechNet Gallery here:
Thanks for checking out my latest blog series! For more information, tips/tricks, and example solutions for Automation within System Center, Windows Azure Pack, Windows Azure, etc., be sure to check out the other blog posts from Building Clouds in the Automation Track!