More Automation! Using Hybrid Worker Runbooks in Azure Automation

hybrid worker runbooks

As this year goes on, I’ve been spending more time expanding the things I can do in with Azure Automation. It has allowed me to automate some of the more tedious tasks in my day to day. One limitation I’ve experienced so far though, is that I cannot run anything outside of the sandbox where the runbook lives. This is intentional obviously; it’s how Azure Automation accounts are designed. Even still, it got me wondering about how to reach out and do more. Thats when I decided to start testing Hybrid Worker Runbooks.

The purpose of these Hybrid worker runbooks is to extend the capabilities and usage of Azure Automation accounts to servers in your environment. This environment may be on premises servers or Azure cloud hosted servers. There are additional considerations with on premises servers, but when configured correctly the benefits can be immense.

This is my first foray into these hybrid runbook worker accounts. I don’t want this blog to be considered any king of expert opinion. The idea here is to document the basics and help someone else getting started to understand things I had to figure out when I first started playing with these features. As I expand and spend more time testing and learning, I’ll continue to write about it and share those experiences too. I just want to make sure that this is clear before I continue.


Please understand that the content herein is for informational purposes only. This existence and contents shall not create an obligation, liability or suggest a consultancy relationship. In further, such shall be considered as is without any express or implied warranties including, but not limited to express and implied warranties of merchantability, fitness for a particular purpose and non-infringement. There is no commitment about the content within the services that the specific functions of the services or its reliability, applicability or ability to meet your needs, whether unique or standard. Please be sure to test this process fully before deploying in ANY production capacity, and ensure you understand that you are doing so at your own risk.

Table of Contents

Preparing for Hybrid Worker Runbooks
Add Private Endpoint to Automation Account
Configuring Hybrid Worker Group and Runbook
Test the Hybrid Worker
Using Hybrid Workers in Automation Scripts

Preparing for Hybrid Worker Runbooks

As I said in the introduction, you can leverage Hybrid Runbook Workers in Azure hosted servers, as well as on premises hosted servers. For the purposes of this blog, I’m going to focus on the Azure hosted servers for now. This is primarily because I don’t have a VPN tunnel between my home lab and my Azure Lab (yet!). I’m thinking that might be a good idea for a future blog.

Anyways, there are a few things you need to have set up prior to running the setup script for the Hybrid worker. Microsoft explains in greater detail here, but these are the basics.

  • Log Analytics Workspace
    • I suggest creating a new one just for this Hybrid worker, so you avoid duplicate or confusing data.
  • Log Analytics Agent
    • Will be installed automatically if you use the PowerShell script provided by Microsoft.
  • Windows OS
    • Seems like just about any will work (Server 2012R2 or Windows 7 and newer…)
  • Network Connection
    • It is explained here, but you will need an Azure VNet and some kinds of connections for the Automation Account and your server/Windows machine. For this, I am just using a single VLAN inside if a single VNet.

Thats about it. Microsoft has been kind enough to provide a script that will automate the entire installation, so long as we do the prerequisite work. I recommend creating a new Resource Group for all the items that will be associated with this Azure Automation Account and Hybrid worker.

Unfortunately, the Azure Dev tenant isn’t going to allow you to spin up Virtual Machines (that I have seen) so you will want to either use the free $200 for a new tenant or be sure to keep everything spun down when you aren’t using it. Maybe use an automation account to do it for you? 🙂

Add Private Endpoint to Automation Account

When we set up our Automation Account before, we gave it public network access. This is fine for testing, but now we want to start getting more serious about security. Time to add a Private Endpoint and connect the Automation Account to the same place we have our Azure server.

  1. First, go to your Automation Account, and on the left-hand side, click on the “Networking” tab. Click “+ Private Endpoint” to add a new Private nic.
private endpoint for automation account step 1
  1. Assign your private endpoint to a resource group, give it a name and an interface name. Choose the same region your Automation Account lives in, and then hit Next.
private endpoint for automation account step 2
  1. On the Resource page, choose “DSCAndHybridWorker” as your Target sub-resource. Click next.
private endpoint for automation account step 3
  1. On the Virtual network tab, choose your VNet and subnet where your server lives. It’s fine to have it dynamically allocate the IP address for now. Click next to go to the next page.
private endpoint for automation account step 4
  1. On the DNS page, just be sure that the “Integrate with private DNS zone” radio button is set to “YES”. This will ensure that when the Automation Account runs on the Hybrid Worker, the Hybrid Worker will be able to find the automation account. (If you aren’t using Azure DNS in your VNet, you will need to manually add the DNS records to your DNS zones.). Click Next.
private endpoint for automation account stepv5
  1. Finally, add some tags if you are using them, and hit Next. Give it a minute to validate the configuration, then hit Create. Once it is finished, we can log into the Hybrid Worker server to get ready for the next section.
private endpoint for automation account step 6

Configuring Hybrid Worker Group and Runbook

Now that we have our private endpoint configured, we can set up the server side. In general, your server where your Hybrid Runbooks will run, needs to be capable of running whatever scripts you plan to run. Scale it to your needs.

Setup Hybrid Worker Server

  1. First thing is to create a Hybrid Worker Group. On the left-hand side, click “Hybrid Worker Group”. From there, choose “+ Create Hybrid Worker Group”. Give it a unique name, then click next. Here you have the option to add credentials or use existing credentials for the Hybrid worker. I’m leaving this Default for now, which means it will run under “SYSTEM” context.
  1. On the next page, it will as if you want to add machines. Just skip this for now, the script will do it for us. Click next, then create. Grab the Hybrid worker group name as you will need it shortly.
  1. Then, go to the PowerShell gallery to get the Hybrid worker installation script. This is the easiest way to configure this hybrid worker server. Run this command on the Hybrid Worker server to install the script. Accept any prompts as these are pre-req’s for the installation script.
