The New World of Tenant Provisioning

The New World of Tenant Provisioning

Published: 2014

For the latest information, please see

http://aka.ms/BuildingClouds

Introduction 1

So, what is this white paper all about? 1

Background 2

Looking Back 2

What can we salvage? 2

What’s new? 2

Download 3

Automated Deployment of Tenant Network and Identity Workload 4

Automated Tenant Virtual Network Deployment 4

Create a VM Network “OnBehalfOf” a User Role 5

Automated Active Directory VMRole Deployment 7

The Options 7

The Process 8

Even More Magic – Bearer Tokens 10

The overall structure of the SMA Runbooks 11

Deploy a Gallery Item VMRole 13

BONUS - Example VMM PowerShell for Gallery Item VMRole Deployment! 20

Use Cases 21

Automated Deployment of the Identity Workload as a Tenant Admin 22

The Options 23

The Process 24

The Pre-Requisites 25

The Pre-Requisite Setup 26

Active Directory Gallery Item VMRole Deployment as a Tenant Admin 27

Use Cases 31

Automated Deployment of Tenant Workloads (Lync, SharePoint, and Exchange) 32

The Scope 33

Out of Scope 34

Deployment as a Service Administrator in SMA (with the WAP Tenant API Only) 34

Existing: SMA Runbook that is the same for each Gallery Item VMRole Deployment 34

New: Updated SMA Runbooks… 35

…for the Lync Gallery Item VMRole Deployment 36

…for the SharePoint Gallery Item VMRole Deployment 36

…for the Exchange Gallery Item VMRole Deployment 36

Future Discovery: How to enumerate ResDef/ResDefExt and ResDefConfig Requirements for any Gallery Item VMRole 38

Deployment as a Tenant Administrator from a PowerShell Script (with the Public WAP Tenant API) 40

New: Deployment Script for Active Directory, Lync, Exchange, or SharePoint 40

Future Discovery: Modified Example PowerShell script to enumerate ResDef/ResDefExt and ResDefConfig Requirements for any Gallery Item VMRole 44

Use Cases 45

Appendix 46

Links Referenced within the Document 46

Links from the Related Blog Series 47

Links to Other Related and Valuable Content 47

The New World of Tenant Provisioning

Introduction

To be clear, this document is all about [on-prem] Automated Tenant Provisioning with [Windows] Azure Pack (WAP). And WAP is just one of the primary technologies leveraged within this example. In fact, Service Management Automation (SMA), PowerShell, PowerShell Workflow, Virtual Machine Manager (VMM), and VMRole Gallery Items, are the backbone of the [example] solution.
Note The guidance here was previously published blog content found on the Building Clouds Blog.

So, what is this white paper all about?

·  Applying existing knowledge of tenant provisioning techniques in this “new world”
·  Transforming existing knowledge (Service Templates) of tenant workload deployments into “Azure Pack friendly” workload deployments (VMRoles)
·  Providing new automation (PowerShell scripts) for the latest tenant provisioning technology (Azure Pack)

Background

Looking Back

If you have been following my work on the Building Clouds Blog, you may remember the following two blog posts:

·  Automation–PowerShell Workflow Script Spotlight–Deploying Virtual Machine Manager Service Templates “OnBehalfOf” Tenant Administrator User Roles

·  Automation–PowerShell Workflow Script Spotlight–Creation and Parameterization of Virtual Machine Manager Run As Accounts for “OnBehalfOf” Service Template Deployment

Well, those were directly related to the initial learning around Tenant Provisioning my team gathered during an internal Proof of Concept. Back then, it was all about the “VMM Service Template”, and while some of that existing knowledge will work in this new world of Azure Pack, the focus now is on VMRoles as the delivery mechanism for application workloads.

What can we salvage?

At the very least, all the existing knowledge around automated deployment of the Tenant Virtual Network (Isolated Software Defined Network (SDN)). As well as, some previously undisclosed techniques for automatically initiating the deployments - all of which still holds true, regardless of delivery mechanism.

What’s new?

The new automation involved in the deployment of VMRoles, as both a Service Admin (via VMM “OnBehalfOf” PS Commands) and a Tenant Admin (via the Service Management WS API).

Download

The download for all the artifacts within this example solution can be found on TechNet Gallery. The downloadable content introduces a collection of example PowerShell Scripts and SMA Runbooks that you can use to Automate Tenant Provisioning of Gallery Item VMRoles within WAP.

URL: http://gallery.technet.microsoft.com/Windows-Azure-Pack-Tenant-3e8afd64

