Migrate an existing agent-based hybrid workers to extension-based-workers in Azure Automation (2023)

  • Article
  • 14 minutes to read

This article describes the benefits of Extension-based User Hybrid Runbook Worker and how to migrate existing Agent-based User Hybrid Runbook Workers to Extension-based Hybrid Workers.

There are two Hybrid Runbook Workers installation platforms supported by Azure Automation:

  • Agent based hybrid runbook worker (V1) - The Agent-based hybrid runbook worker depends on the Log Analytics Agent.
  • Extension based hybrid runbook worker (V2) - The Extension-based hybrid runbook worker provides native integration of the hybrid runbook worker role through the Virtual machine (VM) extension framework. 

The process of executing runbooks on Hybrid Runbook Workers remains the same for both.

Benefits of Extension-based User Hybrid Runbook Workers over Agent-based workers

The purpose of the Extension-based approach is to simplify the installation and management of the Hybrid Worker and remove the complexity working with the Agent-based version. Here are some key benefits:

  • Seamless onboarding – The Agent-based approach for onboarding Hybrid Runbook worker is dependent on the Log Analytics Agent, which is a multi-step, time-consuming, and error-prone process. The Extension-based approach offers more security and is no longer dependent on the Log Analytics Agent.

    (Video) Extension-based User Hybrid Runbook Worker in Azure Automation

  • Ease of Manageability – It offers native integration with Azure Resource Manager (ARM) identity for Hybrid Runbook Worker and provides the flexibility for governance at scale through policies and templates.

  • Azure Active Directory based authentication – It uses a VM system-assigned managed identities provided by Azure Active Directory. This centralizes control and management of identities and resource credentials.

  • Unified experience – It offers an identical experience for managing Azure and off-Azure Arc-enabled machines.

  • Multiple onboarding channels – You can choose to onboard and manage Extension-based workers through the Azure portal, PowerShell cmdlets, Bicep, ARM templates, REST API and Azure CLI.

  • Default Automatic upgrade – It offers Automatic upgrade of minor versions by default, significantly reducing the manageability of staying updated on the latest version. We recommend enabling Automatic upgrades to take advantage of any security or feature updates without the manual overhead. You can also opt out of automatic upgrades at any time. Any major version upgrades are currently not supported and should be managed manually.


(Video) Azure Automation Hybrid Worker with Azure Arc Enabled Server

The Extension-based Hybrid Runbook Worker only supports the User Hybrid Runbook Worker type, and doesn't include the System Hybrid Runbook Worker required for the Update Management feature.


Machine minimum requirements

  • Two cores
  • 4 GB of RAM
  • Non-Azure machines must have the Azure Connected Machine agent installed. To install the AzureConnectedMachineAgent, see Connect hybrid machines to Azure from the Azure portal for Arc-enabled servers or see Manage VMware virtual machines Azure Arc to enable guest management for Arc-enabled VMware vSphere VMs.
  • The system-assigned managed identity must be enabled on the Azure virtual machine, Arc-enabled server or Arc-enabled VMware vSphere VM. If the system-assigned managed identity isn't enabled, it will be enabled as part of the installation process through the Azure portal.

Supported operating systems

WindowsLinux (x64)
● Windows Server 2022 (including Server Core)
● Windows Server 2019 (including Server Core)
● Windows Server 2016, version 1709 and 1803 (excluding Server Core), and
● Windows Server 2012, 2012 R2
● Debian GNU/Linux 10 and 11
● Ubuntu 22.04 LTS
● SUSE Linux Enterprise Server 15.2, and 15.3
● Red Hat Enterprise Linux Server 7 and 8 

Other Requirements

WindowsLinux (x64)
Windows PowerShell 5.1 (download WMF 5.1). PowerShell Core isn't supported.Linux Hardening must not be enabled. 
.NET Framework 4.6.2 or later. 

Package requirements for Linux

Required packageDescriptionMinimum version
GlibcGNU C Library2.5-12
OpensslOpenSSL Libraries1.0 (TLS 1.1 and TLS 1.2 are supported)
CurlcURL web client7.15.5
Python-ctypesForeign function library for PythonPython 2.x or Python 3.x are required
PAMPluggable Authentication Modules
Optional packageDescriptionMinimum version
PowerShell CoreTo run PowerShell runbooks, PowerShell Core needs to be installed. For instructions, see Installing PowerShell Core on Linux6.0.0

Permissions for Hybrid Worker credentials

If agent-based Hybrid Worker is using custom Hybrid Worker credentials, then ensure that following permissions are assigned to the custom user to avoid jobs from getting suspended on the extension-based Hybrid Worker.

Resource typeFolder permissions
Azure VMC:\Packages\Plugins\Microsoft.Azure.Automation.HybridWorker.HybridWorkerForWindows (read and execute)
Arc-enabled ServerC:\ProgramData\AzureConnectedMachineAgent\Tokens (read) C:\Packages\Plugins\Microsoft.Azure.Automation.HybridWorker.HybridWorkerForWindows (read and execute)