powershell gallery for installation script
  1. Next, grab this text and start to modify it so that the variables are filled with your information.
$NewOnPremiseHybridWorkerParameters = @{
  AutomationAccountName = <nameOfAutomationAccount>
  AAResourceGroupName   = <nameOfResourceGroup>
  OMSResourceGroupName  = <nameOfResourceGroup>
  HybridGroupName       = <nameOfHRWGroup>
  SubscriptionID        = <subscriptionId>
  WorkspaceName         = <nameOfLogAnalyticsWorkspace>
.\New-OnPremiseHybridWorker.ps1 @NewOnPremiseHybridWorkerParameters

I recommend doing this in PowerShell ISE on the server where you are working. You can skip OMSResourceGroupName and WorkspaceName if you want, as the script will automatically create them if it needs it if you don’t input one. Otherwise, if you have one you want to use, update it and then run this script.

parameters to create the hybrid worker settings
  1. When you run this script, it will download all the modules it needs, and it will then create everything it needs to get connected to your Automation Account. If you get an error about running the script, remove the “.\” at the beginning, and it will find the script on its own.
importing modules to install the hybrid worker assets
  1. Once the script is done loading everything, it will prompt you to sign in with your Azure account. Sign in, and it will finish the configuration and Hybrid Worker process.
finished running the hybrid worker script

Setup Hybrid Runbook

  1. First, we want to confirm our Hybrid worker is available and connected to the group. Go back to our Automation Account, and on the left-hand side, click on Hybrid Worker Groups. Click on the group we created to see what workers are assigned.
Our newly added Hybrid worker group
Our newly added Hybrid worker group
  1. We should now see a dashboard box with the number “1” in it. Click on the side where the “Hybrid Workers” button is, and you should see the server. As long as you do, we are ready to test!
We should see 1 here for our Hybrid Worker
We should see 1 here for our Hybrid Worker

Test the Hybrid Worker

We can now test and make sure our Hybrid worker is working. The easiest way to do this, is to see if we can create a text in a location on the server. If you have more than one server in your VNet, then you could also ping a different server. Either way, the goal will be to prove that we can access something that the Automation Account wouldn’t be able to access otherwise.

If you forget how to create a runbook, check this out here to get a quick refresher.

Ping Test Example

You can use this script in your Automation Account to test if you can ping another server.

Testing connectivity from Azure Automation Account to On-prem resources

Attempts to verify connectivity through a simple ping for private endpoints in Azure Automation Accounts

Test-Connection -ComputerName "DC1","DC2","DC3"

Author: Smitty
Date: 3/4/23
Version: 1.0


#List of servers that should always pass connectivity when on the network
#Use a Comma to separate server names if you want to ping more than one

Test-Connection -ComputerName "hrw-test" 

Once you create your run book, go to the Test Pane. Before you hit Start, be sure to change the run settings to Hybrid Worker Group so use the Hybrid Worker for the test. The output will display when the script is done and should show a success. If you want to compare, test it again on the “Azure” run settings, and it should fail.

ping test example for hybrid worker

Create a Text File Test

You can use this script in your Automation Account to test creating a file. You can also use a file share if you wish to test that instead. Keep in mind, if you chose to do a user account instead of Default (SYSTEM) above, then the account you are using will need permissions to write to the folder you are testing or it will fail.

Testing connectivity from Azure Automation Account to On-prem resources

Attempts to verify connectivity through a simple file create script from Azure Automation Accounts

Author: Smitty
Date: 3/4/23
Version: 1.0


#Change the file and name as needed to manage testing 
New-item -Path "C:\Temp" -Name "File Test.txt" -ItemType File -Value "This test was a success!"

After you run this script, you should be able to log into your Hybrid Worker and find this file (As long as it was a success). I had to create the C:\temp folder because it didn’t exist, so make sure your directory exists before you run this test!

file create test for hybrid worker
Successfully run!
hybrid worker test is a success
We can see the file was successfully created

Using Hybrid Workers in Automation Scripts

The last thing to know is pretty straightforward. When you are ready to use your script, and want it to run on a Hybrid Worker group, you configure that from the Schedule tab.

  1. Click inside your runbook and click the schedules button. Hit the “+ Add a Schedule” button.
  2. Choose or create your schedule for your script to run.
  3. On the Run Settings, be sure to change it to the Hybrid Worker, and choose the Hybrid Worker Group we created previously.
  4. Finally, hit OK to save the schedule.
hybrid worker schedule
Settings to ensure it runs on the hybrid


There we have it! I’m going to be experimenting with this more as time goes by. One thing in particular I would like to explore more will be automation for on premises servers. I’ll be setting up a VPN connection from my Azure environment to my home lab so I can work out some scripting I could do there.

What about you? What are you running on your Hybrid workers? Security settings for servers? Logging or data collection? What about file copies or even maybe desired state configuration settings? The possibilities are limitless!

Let me know! I’d love to hear your ideas and see if I can implement any of them in my own lab. Hit me up on Twitter @SeeSmittyIT to let me know what you thought of this post. Or if you are avoiding the bird site, I’m also posted up on Mastodon @[email protected]. Thanks for reading!


Curtis Smith works in IT with a primary focus on Mobile Device Management, M365 Apps, and Azure AD. He has certifications from CompTIA and Microsoft, and writes as a hobby.

View all posts by Smitty →