The download (Windows Azure Pack Tenant Provisioning Automation Toolkit.zip) includes (14) files:

For the Service Administrator

·  SMA Runbook Exports (5 files)

o  Create-VMNetwork.xml

o  Deploy-TenantVMRole.xml

o  Deploy-VMRole.xml

o  Subscription-Create-Dispatcher.xml

o  VMRole-Create-Dispatcher.xml

·  PowerShell Scripts (2 files)

o  Deploy-VMRole_OptionalVMMCommands.ps1

o  Get-GIResourceParams_asServiceAdmin.ps1

·  PowerShell Workflows (5 files)

o  Create-VMNetwork.ps1

o  Deploy-TenantVMRole.ps1

o  Deploy-VMRole.ps1

o  Subscription-Create-Dispatcher.ps1

o  VMRole-Create-Dispatcher.ps1

For the Tenant Administrator

·  PowerShell Scripts (2 files)

o  Deploy-TenantVMRoles_asTenantAdmin.ps1

o  Get-GIResourceParams_asTenantAdmin.ps1

Note XML (SMA Runbooks) and PS1 (PowerShell Scripts) files are both provided in the download. Use SMART for Runbook Import and Export to leverage the provided XML files in the above download for an enhanced experience in importing the example solution into your SMA environment.

Optional Some of the scripts within this download contain commented out “optional” portions for Monitoring and Notifications. The associated Runbooks and Variables for these options are not included in this download. For more information about Monitoring and Notifications within SMA, please see the following blog post: Automation–Monitoring and Notifying in Windows Azure Pack with SMA

Automated Deployment of Tenant Network and Identity Workload

What does that mean, exactly?

Well for the context of this document, 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 VMRole. So, for organization’s sake, this section of the document will be split into two main sections – one for automated Tenant Virtual Network deployment, and one for automated VMRole deployment.

Automated Tenant Virtual Network 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 the blog. That said, for this document, 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 throughout the document. 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.

Create a VM Network “OnBehalfOf” a User Role

The following PowerShell workflow script (Create-VMNetwork) will create a VMM VM Network with the following settings (leveraging VMM PowerShell Commands):

·  VM Network Name: <VM Network Name generated by Owner User Role Name defined with parameter>

·  Subnet Name: <defined in script: “TenantSubnet”>

·  Subnet Value: <defined in script: “192.168.0.0/24”>

·  IP Address Pool Name: <defined in script: “TenantIPPool”>

·  IP Address Range Start: <defined in script: “192.168.0.100”>

·  IP Address Range End: <defined in script: “192.168.0.199” – providing for 100 available addresses>

·  DNS IP: <defined in script: “192.168.0.100” – first IP in Pool>

·  OnBehalfOfUser: <User Name parsed from Owner User Role Name defined with parameter>

·  OnBehalfOfUserRole: <User Role parsed from Owner User Role Name defined with parameter>

Note You may keep these example settings, or modify to fit your deployment specifications.

Example PowerShell workflow script for Create-VMNetwork

