How to launch an Azure Automation runbook on a Hybrid Worker via PowerShell

With the update in Azure PowerShell 1.0, quite a lot has changed. Working with Azure has been divided into cmdlets for working with Azure 1.0 (Azure Service Management) and Azure 2.0 (Azure Resource Manager). With the GA release of the new Azure portal ( that was called “the preview portal” forever, has arrived. In short, the PowerShell cmdlets for working with Azure Resource Manager include an “Rm” after the “Azure”, such as in New-AzureRmVm, the cmdlet for creating a new VM in Azure IaaS v2…aka Azure Resource Manager.

Azure Automation, when connected to your Operations Management Suite (OMS) subscription, eanbles you to tap into a new Azure Automation feature called a Hybrid Runbook Worker. This allows you to run runbooks on machines located in your data center in order to manage local resources. The runbooks are stored and managed in Azure Automation and then delivered to one or more on-premises machines where they are run.

If you are unfamiliar with any of the above concepts, you can click on the links and read more. If you are familiar and just want to know what the PowerShell is you need to call an Azure Automation runbook and run it on a Hybrid Worker, you will find the script and some explanation below.


You will need the following in before you get started

  • The latest Azure PowerShell module, which you can install using the Web Platform Installer or the PowerShell Gallery, on the system where you will run the script
  • An Azure AD user with appropriate rights from your Azure subscription. You cannot use a Microsoft (Live) account when authenticating to your Azure subscription.

I am working on a Windows Server 2012 R2 system. I also have the production preview of the Windows Management Framework 5 installed, though this is not required.

Sample Script

In this sample, we will assume you are working with your default Azure subscription. We will build on this example to cover working with multiple Azure subscriptions in a future post.

# Import Azure Modules
Import-Module "C:\Program Files (x86)\Microsoft SDKs\Azure\PowerShell\ResourceManager\AzureResourceManager\AzureRM.Profile\AzureRM.Profile.psd1"
Import-Module "C:\Program Files (x86)\Microsoft SDKs\Azure\PowerShell\ResourceManager\AzureResourceManager\AzureRM.Automation\AzureRM.Automation.psd1"

# Authenticate with Azure AD credentials

$SecurePassword=Convertto-SecureString –String $MyClearTextPassword –AsPlainText –force

$cred=New-object System.Management.Automation.PSCredential $MyUserName,$SecurePassword

Login-AzureRmAccount -Credential $cred

#Runbook parameters
$params = @{"Message"="Hello Azure Community!";}

Start-AzureRmAutomationRunbook –AutomationAccountName "contoso-testrba" –Name "Hello-World" `
-ResourceGroupName 'Default-Networking' –Parameters $params -RunOn 'ConfigMgrPool'

A little explanation…

A couple of key areas of the script that deserve explanation.

On lines 5 through 13, you will see how we handle credentials. You will need to replace the user name and password with your Azure AD user. In this case, I have hard-coded the credentials so we can riff on this in some other contexts in my next post. If you intend to call this script right out of PowerShell, you may want to prompt for the password each time. You can do that by replacing the code on line 7 above with the following:

$MyClearTextPassword = Read-host "Enter your password:" -AsSecureString

Runbook Name and Parameters

  • The runbook parameters are presented on line 16 in name / value pairs, separated by semicolons (a hash table). In this case, I am launching a runbook named “Hello-World” that has one parameter called “Message”, which accepts a text string. You can see this pictured in the image below. If you have a runbook with multiple parameters, simply provide additional name / value pairs separated by semicolons.


  • On line 18, notice the -AutomationAccountName parameter where you specify the name of the Azure Automation account associated with this runbook, as well as the -Name parameter where you specify the name of the runbook.
  • On line 19, you will need to update the -ResourceGroupName parameter with the name of the Azure resource group containing the Azure Automation account.
  • Finally, the name of your Azure Automation Hybrid Worker group is specified in the -RunOn parameter. If you want to know where to find your available Hybrid Worker groups, you can see the GUI version of this in the image above from the Azure portal.

Once you execute the runbook, the output if it runs successfully will be roughly as follows:


In the Azure portal, go to the Jobs area of your Azure Automation account where you can see detailed job results:


In our next installment, we will do something interesting with this script you can use in your environment…today!

Leave a Reply