Hybrid Runbook Worker is currently not supported for Virtual Machine Scale Sets (VMSS).

Migrate an existing Agent based Hybrid Worker to Extension based Hybrid Worker

To utilize the benefits of extension based Hybrid Workers, you must migrate all existing agent based User Hybrid Workers to extension based Workers. A hybrid worker machine can co-exist on both Agent based (V1) and Extension based (V2) platforms. The extension based installation doesn't affect the installation or management of an agent based Worker.

To install Hybrid worker extension on an existing agent based hybrid worker, follow these steps:

(Video) Azure Automation Hybrid Worker Setup and RunAs Account

  1. Under Process Automation, select Hybrid worker groups, and then select your existing hybrid worker group to go to the Hybrid worker group page.

  2. Under Hybrid worker group, select Hybrid Workers > + Add to go to the Add machines as hybrid worker page.

  3. Select the checkbox next to the existing Agent based (V1) Hybrid worker. If you don't see your agent-based Hybrid Worker listed, ensure Azure Arc Connected Machine agent is installed on the machine. To install the AzureConnectedMachineAgent, see Connect hybrid machines to Azure from the Azure portal for Arc-enabled servers, or see Manage VMware virtual machines Azure Arc to enable guest management for Arc-enabled VMware vSphere VMs.

  4. Select Add to append the machine to the group.

    The Platform column shows the same Hybrid worker as both Agent based (V1) and Extension based (V2). After you're confident of the extension based Hybrid Worker experience and use, you can remove the agent based Worker.

    (Video) Azure Automation Hybrid Workers with PowerShell Remoting and Credential Resources

For at-scale migration of multiple Agent based Hybrid Workers, you can also use other channels such as - Bicep, ARM templates, PowerShell cmdlets, REST API, and Azure CLI.

Manage Hybrid Worker extension using Bicep & ARM templates, REST API, Azure CLI, and PowerShell

  • Bicep template
  • ARM template
  • Azure CLI
  • PowerShell

You can use the Bicep template to create a new Hybrid Worker group, create a new Azure Windows VM and add it to an existing Hybrid Worker Group. Learn more about Bicep

param automationAccount stringparam automationAccountLocation stringparam workerGroupName string@description('Name of the virtual machine.')param virtualMachineName string@description('Username for the Virtual Machine.')param adminUsername string@description('Password for the Virtual Machine.')@minLength(12)@secure()param adminPassword string@description('Location for the VM.')param vmLocation string = 'North Central US'@description('Size of the virtual machine.')param vmSize string = 'Standard_DS1_v2'@description('The Windows version for the VM. This will pick a fully patched image of this given Windows version.')@allowed([ '2008-R2-SP1' '2012-Datacenter' '2012-R2-Datacenter' '2016-Nano-Server' '2016-Datacenter-with-Containers' '2016-Datacenter' '2019-Datacenter' '2019-Datacenter-Core' '2019-Datacenter-Core-smalldisk' '2019-Datacenter-Core-with-Containers' '2019-Datacenter-Core-with-Containers-smalldisk' '2019-Datacenter-smalldisk' '2019-Datacenter-with-Containers' '2019-Datacenter-with-Containers-smalldisk'])param osVersion string = '2019-Datacenter'@description('DNS name for the public IP')param dnsNameForPublicIP stringvar nicName_var = 'myVMNict'var addressPrefix = ''var subnetName = 'Subnet'var subnetPrefix = ''var subnetRef = resourceId('Microsoft.Network/virtualNetworks/subnets', virtualNetworkName_var, subnetName)var vmName_var = virtualMachineNamevar virtualNetworkName_var = 'MyVNETt'var publicIPAddressName_var = 'myPublicIPt'var networkSecurityGroupName_var = 'default-NSGt'var UniqueStringBasedOnTimeStamp = uniqueString(resourceGroup().id)resource publicIPAddressName 'Microsoft.Network/publicIPAddresses@2020-08-01' = { name: publicIPAddressName_var location: vmLocation properties: { publicIPAllocationMethod: 'Dynamic' dnsSettings: { domainNameLabel: dnsNameForPublicIP } }}resource networkSecurityGroupName 'Microsoft.Network/networkSecurityGroups@2020-08-01' = { name: networkSecurityGroupName_var location: vmLocation properties: { securityRules: [ { name: 'default-allow-3389' properties: { priority: 1000 access: 'Allow' direction: 'Inbound' destinationPortRange: '3389' protocol: 'Tcp' sourceAddressPrefix: '*' sourcePortRange: '*' destinationAddressPrefix: '*' } } ] }}resource virtualNetworkName 'Microsoft.Network/virtualNetworks@2020-08-01' = { name: virtualNetworkName_var location: vmLocation properties: { addressSpace: { addressPrefixes: [ addressPrefix ] } subnets: [ { name: subnetName properties: { addressPrefix: subnetPrefix networkSecurityGroup: { id: networkSecurityGroupName.id } } } ] }}resource nicName 'Microsoft.Network/networkInterfaces@2020-08-01' = { name: nicName_var location: vmLocation properties: { ipConfigurations: [ { name: 'ipconfig1' properties: { privateIPAllocationMethod: 'Dynamic' publicIPAddress: { id: publicIPAddressName.id } subnet: { id: subnetRef } } } ] } dependsOn: [ virtualNetworkName ]}resource vmName 'Microsoft.Compute/virtualMachines@2020-12-01' = { name: vmName_var location: vmLocation identity: { type: 'SystemAssigned' } properties: { hardwareProfile: { vmSize: vmSize } osProfile: { computerName: vmName_var adminUsername: adminUsername adminPassword: adminPassword } storageProfile: { imageReference: { publisher: 'MicrosoftWindowsServer' offer: 'WindowsServer' sku: osVersion version: 'latest' } osDisk: { createOption: 'FromImage' } } networkProfile: { networkInterfaces: [ { id: nicName.id } ] } }}resource automationAccount_resource 'Microsoft.Automation/automationAccounts@2021-06-22' = { name: automationAccount location: automationAccountLocation properties: { sku: { name: 'Basic' } }}resource automationAccount_workerGroupName 'Microsoft.Automation/automationAccounts/hybridRunbookWorkerGroups@2022-02-22' = { parent: automationAccount_resource name: workerGroupName dependsOn: [ vmName ]}resource automationAccount_workerGroupName_testhw_UniqueStringBasedOnTimeStamp 'Microsoft.Automation/automationAccounts/hybridRunbookWorkerGroups/hybridRunbookWorkers@2021-06-22' = { parent: automationAccount_workerGroupName name: guid('testhw', UniqueStringBasedOnTimeStamp) properties: { vmResourceId: resourceId('Microsoft.Compute/virtualMachines', virtualMachineName) } dependsOn: [ vmName ]}resource virtualMachineName_HybridWorkerExtension 'Microsoft.Compute/virtualMachines/extensions@2022-03-01' = { name: '${virtualMachineName}/HybridWorkerExtension' location: vmLocation properties: { publisher: 'Microsoft.Azure.Automation.HybridWorker' type: 'HybridWorkerForWindows' typeHandlerVersion: '1.1' autoUpgradeMinorVersion: true enableAutomaticUpgrade: true settings: { AutomationAccountURL: automationAccount_resource.properties.automationHybridServiceUrl } } dependsOn: [ vmName ]}output output1 string = automationAccount_resource.properties.automationHybridServiceUrl