001
002
003
004
005
006
007
008
009
010
011
012
013
014
015
016
017
018
019
020
021
022
023
024
025
026
027
028
029
030
031
032
033
034
035
036
037
038
039
040
041
042
043
044
045 / workflowCreate-VMNetwork
{
param
(
[string]$OwnerUserRole,
[string]$VmmServerName,
[string]$CloudName,
[string]$LogicalNetworkName
)
inlinescript
{
$subnetValue="192.168.0.0/24"
$subnetName="TenantSubnet"
$dnsIP="192.168.0.100"
$ipAdressPoolName="TenantIPPool"
$ipAddressRangeStart="192.168.0.100"
$ipAddressRangeEnd="192.168.0.199"
$UserRole=$Using:OwnerUserRole
$User=$UserRole.Split("_")[0]
$vmNetworkName="Tenant Network ($User)"
Get-SCVMMServer-ComputerName$Using:VmmServerName-ForOnBehalfOf|Out-Null
$OwnerUserRoleObj=Get-SCUserRole|where{$_.Name-match$Using:OwnerUserRole}
$VMNetwork=Get-SCVMNetwork-OnBehalfOfUser$User-OnBehalfOfUserRole$OwnerUserRoleObj
if(!$VMNetwork){
$CloudObj=Get-SCCloud-Name$Using:CloudName
$logicalNetwork=Get-SCLogicalNetwork-Cloud$CloudObj-Name$Using:LogicalNetworkName
$vmNetwork=New-SCVMNetwork-Name$vmNetworkName-LogicalNetwork$logicalNetwork`
-OnBehalfOfUser$User-OnBehalfOfUserRole$OwnerUserRoleObj
$subnet=New-SCSubnetVLan-Subnet$subnetValue
$vmSubnet=New-SCVMSubnet-Name$subnetName-VMNetwork$vmNetwork-SubnetVLan$subnet`
-OnBehalfOfUser$User-OnBehalfOfUserRole$OwnerUserRoleObj
$allDnsServer=@($dnsIP)
$staticIPAddressPool=New-SCStaticIPAddressPool-Name$ipAdressPoolName`
-VMSubnet$vmSubnet-Subnet$subnetValue-IPAddressRangeStart$ipAddressRangeStart`
-IPAddressRangeEnd$ipAddressRangeEnd-DNSServer$allDnsServer`
-RunAsynchronously-OnBehalfOfUser$User-OnBehalfOfUserRole$OwnerUserRoleObj
}
}
}

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

Configuring more than just the basics…

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:

001
002
003
004
005
006
007
008
009
010
011
012
013
014
015 / #NAT, Gateway and External IP Address Pool Variables
$vmGWServiceName="Gateway Service Name"
$vmNetworkGwName="{0}_Gateway"-f$vmNetworkName
$vmExtStaticIPAddyPoolName="External IP Address Pool Name"
$vmNetworkNATConnName="{0}_NatConnection"-f$vmNetworkName
#NAT, Gateway and External IP Address Pool Commands
$gatewayDevice=Get-SCNetworkGateway-Name$vmGWServiceName
$VmNetworkGateway=Add-SCVMNetworkGateway-Name$vmNetworkGwName-EnableBGP$false`
-NetworkGateway$gatewayDevice-VMNetwork$vmNetwork`
-OnBehalfOfUser$User-OnBehalfOfUserRole$OwnerUserRoleObj
$externalIpPoolVar=Get-SCStaticIPAddressPool-Name$vmExtStaticIPAddyPoolName
$natConnection=Add-SCNATConnection-Name$vmNetworkNATConnName`
-VMNetworkGateway$VmNetworkGateway-ExternalIPPool$externalIpPoolVar`
-OnBehalfOfUser$User-OnBehalfOfUserRole$OwnerUserRoleObj

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.

Calling the Create-VMNetwork PowerShell workflow

The following is a very basic example for calling this workflow:

001
002
003
004
005
006 / $VMMServer="MY_VMM_SERVER"
$UserRole="USER_ROLE"
$CloudName="My Tenant Cloud"
$LogicalNetworkName="Contoso Logical Network"
Create-VMNetwork-VmmServerName$VMMServer-OwnerUserRoleName$UserRole.Name`
-CloudName$CloudName-LogicalNetworkName$LogicalNetworkName

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).

Why go directly against VMM, as opposed to leveraging the WAP Tenant API?

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.

URL: 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.

Automated Active Directory VMRole Deployment

The Options

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 VMRole Deployment, Active Directory happens to be the first one to be deployed, so it gets all the attention.

The Process

I believe it is important for everyone to understand the current step-by-step process necessary to automatically deploy a VMRole via PowerShell against the available endpoints. It will let you appreciate the script that much more.

1.  Generate the Gallery Item VMRole Reference URI (based on Subscription ID and Tenant Portal Address)

2.  Invoke-WebRequest to Get the Gallery Item VMRole Reference (portion of the Gallery Item VMRole Resource Definition (ResDef) URI specific to the Gallery Item VMRole, based on the Gallery Item VMRole Name and data returned from Step #1)

3.  Generate the Gallery Item VMRole ResDef URI (based on data returned from Step #2)

4.  Invoke-WebRequest to Get the Gallery Item VMRole ResDef (based on the URI from Step #3, data returned in JSON)

5.  Convert (Deserialize) the returned ResDef JSON to a 'System.Collections.Generic.Dictionary[String,Object]

6.  Create the Gallery Item VMRole Parameter Hashtable (based on custom variable data)

7.  Convert the Gallery Item VMRole Parameter Hashtable to JSON

8.  Create the Gallery Item VMRole Resource Definition Configuration (ResDefConfig) 'System.Collections.Generic.Dictionary[String,Object]' (based on converted Gallery Item VMRole Parameter data (JSON) and Version information)

9.  Create the Gallery Item VMRole Payload Hashtable (based on custom variable data, Gallery Item VMRole ResDef and ResDefConfig Dictionary Objects)