Working with Hybrid Runbook Worker in Azure Automation

In my current project, I had a chance to work with Azure Automation and Hybrid Runbook Worker machine solution. The task was to migrate high number of VMware Virtual Machines (VMs) running different type of Window Server operating systems into Microsoft Azure and do a few post-migration activities, like install/uninstall software, configure PageFile to the Temporary Storage drive, add server to Azure Backup, etc.


The base of the environment was already in place, including the migration solution which was Azure Site Recovery using Recovery Plan to migrate the servers and start post-migration automation configured in an Azure Automation Account. We took over the current setup and out task was to fix issues and complete the post-migration automation to fulfill all the requirements. The setup contained the following elements

  • Azure Site Recovery (ASR) vault with complete configuration
  • Single Configuration server configured for the ASR vault
  • Azure Automation account
  • Several runbooks designed to run specific post-migration tasks
  • One Hybrid Runbook Worker (HRW) VM connected to the Azure Automation account

When ASR migration finished, the Recovery Plan started an automation runbook which kicked-off a process to complete several tasks on the previously migrated VMs.


After a few test migrations, we realized that something is not right with the current configuration. The runbooks executed on the Hybrid Runbook Worker machine doesn’t always used the correct variable. The issue needed to be solved, because the solution in this form became unreliable and we needed to fix many things after each migration manually


During the early stage of the investigation we realized the Hybrid Runbook Worker is not properly configured, so we decided to wipe the whole thing and install a brand-new server and configure it from scratch. Installation and basic configuration of Azure Automation Hybrid Runbook Worker machines is pretty straight-forward and Microsoft has official documentation covering this part: Because of this, I am not going to discuss that part. In this article, I would like to focus on the possible issues and misunderstandings I ran into during the installation and configuration process.

OMS (Log Analytics) in different subscription

The automated deployment solution for the HRW contains a part which connects the VM to your OMS workspace. The PowerShell script will look for an OMS workspace in the same subscription with the given name. In our case the OMS workspace is in a different subscription and because of that it was not be able to find it, so it tried to create one. However, that name was already taken, so the deployment failed. In case you have the OMS workspace in a different subscription, you have two options

  1. Modify the PowerShell script to look for the OMS workspace in another subscription – It is a good solution if you plan to deploy many HRW machines in the future
  2. Configuration the HRW machine manually as described in the Microsoft article

Because of shortage of time, I choose the second option and configured the HRW manually

Orchestrator.AssetManagement.Cmdlets module is not loading

When the Hybrid Runbook Worker is configured according to the Microsoft article, you may try to run the runbooks you created in Azure Automation account on the HRW to test the functionality. That is the time when you could run into an issue when the Orchestrator.AssetManagement.Cmdlets PowerShell module is not loading properly:

Do not go nuts and try to find the fix for that module (as I did when I encountered this issue the first time). Actually, this module was never designed to work in a normal PowerShell session. When you run it from an Orchestrator Sandbox, which is used by the HRW, it loads properly and runs the command successfully. I have a runbook created in my Automation Account which runs a Get-AutomationVariable command (which is included in the module) and retrieve module information. As the picture below shows the output of that runbook, both commands were executed successfully

Login to Azure using Service Principal Name (SPN)

When we use Azure Automation to execute commands against Azure environment, we need to make sure there is a login procedure in our scripts. To login to Azure from a PowerShell script we can use multiple methods, like services account with username and password or Service Principal Names (SPN) using Certificate which is more secure. When the login process uses SPN with Certificate, we need to make sure that the certificate is available in the personal certificate store of the user running the HRW sessions. To achieve this there is a process to follow:

  1. Import the runbook called “Export-RunAsCertificateToHybridWorker” to the Azure Automation account from the Microsoft runbook gallery – This is an easy task. Just go into the Azure Automation account select Runbooks and Browse Gallery:

    Search the gallery for the runbook and import it.

  2. Execute the runbook with “Default” run as account settings on the HBW – To be able to import the certificate to the HRW the runbook needs to be executed with Default Hybrid Runbook Worker settings as Run As account. To do the setting go to Automation Accounts -> <NameOfTheAccount> -> Hybrid worker groups -> <NameOFHybridWorkerGroup> -> Hybrid worker group settings, and select Default


  3. Export the certificate from the computer account on the Hybrid Runbook Worker and import it to the personal store of the service account which used to execute the runbooks on the HRW. When you do the import into the Personal store of the service account, make sure that the Enable strong private key protection… option is NOT checked, because it prompts for confirmation every time the certificate is used and the runbook process would stop running at that point after a timeout.
  4. If needed change the Run As account back to the desired user account on the HRW by following the process described in Step 2 and select a Custom account.

AzureAutomationAuthoringToolkit on Hybrid Runbook Worker

NEVER ever install the module AzureAutomationAuthoringToolkit on HRW machines, because the cmdlets in this module has the same name as the ones in the Orchestrator.AssetManagement.Cmdlets. This module was only designed to make the Automation runbooks able to run on servers without Hybrid Runbook Worker role, becaise as you read in a previous chapter, the Orchestrator.AssetManagement.Cmdlets are not working when it executed in a normal PowerShell environment. This module creates a local cache of the variables, connections, credentials and certificates of the Automation Runbook you set it up with. Then when a runbook is executed in a normal PowerShell session, it can execute the commands related to the Automation account items and get back the values without issue. However, if the module AzureAutomationAuthoringToolkit is installed on the HRW the information in the local cache will be returned even when the runbook executed in the orchestrator sandbox, which is the normal environment for Azure Automation runbooks

During my latest encounter these were the obstacles I needed to overcome. I hope with this article I am able to make your life easier and the configuration faster

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.