Document Details
Migrate Existing Agent Based Hybrid Worker To Extension Based Workers
❌
This page contains Windows bias
About This Page
This page is part of the Azure documentation. It contains code examples and configuration instructions for working with Azure services.
Bias Analysis
Bias Types:
⚠️
windows_first
⚠️
missing_linux_example
⚠️
powershell_heavy
⚠️
windows_tools
Summary:
The documentation exhibits a Windows bias in several ways: (1) Windows-specific examples and tools (e.g., PowerShell, Windows registry paths) are provided first or exclusively in key sections, especially in the Bicep, ARM template, PowerShell, and removal instructions. (2) There is a lack of equivalent Linux-focused examples for core automation scenarios (e.g., Bicep/ARM templates and PowerShell/CLI commands are tailored to Windows VMs and extensions, with no Linux VM or extension examples). (3) PowerShell is heavily featured, with less emphasis on bash or Linux-native scripting. (4) Windows-specific requirements and tools (e.g., .NET Framework, Windows PowerShell 5.1) are highlighted, while Linux requirements are less detailed or are presented as secondary.
Recommendations:
- Provide Linux-specific examples alongside Windows examples for Bicep, ARM templates, REST API, Azure CLI, and PowerShell sections. For instance, show how to deploy a Linux VM and install the HybridWorkerForLinux extension.
- Ensure that Linux commands and requirements are given equal prominence and detail as Windows, including bash scripts and Linux-native automation tools.
- When listing prerequisites, present Windows and Linux requirements in parallel, and avoid listing Windows first by default.
- For PowerShell-heavy sections, provide equivalent bash or shell script examples for Linux users.
- Clarify when a step or tool is Windows-only, and always provide the Linux alternative immediately after or in a side-by-side format.
- In code samples and parameter tables, include Linux OS options and extension types (e.g., HybridWorkerForLinux) wherever Windows options are shown.
- Expand the removal instructions for Linux to include cleanup of all related components, matching the detail provided for Windows.
Create pull request
Scan History
| Date | Scan ID | Status | Bias Status |
|---|---|---|---|
| 2025-08-17 00:01 | #83 | in_progress | ✅ Clean |
| 2025-07-13 21:37 | #48 | completed | ❌ Biased |
| 2025-07-09 13:09 | #3 | cancelled | ✅ Clean |
| 2025-07-08 04:23 | #2 | cancelled | ❌ Biased |
Flagged Code Snippets
1. Create an Azure VM or Arc-enabled server and add it to the above created Hybrid Worker Group. Use the below command to add an existing Azure VM or Arc-enabled Server to the Hybrid Worker Group. Generate a new GUID and pass it as `hybridRunbookWorkerGroupName`. To fetch `vmResourceId`, go to the **Properties** tab of the VM on Azure portal.
1. Under **Process Automation**, select **Hybrid worker groups** and then your hybrid worker group to go to the **Hybrid Worker Group** page.
1. Under **Hybrid worker group**, select **Hybrid Workers**.
1. Select the checkbox next to the machine(s) you want to delete from the hybrid worker group.
1. Select **Delete** to remove the agent-based Windows Hybrid Worker.
> [!NOTE]
> - 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.
#### [Linux Hybrid Worker](#tab/lin-hrw)
1. Run the following commands on agent-based Linux Hybrid Worker:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"automationAccount": {
"type": "string"
},
"automationAccountLocation": {
"type": "string"
},
"workerGroupName": {
"type": "string"
},
"virtualMachineName": {
"type": "string",
"metadata": {
"description": "Name of the virtual machine."
}
},
"adminUsername": {
"type": "string",
"metadata": {
"description": "Username for the Virtual Machine."
}
},
"adminPassword": {
"type": "securestring",
"minLength": 12,
"metadata": {
"description": "Password for the Virtual Machine."
}
},
"vmLocation": {
"type": "string",
"defaultValue": "North Central US",
"metadata": {
"description": "Location for the VM."
}
},
"vmSize": {
"type": "string",
"defaultValue": "Standard_DS1_v2",
"metadata": {
"description": "Size of the virtual machine."
}
},
"osVersion": {
"type": "string",
"defaultValue": "2019-Datacenter",
"allowedValues": [
"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"
],
"metadata": {
"description": "The Windows version for the VM. This will pick a fully patched image of this given Windows version."
}
},
"dnsNameForPublicIP": {
"type": "string",
"metadata": {
"description": "DNS name for the public IP"
}
},
"_CurrentDateTimeInTicks": {
"type": "string",
"defaultValue": "[utcNow('yyyy-MM-dd')]"
}
},
"variables": {
"nicName": "myVMNict",
"addressPrefix": "10.0.0.0/16",
"subnetName": "Subnet",
"subnetPrefix": "10.0.0.0/24",
"subnetRef": "[resourceId('Microsoft.Network/virtualNetworks/subnets', variables('virtualNetworkName'), variables('subnetName'))]",
"vmName": "[parameters('virtualMachineName')]",
"virtualNetworkName": "MyVNETt",
"publicIPAddressName": "myPublicIPt",
"networkSecurityGroupName": "default-NSGt",
"UniqueStringBasedOnTimeStamp": "[uniqueString(deployment().name, parameters('_CurrentDateTimeInTicks'))]"
},
"resources": [
{
"apiVersion": "2020-08-01",
"type": "Microsoft.Network/publicIPAddresses",
"name": "[variables('publicIPAddressName')]",
"location": "[parameters('vmLocation')]",
"properties": {
"publicIPAllocationMethod": "Dynamic",
"dnsSettings": {
"domainNameLabel": "[parameters('dnsNameForPublicIP')]"
}
}
},
{
"comments": "Default Network Security Group for template",
"type": "Microsoft.Network/networkSecurityGroups",
"apiVersion": "2020-08-01",
"name": "[variables('networkSecurityGroupName')]",
"location": "[parameters('vmLocation')]",
"properties": {
"securityRules": [
{
"name": "default-allow-3389",
"properties": {
"priority": 1000,
"access": "Allow",
"direction": "Inbound",
"destinationPortRange": "3389",
"protocol": "Tcp",
"sourceAddressPrefix": "*",
"sourcePortRange": "*",
"destinationAddressPrefix": "*"
}
}
]
}
},
{
"apiVersion": "2020-08-01",
"type": "Microsoft.Network/virtualNetworks",
"name": "[variables('virtualNetworkName')]",
"location": "[parameters('vmLocation')]",
"dependsOn": [
"[resourceId('Microsoft.Network/networkSecurityGroups', variables('networkSecurityGroupName'))]"
],
"properties": {
"addressSpace": {
"addressPrefixes": [
"[variables('addressPrefix')]"
]
},
"subnets": [
{
"name": "[variables('subnetName')]",
"properties": {
"addressPrefix": "[variables('subnetPrefix')]",
"networkSecurityGroup": {
"id": "[resourceId('Microsoft.Network/networkSecurityGroups', variables('networkSecurityGroupName'))]"
}
}
}
]
}
},
{
"apiVersion": "2020-08-01",
"type": "Microsoft.Network/networkInterfaces",
"name": "[variables('nicName')]",
"location": "[parameters('vmLocation')]",
"dependsOn": [
"[variables('publicIPAddressName')]",
"[variables('virtualNetworkName')]"
],
"properties": {
"ipConfigurations": [
{
"name": "ipconfig1",
"properties": {
"privateIPAllocationMethod": "Dynamic",
"publicIPAddress": {
"id": "[resourceId('Microsoft.Network/publicIPAddresses',variables('publicIPAddressName'))]"
},
"subnet": {
"id": "[variables('subnetRef')]"
}
}
}
]
}
},
{
"apiVersion": "2020-12-01",
"type": "Microsoft.Compute/virtualMachines",
"name": "[variables('vmName')]",
"location": "[parameters('vmLocation')]",
"dependsOn": [
"[variables('nicName')]"
],
"identity": {
"type": "SystemAssigned"
} ,
"properties": {
"hardwareProfile": {
"vmSize": "[parameters('vmSize')]"
},
"osProfile": {
"computerName": "[variables('vmName')]",
"adminUsername": "[parameters('adminUsername')]",
"adminPassword": "[parameters('adminPassword')]"
},
"storageProfile": {
"imageReference": {
"publisher": "MicrosoftWindowsServer",
"offer": "WindowsServer",
"sku": "[parameters('osVersion')]",
"version": "latest"
},
"osDisk": {
"createOption": "FromImage"
}
},
"networkProfile": {
"networkInterfaces": [
{
"id": "[resourceId('Microsoft.Network/networkInterfaces',variables('nicName'))]"
}
]
}
}
},
{
"type": "Microsoft.Automation/automationAccounts",
"apiVersion": "2021-06-22",
"name": "[parameters('automationAccount')]",
"location": "[parameters('automationAccountLocation')]",
"properties": {
"sku": {
"name": "Basic"
}
},
"resources": [
{
"name": "[parameters('workerGroupName')]",
"type": "hybridRunbookWorkerGroups",
"apiVersion": "2022-02-22",
"dependsOn": [
"[resourceId('Microsoft.Automation/automationAccounts', parameters('automationAccount'))]",
"[resourceId('Microsoft.Compute/virtualMachines', variables('vmName'))]"
],
"resources" : [
{
"name": "[guid('testhw', variables('UniqueStringBasedOnTimeStamp'))]",
"type": "hybridRunbookWorkers",
"apiVersion": "2021-06-22",
"dependsOn": [
"[resourceId('Microsoft.Automation/automationAccounts', parameters('automationAccount'))]",
"[resourceId('Microsoft.Automation/automationAccounts/hybridRunbookWorkerGroups', parameters('automationAccount'),parameters('workerGroupName'))]",
"[resourceId('Microsoft.Compute/virtualMachines', variables('vmName'))]"
],
"properties": {
"vmResourceId": "[resourceId('Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]"
}
}
]
}
]
},
{
"type": "Microsoft.Compute/virtualMachines/extensions",
"name": "[concat(parameters('virtualMachineName'),'/HybridWorkerExtension')]",
"apiVersion": "2022-03-01",
"location": "[parameters('vmLocation')]",
"dependsOn": [
"[resourceId('Microsoft.Automation/automationAccounts', parameters('automationAccount'))]",
"[resourceId('Microsoft.Compute/virtualMachines', parameters('virtualMachineName'))]"
],
"properties": {
"publisher": "Microsoft.Azure.Automation.HybridWorker",
"type": "HybridWorkerForWindows",
"typeHandlerVersion": "1.1",
"autoUpgradeMinorVersion": true,
"enableAutomaticUpgrade": true,
"settings": {
"AutomationAccountURL": "[reference(resourceId('Microsoft.Automation/automationAccounts', parameters('automationAccount'))).AutomationHybridServiceUrl]"
}
}
}
],
"outputs": {
"output1": {
"type": "string",
"value": "[reference(resourceId('Microsoft.Automation/automationAccounts', parameters('automationAccount'))).AutomationHybridServiceUrl]"
}
}
}
param automationAccount string
param automationAccountLocation string
param 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 string
var nicName_var = 'myVMNict'
var addressPrefix = '10.0.0.0/16'
var subnetName = 'Subnet'
var subnetPrefix = '10.0.0.0/24'
var subnetRef = resourceId('Microsoft.Network/virtualNetworks/subnets', virtualNetworkName_var, subnetName)
var vmName_var = virtualMachineName
var 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
1. Follow the steps [here](../active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm.md#enable-system-assigned-managed-identity-on-an-existing-vm) to enable the System-assigned managed identity on the VM.
1. Install Hybrid Worker Extension on the VM.
**Hybrid Worker extension settings**
1. Under **Process Automation**, select **Hybrid worker groups** and then your hybrid worker group to go to the **Hybrid Worker Group** page.
1. Under **Hybrid worker group**, select **Hybrid Workers**.
1. Select the checkbox next to the machine(s) you want to delete from the hybrid worker group.
1. Select **Delete** to remove the agent-based Windows Hybrid Worker.
> [!NOTE]
> - 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.
#### [Linux Hybrid Worker](#tab/lin-hrw)
1. Run the following commands on agent-based Linux Hybrid Worker:
1. Follow the steps [here](../active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm.md#enable-system-assigned-managed-identity-on-an-existing-vm) to enable the System-assigned managed identity on the VM.
1. Install Hybrid Worker Extension on the VM.
**Hybrid Worker extension settings**