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 demonstrates a Windows bias in several ways: Windows examples and tools (such as PowerShell and Windows-specific registry paths) are presented first or exclusively in key sections, especially in the Bicep and ARM template examples, which only show Windows VM creation and extension installation. PowerShell is heavily featured, while Linux command-line or scripting examples are minimal or absent for core tasks. Some operational steps (like folder permissions and extension installation) reference only Windows paths or tools, and Linux equivalents are either missing or less detailed.
Recommendations:
- Provide parallel Linux examples for all automation, scripting, and deployment scenarios (e.g., show how to deploy the Hybrid Worker extension to a Linux VM using Bicep/ARM templates, Azure CLI, REST API, and PowerShell).
- In code samples and step-by-step instructions, present both Windows and Linux paths, commands, and configuration details side-by-side or in clearly separated tabs.
- Include Linux-specific operational guidance, such as required folder permissions, service management, and troubleshooting steps, matching the detail provided for Windows.
- When listing tools or onboarding channels (e.g., PowerShell, Azure CLI), ensure Linux-friendly tools and workflows are given equal prominence and detail.
- Avoid presenting Windows instructions or tools before Linux equivalents unless there is a technical reason; strive for parity in ordering and depth.
- Expand the 'Remove agent-based Hybrid Worker' and other operational sections to provide more comprehensive Linux removal and cleanup steps, including agent uninstallation and configuration file cleanup.
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
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
---
## Remove agent-based Hybrid Worker
#### [Windows Hybrid Worker](#tab/win-hrw)
1. Open PowerShell session in Administrator mode and run the following command:
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. To confirm if the extension has been successfully installed on the VM, in **Azure portal**, go to the VM > **Extensions** tab and check the status of the Hybrid Worker extension installed on the VM.
**Manage Hybrid Worker Extension**
- To create, delete, and manage extension-based Hybrid Runbook Worker groups, see [az automation hrwg | Microsoft Docs](/cli/azure/automation/hrwg?view=azure-cli-latest&preserve-view=true)
- To create, delete, and manage extension-based Hybrid Runbook Worker, see [az automation hrwg hrw | Microsoft Docs](/cli/azure/automation/hrwg/hrw?view=azure-cli-latest&preserve-view=true)
After creating new Hybrid Runbook Worker, you must install the extension on the Hybrid Worker using [az vm extension set](/cli/azure/vm/extension?view=azure-cli-latest#az-vm-extension-set&preserve-view=true).
#### [PowerShell](#tab/ps)
You can use PowerShell cmdlets to create a new Hybrid Worker group, create a new Azure VM, add it to an existing Hybrid Worker Group and install the Hybrid Worker extension.
Follow the steps mentioned below as an example:
1. Create a Hybrid Worker Group.
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. To confirm if the extension has been successfully installed on the VM, In **Azure portal**, go to the VM > **Extensions** tab and check the status of Hybrid Worker extension installed on the VM.
**Manage Hybrid Worker Extension**
You can use the following PowerShell cmdlets to manage Hybrid Runbook Worker and Hybrid Runbook Worker groups:
| PowerShell cmdlet | Description |
| ----- | ----------- |
|[`Get-AzAutomationHybridRunbookWorkerGroup`](/powershell/module/az.automation/get-azautomationhybridrunbookworkergroup) | Gets Hybrid Runbook Worker group|
|[`Remove-AzAutomationHybridRunbookWorkerGroup`](/powershell/module/az.automation/remove-azautomationhybridrunbookworkergroup) | Removes Hybrid Runbook Worker group|
|[`Set-AzAutomationHybridRunbookWorkerGroup`](/powershell/module/az.automation/set-azautomationhybridrunbookworkergroup) | Updates Hybrid Worker group with Hybrid Worker credentials|
|[`New-AzAutomationHybridRunbookWorkerGroup`](/powershell/module/az.automation/new-azautomationhybridrunbookworkergroup) | Creates new Hybrid Runbook Worker group|
|[`Get-AzAutomationHybridRunbookWorker`](/powershell/module/az.automation/get-azautomationhybridrunbookworker) | Gets Hybrid Runbook Worker|
|[`Move-AzAutomationHybridRunbookWorker`](/powershell/module/az.automation/move-azautomationhybridrunbookworker) | Moves Hybrid Worker from one group to other|
|[`New-AzAutomationHybridRunbookWorker`](/powershell/module/az.automation/new-azautomationhybridrunbookworker) | Creates new Hybrid Runbook Worker|
|[`Remove-AzAutomationHybridRunbookWorker`](/powershell/module/az.automation/remove-azautomationhybridrunbookworker)| Removes Hybrid Runbook Worker|
After creating new Hybrid Runbook Worker, you must install the extension on the Hybrid Worker.
**Azure VMs**
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]"
}
}
}
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