Windows Azure Pack, Products, VConnect
How to invoke System Center Orchestrator Runbooks from VConnect?
VConnect Operations Templates, Custom Operation and Orchestrator Runbooks
Introduction:
VConnect Operation Templates™ (OT) define set of steps performed during provisioning and de-provisioning of a Virtual Machine. These templates are simple .JSON files that can be modified by the administrators to add additional custom steps to enable automation of any IT process. VConnect Deployment Engine running on an agent provides a reliable execution framework for these templates along with supporting synchronous and asynchronoussc step executions.
Operation Templates support adding any PowerShell script or .Net code as a step. This scenario takes advantage of that to create a PowerShell script that invokes a Runbook asynchronously and wait until the Runbook completes.
Invoking a Runbook
A quick look at how the flow of events look end to end from Windows Azure Pack Tenant portal to Runbook
è Tenant User Creates VM in Azure Pack Portal
à VConnect Deployment Task is created based on the customized Operation Template™
à VConnect Operation step invokes the custom script that invokes a Runbook
à Microsoft System Center Orchestrator starts Runbook Execution
à VConnect Operation returns with the asynchronous wait status
à VConnect releases any resources held while the runbook is executing asynchronously
à VConnect periodically checks if the Runbook job completed
à Once the Runbook status is marked completed, VConnect moves to next steps
à VConnect Completes all the Steps defined in the Operation Template™
è Virtual Machine is created and marked as Ready for Tenant User
è Admin User can monitor and take corrective actions if required from Windows Azure Pack Admin portal. VConnect Admin extension displays the deployments and Operation steps
Asynchronous Invocation Overview
VConnect Operation Templates™ supports asynchronous operation steps. Asynchronous operation steps, as the name implies, starts executing a long running operation and returns back immediately. This frees VConnect resources. VConnect automatically persists any asynchronous job data returned from the operation, it then periodically calls back the Operation using prescribed async Call back mechanism, passing the previously persisted async job data to check the async completion status.
The sample runbook mentioned below and the sample scripts provided demonstrates the steps and process involved.
Download Sample Scripts and Sample Runbook:
You can download all the sample scripts and runbook example used from here.
Do it Your Self: Invoke Sample Runbook from Operations Templates during VM Provisioning
Step 1: Prepare the Runbook
Scenario:
- Runbook take a input parameter called ‘Param1’, which is passed from VConnect
- Runbook executes asynchronously – to simulate this, there is a Sleep added in the .net script activity
- When completed Runbook will return a result (out) parameter called ‘ResuldData’
Screen 1: Runbook overview
Screen 2: Define Returned Data ‘ResultData’ by
- Right-click the specific runbook tab
- And click ‘Properties’
- And choose ‘Returned Data’
- Click Add button to add the ‘ResultData’
Screen 3: Add a ‘Initialize Data’ activity, click ‘Details’ and add a parameter called ‘Param1’
Screen 4: Add a new ‘Run .Net Script’ activity, click ‘Details’ select the Language Type as ‘PowerShell’ and enter the ‘Script’ and add Published Data as shown below.
|
# Define function to add entry to trace log variable function AppendLog ([string]$Message) { $script:CurrentAction = $Message $script:TraceLog += ((Get-Date).ToString() + "`t" + $Message + " `r`n") }
$Param1 = "\`d.T.~Ed/{97D972DB-472C-4E6C-B6EA-238F4EBC0B87}.{957EF51D-9912-4454-84B6-C83854120E6A}\`d.T.~Ed/" AppendLog "Parameter Received: [$Param1]" start-sleep -seconds 25
$ResultData = "Runbook Processed VM: \`d.T.~Ed/{97D972DB-472C-4E6C-B6EA-238F4EBC0B87}.{957EF51D-9912-4454-84B6-C83854120E6A}\`d.T.~Ed/" |
Published Data.
Screen 5: Add a ‘Return Data’ activity and ensure that in ‘Details’ ‘ResultData’ is seen as below.
Finally test the runbook by executing in Runbook Tester and see that the result
Before going into the main script, you need to get the Runbook Id that you want to invoke from your environment and the Param Id. If you have imported the sample runbook provided, then the Param Id most likely stays the same as used in the script, but you need to get the Runbook Id from your Orchestrator.
Find out the runbook id and param id
Use the ‘OrchestratorServiceModule.psm1’ provided along with the sample scripts.
|
$scomServer = 'SCOM' $scomUserDomain = 'wapdemo' $scomUserName = 'administrator' $scomUserPassword = 'XXXXXXXXX'
Import-Module C:\inetpub\MgmtSvc-CloudAssert-VConnect\OrchestratorServiceModule.psm1
if (!$?) { $errorMessage = "Failure loading the module.`nError Message:`n" $errorMessage += $error[0].ToString()
$result = @{ IsSuccess = $false Message = "Error: " + $errorMessage ErrorCode = 0 } New-Object PSObject -Property $result return }
$creds = Get-Credentials $scomUserDomain $scomUserName $scomUserPassword $url = Get-OrchestratorServiceUrl -server $scomServer
$runbook = Get-OrchestratorRunbook -serviceurl $url -credentials $creds -RunbookPath "\ProcessAndReturnData" -Verbose $rbId = $runbook.Id $inputParam = $runbook.Parameters | Where-Object {$_.Direction -eq "In" } $paramName = $inputParam.Name $paramId = $inputParam.Id |
SampleInvokeRunbookWithAsync.PS1
Following script has comments inline and self-explanatory method names. The starting point of the script is found at the bottom, where either the ‘ProcessAsyncCallback’ or ‘ProcessMain’ is called depending on whether VConnect has called the script with ‘IsAsyncCallback’ or not.
Another important snippet to note is the result format. For Completion results (Success or Failure) the format must be like the following:
|
$resultDataJson = ConvertTo-Json -InputObject $resultData -Compress $result = @{ IsSuccess = $true Message = $message Details = $resultDataJson ErrorCode = 0 } |
For asynchronous results it must of the following format:
|
$asyncResultDataJson = ConvertTo-Json -InputObject $resultData -Compress $asyncResult = @{ IsSuccess = $true IsWaitingForAsyncCompletion = $true Message = "Completed async. " + $asyncResultDataJson ErrorCode = 0 Details = $asyncResultDataJson } |
Note: It is important to use ‘-Compress’ in ConvertTo-Json. And the ‘Details’ field can only contain string results.
|
########################################################################### # SampleInvokeRunbookWithAsync.PS1 ###########################################################################
## Following parameters will be passed by VConnect and available for your script
#$HostServerName = @(HostServerName) #$HostServerPort = @(HostServerPort) #$UserName = @(UserName) #$Password = @(Password) #$Datacenter = @(Datacenter) #$Cluster = @(Cluster) #$HostName = @(HostName) #$SubscriptionId = @(SubscriptionId) #$VMName = @(VMName) #$ResourcePoolName = @(ResourcePoolName) #$FolderName = @(FolderName) ###########################################################################
$scomServer = '[YOUR ORCHESTRATOR SERVER]' $scomUserDomain = '[YOUR DOMAIN]' $scomUserName = '[YOUR ADMIN USER]' $scomUserPassword = '[YOUR PASSWORD]'
# This is for the sample runbook. Use your Runbook Guid $runBookId = [guid]"32cee37d-bada-4cc6-9f69-bc85e0e08100"
# This is for the sample runbook param. you should look up for your runbook in the $runbook.Parameters $param1GUID = "957ef51d-9912-4454-84b6-c83854120e6a"
Import-Module C:\inetpub\MgmtSvc-CloudAssert-VConnect\OrchestratorServiceModule.psm1
if (!$?) { $errorMessage = "Failure loading the module.`nError Message:`n" $errorMessage += $error[0].ToString()
$result = @{ IsSuccess = $false Message = "Error: " + $errorMessage ErrorCode = 0 } New-Object PSObject -Property $result return }
function CheckJobStatus() { param([guid] $JobId,[int] $MaxIteration) $runBookjob = Get-OrchestratorJob -JobId $JobId -ServiceUrl $url -Credentials $creds $iterationCount = 0; while($runBookjob -ne $null -and !(IsCompleted $runBookjob.Status) -and ($iterationCount++ -lt $MaxIteration)) { start-sleep -seconds 10 $runBookjob = Get-OrchestratorJob -JobId $JobId -ServiceUrl $url -Credentials $creds if($runBookjob -eq $null -or ($_ -ne $null -and $_.Exception -ne $null)) { return $null; }
if(IsErrorStatus($runBookjob.Status)) { return $runBookjob; } } return $runBookjob; }
function IsErrorStatus($RunBookstatus) { return $RunBookstatus.StartsWith("Error") -or $RunBookstatus.StartsWith("Fail") -or $RunBookstatus.StartsWith("Cancelled"); }
function IsSuccessStatus($RunBookstatus) { return $RunBookstatus.Equals("Completed"); }
function IsCompleted($RunBookstatus) { $isSuccess = IsSuccessStatus $RunBookstatus; $isFailed = IsErrorStatus $RunBookstatus; return ($isSuccess -or $isFailed); }
function GetErrorResult($message, $resultData) { $resultDataJson = ConvertTo-Json -InputObject $resultData -Compress $result = @{ IsSuccess = $false Message = $message Details = $resultDataJson ErrorCode = 1 } return $result }
function GetSuccessResult($message, $resultData) { $resultDataJson = ConvertTo-Json -InputObject $resultData -Compress $result = @{ IsSuccess = $true Message = $message Details = $resultDataJson ErrorCode = 0 } return $result }
function GetAsyncResult($resultData) { $asyncResultDataJson = ConvertTo-Json -InputObject $resultData -Compress $asyncResult = @{ IsSuccess = $true IsWaitingForAsyncCompletion = $true Message = "Completed async. " + $asyncResultDataJson ErrorCode = 0 Details = $asyncResultDataJson } return $asyncResult; }
function GetAsyncDataRunBookJobId() { if($asyncStateJson -ne $null) { $asyncInput = ConvertFrom-Json -InputObject $asyncStateJson return [guid]$asyncInput.RunBookJobId; }
return $null }
function GetResultToReturn($job) { if($job -eq $null) { $msg = "Error: Runbook execution didnt happen." + $error[0] $errorResult = GetErrorResult $msg return $errorResult; } if(IsErrorStatus $job.Status) { $errorResult = GetErrorResult "Error: Runbook error." return $errorResult; } if(IsSuccessStatus $job.Status) { $ri=Get-OrchestratorRunbookInstance $job -Credentials $creds
# NOTE: change these based on your Runbook Out Parameters. This sample runbook publishes 1 out string param $params=@(Get-OrchestratorRunbookInstanceParameter -RunbookInstance $ri -Credentials $creds) $resultOut = $params | where {$_.Name -eq 'ResultData'} $resultData = @{ ResultData = $resultOut[0].Value } $resultDataJson = ConvertTo-Json -InputObject $resultData -Compress $message = "Job: " + $job.id + ".Status: " + $job.Status + ". Result: " + $resultOut[0].Value
$successResult = GetSuccessResult $message $resultData; return $successResult; } if(!(IsCompleted $job.Status)) { $asyncResultData = @{ RunBookJobId = $job.Id }
$asyncResult = GetAsyncResult $asyncResultData; return $asyncResult; } }
function ProcessAsyncCallback() { $RunBookJobId = GetAsyncDataRunBookJobId
if($RunBookJobId -ne $null) { $job = CheckJobStatus $RunBookJobId 3 $result = GetResultToReturn $job; New-Object PSObject -Property $result return } else { $errorResult = GetErrorResult "Error: Async Call Back did not receive the required input param: RunBookJobId" New-Object PSObject -Property $errorResult return } }
function ProcessMain() { # Use runbook id $runbook = Get-OrchestratorRunbook -serviceurl $url -runbookid $runBookId -credentials $creds
if ($runbook -ne $null) { $childParams = @{ $param1GUID=$VMName }
$job = Start-OrchestratorRunbook -runbook $runbook -credentials $creds -Parameters $childParams
if ($job -ne $null) { $jobId = [guid]($job.Id); $job = CheckJobStatus $jobId 3; $result = GetResultToReturn $job; } else { if($_ -ne $null -and $_.Exception -ne $null) { $response = $($_.Exception.Response) if ($response -ne $null -and $response.ContentLength -gt 0) { $reader = [IO.StreamReader] $response.GetResponseStream() $output = $reader.ReadToEnd() $reader.Close() } } $msg = $error[0] | out-string $result = GetErrorResult "Exception while calling execute Runbook: " + $rbarray.Name + ". Errors: " + $output + '. ' + $msg; } } else { $msg = $error[0] | out-string $result = GetErrorResult "Exception while getting Runbook. Errors: " + $msg; } return New-Object PSObject -Property $result }
### Main Entry ###
# get credentials (set to $null to UseDefaultCredentials) $creds = Get-Credentials $scomUserDomain $scomUserName $scomUserPassword # create the base url to the service $url = Get-OrchestratorServiceUrl -server $scomServer
if($IsAsyncCallback) { ProcessAsyncCallback } else { ProcessMain } ###################
|
You can test this script standalone from a PowerShell windows to ensure that it works.
Update VConnect Operation Template to add Script Op
Now that we have the Runbook, and a script to execute the runbook, next step is to add an Operation Step to the VConnect Operation Template that will invoke the script.
Open the template file: C:\inetpub\MgmtSvc-CloudAssert-VConnect\bin\Templates\VCenterStandAloneVMCreateTemplate.json
Add the following step:
- Make sure the script name matches the sample script file you have created
- You can add the step at the starting of Operations array for test, but practically it can be added at any place
|
{ "Name": "VMScriptOp", "Label": "Invoke Custom Operation", "Provider": "VConnectOperationsProvider", "MaxRetryAttempts": 3, "Params": { "IsSkipIfFileNotExist": true, "scriptfilename": "SampleInvokeSMARunbookWithAsync.ps1" } } |
The entire template will look like the following:
|
{ "Version": "1.7.1", "Name": "DeployVMTemplate", "Operations": [ { "Name": "VMScriptOp", "Label": "Invoke Custom Operation", "Provider": "VConnectOperationsProvider", "MaxRetryAttempts": 3, "Params": { "IsSkipIfFileNotExist": true, "scriptfilename": "SampleInvokeSMARunbookWithAsync.ps1" } }, { "Name": "CreateResourcePoolOp", "Label": "Create Resource Pool", "Provider": "VConnectOperationsProvider", "MaxRetryAttempts": 3 }, { "Name": "DeployVMFromTemplateOp", "Label": "Clone and Create VM", "Provider": "VConnectOperationsProvider", "MaxRetryAttempts": 3 }, { "Name": "GetNetworkSettingsOp", "Label": "Add Default Network Settings", "Provider": "VConnectOperationsProvider", "MaxRetryAttempts": 3 }, { "Name": "CustomizeVMOp", "Label": "Customize VM", "Provider": "VConnectOperationsProvider", "MaxRetryAttempts": 3, "Params": { "NicSettings": "" } }, { "Name": "VMScriptOp", "Label": "Execute AfterVMCustomizationScript.ps1", "Provider": "VConnectOperationsProvider", "MaxRetryAttempts": 3, "Params": { "IsSkipIfFileNotExist": true, "scriptfilename": "AfterVMCustomizationScript.ps1" } }, { "Name": "FinishCreateVMOp", "Label": "Finalize and Mark VM Ready", "Provider": "VConnectOperationsProvider", "MaxRetryAttempts": 3 } ] } |
Save the changes and now everything is set for your custom step to be invoked everytime a tenant user creates a new VM.
View Deployments and Operation Steps from Admin Portal
Admin Portal à VConnect à Deployments