Skip to content

Commit 57181cd

Browse files
prmerger-automator[bot]prmerger-automator[bot]
authored
Merge pull request #298533 from SnehaSudhirG/21Apr-HRWUpdate
Inputs incorporated
2 parents bae7b8c + 25dbd45 commit 57181cd

File tree

1 file changed

+117
-85
lines changed

1 file changed

+117
-85
lines changed

‎articles/automation/extension-based-hybrid-runbook-worker-install.md

Lines changed: 117 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: This article provides information about deploying the extension-bas
44
services: automation
55
ms.subservice: process-automation
66
ms.custom: devx-track-azurepowershell, devx-track-azurecli, devx-track-bicep, linux-related-content
7-
ms.date: 04/07/2025
7+
ms.date: 04/22/2025
88
ms.topic: how-to
99
#Customer intent: As a developer, I want to learn about extension so that I can efficiently deploy Hybrid Runbook Workers.
1010
ms.service: azure-automation
@@ -80,7 +80,28 @@ If extension-based Hybrid Worker is using custom Hybrid Worker credentials, then
8080
> - When a system has UAC/LUA in place, permissions must be granted directly and not through any group membership. [Learn more](troubleshoot/extension-based-hybrid-runbook-worker.md#scenario-runbooks-go-into-a-suspended-state-on-a-hybrid-runbook-worker-when-using-a-custom-account-on-a-server-with-user-account-control-uac-enabled).
8181
> - Due to a current limitation, these folder permissions are removed from the C:\ProgramData\AzureConnectedMachineAgent\Tokens folder on Azure Arc-enabled machines when the Azure Connected Machine agent is updated. The current resolution is to reapply these permissions to the folder. [Learn more](troubleshoot/extension-based-hybrid-runbook-worker.md#scenario-hybrid-runbook-worker-job-execution-on-azure-arc-enabled-windows-server-that-uses-a-custom-credential-is-unexpectedly-suspended).
8282
83+
## Automation account hybrid service url
8384

85+
You must retrieve and use the AutomationHybridServiceURL to deploy the Hybrid Worker extension to the VM/Arc machine.
86+
87+
> [!NOTE]
88+
> The necessary URL is the automationHybridServiceUrl, NOT the RegistrationUrl.
89+
90+
There are multiple ways to retrieve the value for AutomationHybridServiceUrl:
91+
92+
- Copy it from the **Azure portal**, **Automation Account**, **Properties**, **Automation hybrid service URL**.
93+
94+
Or
95+
96+
- Copy it from the **Azure portal**, **Automation Account**, **Overview**, **JSON** view. </br> Select the latest API version, otherwise AutomationHybridServiceUrl might not be displayed.
97+
98+
Or
99+
- The below REST API call:
100+
101+
```rest
102+
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}?api-version=2023-11-01
103+
104+
```
84105

85106
## Network requirements
86107

@@ -96,21 +117,19 @@ If you use a proxy server for communication between Azure Automation and machine
96117
1. Get the automation account details using the below API call.
97118

98119
```http
99-
GET https://westcentralus.management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}?api-version=2021-06-22
120+
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}?api-version=2023-11-01
100121
101122
```
102123

103124
The API call will provide the value with the key: `AutomationHybridServiceUrl`. Use the URL in the next step to enable extension on the VM.
104125

105126
1. Install the Hybrid Worker Extension on the VM by running the following PowerShell cmdlet (Required module: Az.Compute). Use the `properties.automationHybridServiceUrl` provided by the above API call
106-
107127

108-
**Proxy server settings**
109128
# [Windows](#tab/windows)
110129

111130
```azurepowershell-interactive
112131
$settings = @{
113-
"AutomationAccountURL" = "<registrationurl>";
132+
"AutomationAccountURL" = "<automationHybridServiceUrl>";
114133
"ProxySettings" = @{
115134
"ProxyServer" = "<ipaddress>:<port>";
116135
"UserName"="test";
@@ -139,7 +158,7 @@ $protectedsettings = @{
139158
"Proxy_URL"="http://username:password@<IP Address>"
140159
};
141160
$settings = @{
142-
"AutomationAccountURL" = "<registration-url>";
161+
"AutomationAccountURL" = "<automationHybridServiceUrl>";
143162
};
144163
```
145164
**Azure VMs**
@@ -153,7 +172,6 @@ Set-AzVMExtension -ResourceGroupName <VMResourceGroupName> -Location <VMLocation
153172
```powershell
154173
New-AzConnectedMachineExtension -ResourceGroupName <VMResourceGroupName> -Location <VMLocation> -MachineName <VMName> -Name "HybridWorkerExtension" -Publisher "Microsoft.Azure.Automation.HybridWorker" -ExtensionType HybridWorkerForLinux -TypeHandlerVersion 1.1 -Setting $settings -ProtectedSetting $protectedsettings -NoWait -EnableAutomaticUpgrade
155174
```
156-
157175
---
158176

159177
### Firewall use
@@ -313,6 +331,97 @@ New-AzConnectedMachineExtension -ResourceGroupName <VMResourceGroupName> -Locati
313331

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

334+
#### [PowerShell](#tab/ps)
335+
336+
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.
337+
338+
Follow the steps mentioned below as an example:
339+
340+
1. Create a Hybrid Worker Group.
341+
342+
```powershell-interactive
343+
New-AzAutomationHybridRunbookWorkerGroup -AutomationAccountName "Contoso17" -Name "RunbookWorkerGroupName" -ResourceGroupName "ResourceGroup01"
344+
```
345+
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 the name of the Hybrid Worker. To fetch `vmResourceId`, go to the **Properties** tab of the VM on Azure portal.
346+
347+
```azurepowershell
348+
#To fetch vmResourceId, go to the Properties tab of the VM on Azure portal.
349+
$hwVM = "VmResourceId"
350+
351+
# Generate a new GUID and pass it as the name of the Hybrid Worker
352+
$hwguid = New-Guid
353+
354+
# Create the Hybrid Worker
355+
New-AzAutomationHybridRunbookWorker `
356+
-Name $hwguid `
357+
-VmResourceId $hwVM `
358+
-HybridRunbookWorkerGroupName "RunbookWorkerGroupName" `
359+
-AutomationAccountName "Contoso17" `
360+
-ResourceGroupName "AutomationAccountResourceGroup01"
361+
```
362+
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.
363+
364+
1. Install Hybrid Worker Extension on the VM.
365+
366+
> [!NOTE]
367+
> If you want to add proxy server see [proxy server use](#proxy-server-use).
368+
369+
370+
```powershell-interactive
371+
$settings = @{
372+
"AutomationAccountURL" = "<automationHybridServiceUrl>";
373+
};
374+
```
375+
376+
**Azure VMs**
377+
378+
```powershell
379+
Set-AzVMExtension -ResourceGroupName <VMResourceGroupName> -Location <VMLocation> -VMName <VMName> -Name "HybridWorkerExtension" -Publisher "Microsoft.Azure.Automation.HybridWorker" -ExtensionType HybridWorkerForWindows -TypeHandlerVersion 1.1 -Settings $settings -EnableAutomaticUpgrade $true/$false
380+
```
381+
**Azure Arc-enabled VMs**
382+
383+
```powershell
384+
New-AzConnectedMachineExtension -ResourceGroupName <VMResourceGroupName> -Location <VMLocation> -MachineName <VMName> -Name "HybridWorkerExtension" -Publisher "Microsoft.Azure.Automation.HybridWorker" -ExtensionType HybridWorkerForWindows -TypeHandlerVersion 1.1 -Setting $settings -NoWait -EnableAutomaticUpgrade
385+
```
386+
387+
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.
388+
389+
390+
**Manage Hybrid Worker Extension**
391+
392+
You can use the following PowerShell cmdlets to manage Hybrid Runbook Worker and Hybrid Runbook Worker groups:
393+
394+
| PowerShell cmdlet | Description |
395+
| ----- | ----------- |
396+
|[`Get-AzAutomationHybridRunbookWorkerGroup`](/powershell/module/az.automation/get-azautomationhybridrunbookworkergroup) | Gets Hybrid Runbook Worker group|
397+
|[`Remove-AzAutomationHybridRunbookWorkerGroup`](/powershell/module/az.automation/remove-azautomationhybridrunbookworkergroup) | Removes Hybrid Runbook Worker group|
398+
|[`Set-AzAutomationHybridRunbookWorkerGroup`](/powershell/module/az.automation/set-azautomationhybridrunbookworkergroup) | Updates Hybrid Worker group with Hybrid Worker credentials|
399+
|[`New-AzAutomationHybridRunbookWorkerGroup`](/powershell/module/az.automation/new-azautomationhybridrunbookworkergroup) | Creates new Hybrid Runbook Worker group|
400+
|[`Get-AzAutomationHybridRunbookWorker`](/powershell/module/az.automation/get-azautomationhybridrunbookworker) | Gets Hybrid Runbook Worker|
401+
|[`Move-AzAutomationHybridRunbookWorker`](/powershell/module/az.automation/move-azautomationhybridrunbookworker) | Moves Hybrid Worker from one group to other|
402+
|[`New-AzAutomationHybridRunbookWorker`](/powershell/module/az.automation/new-azautomationhybridrunbookworker) | Creates new Hybrid Runbook Worker|
403+
|[`Remove-AzAutomationHybridRunbookWorker`](/powershell/module/az.automation/remove-azautomationhybridrunbookworker)| Removes Hybrid Runbook Worker|
404+
405+
After creating new Hybrid Runbook Worker, you must install the extension on the Hybrid Worker.
406+
407+
**Hybrid Worker extension settings**
408+
409+
```powershell-interactive
410+
$settings = @{
411+
"AutomationAccountURL" = "<automationHybridServiceUrl>";
412+
};
413+
```
414+
**Azure VMs**
415+
416+
```powershell
417+
Set-AzVMExtension -ResourceGroupName <VMResourceGroupName> -Location <VMLocation> -VMName <VMName> -Name "HybridWorkerExtension" -Publisher "Microsoft.Azure.Automation.HybridWorker" -ExtensionType HybridWorkerForWindows -TypeHandlerVersion 1.1 -Settings $settings -EnableAutomaticUpgrade $true/$false
418+
```
419+
**Azure Arc-enabled VMs**
420+
421+
```powershell
422+
New-AzConnectedMachineExtension -ResourceGroupName <VMResourceGroupName> -Location <VMLocation> -MachineName <VMName> -Name "HybridWorkerExtension" -Publisher "Microsoft.Azure.Automation.HybridWorker" -ExtensionType HybridWorkerForWindows -TypeHandlerVersion 1.1 -Setting $settings -NoWait -EnableAutomaticUpgrade
423+
```
424+
316425
#### [Bicep template](#tab/bicep-template)
317426

318427
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](../azure-resource-manager/bicep/overview.md).
@@ -1012,7 +1121,7 @@ Follow the steps mentioned below as an example:
10121121

10131122
```azurecli-interactive
10141123
az vm extension set --name HybridWorkerExtension --publisher Microsoft.Azure.Automation.HybridWorker --version 1.1 --vm-name <vmname> -g <resourceGroupName> \
1015-
--settings '{"AutomationAccountURL" = "<registration-url>";}' --enable-auto-upgrade true
1124+
--settings '{"AutomationAccountURL" = "<automationHybridServiceUrl>";}' --enable-auto-upgrade true
10161125
```
10171126
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.
10181127

@@ -1023,83 +1132,6 @@ Follow the steps mentioned below as an example:
10231132

10241133
After creating new Hybrid Runbook Worker, you must install the extension on the Hybrid Worker using [az vm extension set](/cli/azure/vm/extension#az-vm-extension-set).
10251134

1026-
1027-
#### [PowerShell](#tab/ps)
1028-
1029-
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.
1030-
1031-
Follow the steps mentioned below as an example:
1032-
1033-
1. Create a Hybrid Worker Group.
1034-
1035-
```powershell-interactive
1036-
New-AzAutomationHybridRunbookWorkerGroup -AutomationAccountName "Contoso17" -Name "RunbookWorkerGroupName" -ResourceGroupName "ResourceGroup01"
1037-
```
1038-
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 the name of the Hybrid Worker. To fetch `vmResourceId`, go to the **Properties** tab of the VM on Azure portal.
1039-
1040-
```azurepowershell
1041-
New-AzAutomationHybridRunbookWorker -AutomationAccountName "Contoso17" -Name "RunbookWorkerName" -HybridRunbookWorkerGroupName "RunbookWorkerGroupName" -VmResourceId "VmResourceId" -ResourceGroupName "ResourceGroup01"
1042-
```
1043-
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.
1044-
1045-
1. Install Hybrid Worker Extension on the VM.
1046-
1047-
**Hybrid Worker extension settings**
1048-
1049-
```powershell-interactive
1050-
$settings = @{
1051-
"AutomationAccountURL" = "<registrationurl>";
1052-
};
1053-
```
1054-
1055-
**Azure VMs**
1056-
1057-
```powershell
1058-
Set-AzVMExtension -ResourceGroupName <VMResourceGroupName> -Location <VMLocation> -VMName <VMName> -Name "HybridWorkerExtension" -Publisher "Microsoft.Azure.Automation.HybridWorker" -ExtensionType HybridWorkerForWindows -TypeHandlerVersion 1.1 -Settings $settings -EnableAutomaticUpgrade $true/$false
1059-
```
1060-
**Azure Arc-enabled VMs**
1061-
1062-
```powershell
1063-
New-AzConnectedMachineExtension -ResourceGroupName <VMResourceGroupName> -Location <VMLocation> -MachineName <VMName> -Name "HybridWorkerExtension" -Publisher "Microsoft.Azure.Automation.HybridWorker" -ExtensionType HybridWorkerForWindows -TypeHandlerVersion 1.1 -Setting $settings -NoWait -EnableAutomaticUpgrade
1064-
```
1065-
1066-
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.
1067-
1068-
1069-
**Manage Hybrid Worker Extension**
1070-
1071-
You can use the following PowerShell cmdlets to manage Hybrid Runbook Worker and Hybrid Runbook Worker groups:
1072-
1073-
| PowerShell cmdlet | Description |
1074-
| ----- | ----------- |
1075-
|[`Get-AzAutomationHybridRunbookWorkerGroup`](/powershell/module/az.automation/get-azautomationhybridrunbookworkergroup) | Gets Hybrid Runbook Worker group|
1076-
|[`Remove-AzAutomationHybridRunbookWorkerGroup`](/powershell/module/az.automation/remove-azautomationhybridrunbookworkergroup) | Removes Hybrid Runbook Worker group|
1077-
|[`Set-AzAutomationHybridRunbookWorkerGroup`](/powershell/module/az.automation/set-azautomationhybridrunbookworkergroup) | Updates Hybrid Worker group with Hybrid Worker credentials|
1078-
|[`New-AzAutomationHybridRunbookWorkerGroup`](/powershell/module/az.automation/new-azautomationhybridrunbookworkergroup) | Creates new Hybrid Runbook Worker group|
1079-
|[`Get-AzAutomationHybridRunbookWorker`](/powershell/module/az.automation/get-azautomationhybridrunbookworker) | Gets Hybrid Runbook Worker|
1080-
|[`Move-AzAutomationHybridRunbookWorker`](/powershell/module/az.automation/move-azautomationhybridrunbookworker) | Moves Hybrid Worker from one group to other|
1081-
|[`New-AzAutomationHybridRunbookWorker`](/powershell/module/az.automation/new-azautomationhybridrunbookworker) | Creates new Hybrid Runbook Worker|
1082-
|[`Remove-AzAutomationHybridRunbookWorker`](/powershell/module/az.automation/remove-azautomationhybridrunbookworker)| Removes Hybrid Runbook Worker|
1083-
1084-
After creating new Hybrid Runbook Worker, you must install the extension on the Hybrid Worker.
1085-
1086-
**Hybrid Worker extension settings**
1087-
1088-
```powershell-interactive
1089-
$settings = @{
1090-
"AutomationAccountURL" = "<registrationurl>";
1091-
};
1092-
```
1093-
**Azure VMs**
1094-
1095-
```powershell
1096-
Set-AzVMExtension -ResourceGroupName <VMResourceGroupName> -Location <VMLocation> -VMName <VMName> -Name "HybridWorkerExtension" -Publisher "Microsoft.Azure.Automation.HybridWorker" -ExtensionType HybridWorkerForWindows -TypeHandlerVersion 1.1 -Settings $settings -EnableAutomaticUpgrade $true/$false
1097-
```
1098-
**Azure Arc-enabled VMs**
1099-
1100-
```powershell
1101-
New-AzConnectedMachineExtension -ResourceGroupName <VMResourceGroupName> -Location <VMLocation> -MachineName <VMName> -Name "HybridWorkerExtension" -Publisher "Microsoft.Azure.Automation.HybridWorker" -ExtensionType HybridWorkerForWindows -TypeHandlerVersion 1.1 -Setting $settings -NoWait -EnableAutomaticUpgrade
1102-
```
11031135
---
11041136

11051137
## Manage Role permissions for Hybrid Worker Groups and Hybrid Workers

0 commit comments

Comments
 (0)