Remove agent-based Hybrid Worker

  • Windows Hybrid Worker
  • Linux Hybrid Worker
  1. In the Azure portal, go to your Automation account.

  2. Under Account Settings, select Keys and note the values for URL and Primary Access Key.

  3. Open a PowerShell session in Administrator mode and run the following command with your URL and primary access key values. Use the Verbose parameter for a detailed log of the removal process. To remove stale machines from your Hybrid Worker group, use the optional machineName parameter.

    (Video) Run PowerShell Scripts with Azure Automation Hybrid Workers on-premises using Azure Arc

Remove-HybridRunbookWorker -Url <URL> -Key <primaryAccessKey> -MachineName <computerName>


  • After you disable the Private Link in your Automation account, it might take up to 60 minutes to remove the Hybrid Runbook worker.
  • After you remove the Hybrid Worker, the Hybrid Worker authentication certificate on the machine is valid for 45 minutes.

Next steps

  • To learn more about Hybrid Runbook Worker, see Automation Hybrid Runbook Worker overview.
  • To deploy Extension-based Hybrid Worker, see Deploy an extension-based Windows or Linux User Hybrid Runbook Worker in Azure Automation.
  • To learn about Azure VM extensions, see Azure VM extensions and features for Windows and Azure VM extensions and features for Linux.


1. Azure Automation - Hybrid Workers
2. Start Azure Automation Runbooks with Webhooks
(Travis Roberts)
3. Introduction to Azure Automation
(Travis Roberts)
4. Azure Automation | Azure Automation Tutorial | Learn Azure Automation
(Alpha Tutorials - Admin)
5. Azure Automation - Run-As Account vs Managed Identity
(Shailender Choudhary)
6. Azure Automation Runbooks & State Configuration
Top Articles
Latest Posts
Article information

Author: Kelle Weber

Last Updated: 03/15/2023

Views: 5931

Rating: 4.2 / 5 (73 voted)

Reviews: 80% of readers found this page helpful

Author information

Name: Kelle Weber

Birthday: 2000-08-05

Address: 6796 Juan Square, Markfort, MN 58988

Phone: +8215934114615

Job: Hospitality Director

Hobby: tabletop games, Foreign language learning, Leather crafting, Horseback riding, Swimming, Knapping, Handball

Introduction: My name is Kelle Weber, I am a magnificent, enchanting, fair, joyous, light, determined, joyous person who loves writing and wants to share my knowledge and understanding with you.