Document Details

#### [ARM template](#tab/arm-template)

You can use an Azure Resource Manager (ARM) template to create a new Azure Windows VM and connect it to an existing Automation account and Hybrid Worker Group. To learn more about ARM templates, see [What are ARM templates?](../azure-resource-manager/templates/overview.md)

Follow the steps mentioned below as an example:

1. Create a Hybrid Worker Group.
1. Create either an Azure VM or Arc-enabled server. Alternatively, you can also use an existing Azure VM or Arc-enabled server.
1. Connect the Azure VM or Arc-enabled server to the above created Hybrid Worker Group. 
1. Generate a new GUID and pass it as the name of the Hybrid Worker.
1. Enable System-assigned managed identity on the VM.
1. Install Hybrid Worker Extension on the VM.
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.


**Review the template**

---

### Firewall use

If you use a firewall to restrict access to the Internet, you must configure the firewall to permit access. The following port and URLs are required for the Hybrid Runbook Worker, and for [Automation State Configuration](./automation-dsc-overview.md) to communicate with Azure Automation.

| Property | Description |
| --- | --- |
| Port | 443 for outbound internet access |
| Global URL | *.azure-automation.net |
| Global URL of US Gov Virginia | *.azure-automation.us |

### CPU quota limit

There is a CPU quota limit of 25% while configuring extension-based Linux Hybrid Runbook worker. There is no such limit for Windows Hybrid Runbook Worker.

## Create hybrid worker group

To create a hybrid worker group in the Azure portal, follow these steps:

1. Sign in to the [Azure portal](https://portal.azure.com).

1. Go to your Automation account.

1. Under **Process Automation**, select **Hybrid worker groups**.

1. Select **+ Create hybrid worker group**.

   :::image type="content" source="./media/extension-based-hybrid-runbook-worker-install/hybrid-worker-groups-portal.png" alt-text="Screenshot showing to select hybrid Worker Groups option in portal.":::

1. From the **Basics** tab, in the **Name** text box, enter a name for your Hybrid worker group.

1. For the **Use Hybrid Worker Credentials** option:

   - If you select **Default**, the hybrid extension will be installed using the local system account.
   - If you select **Custom**, then from the drop-down list, select the credential asset.

1. Select **Next** to advance to the **Hybrid workers** tab. You can select Azure virtual machines, Azure Arc-enabled servers,  Azure Arc-enabled VMware vSphere and Arc-enabled SCVMM to be added to this Hybrid worker group. If you don't select any machines, an empty Hybrid worker group will be created. You can still add machines later.

   :::image type="content" source="./media/extension-based-hybrid-runbook-worker-install/basics-tab-portal.png" alt-text="Screenshot showing to enter name and credentials in basics tab.":::

1. Select **Add machines** to go to the **Add machines as hybrid worker** page. You'll only see machines that aren't part of any other hybrid worker group.

1. Select the checkbox next to the machine(s) you want to add to the hybrid worker group. If you don't see your non-Azure machine listed, ensure Azure Arc Connected Machine agent is installed on the machine.

1. Select **Add**.

1. Select **Next** to advance to the **Review + Create** tab.

1. Select **Create**.

    The hybrid worker extension installs on the machine and the hybrid worker gets registered to the hybrid worker group. Adding a hybrid worker to the group happens immediately, while installation of the extension might take a few minutes. Select **Refresh** to see the new group. Select the group name to view the hybrid worker details.

   > [!NOTE]
   > A selected machine won't be added to a hybrid worker group if it is already part of another hybrid worker group.

## Add a machine to a hybrid worker group

You can also add machines to an existing hybrid worker group.

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

1. Under **Hybrid worker group**, select **Hybrid Workers**.

1. Select **+ Add** to go to the **Add machines as hybrid worker** page. You'll only see machines that aren't part of any other hybrid worker group. 

   :::image type="content" source="./media/extension-based-hybrid-runbook-worker-install/hybrid-worker-group-add-machine.png" alt-text="Screenshot showing the Add button to add machines to existing group.":::

1. Select the checkbox next to the machine(s) you want to add to the hybrid worker group. 

   If you don't see your non-Azure machine 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](/azure/azure-arc/servers/onboard-portal) for Arc-enabled servers. See [Install Arc agent for Arc-enabled VMs](/azure/azure-arc/vmware-vsphere/enable-guest-management-at-scale) to enable guest management for Arc-enabled VMware vSphere and [Install Arc agent for Arc-enabled SCVMM](/azure/azure-arc/system-center-virtual-machine-manager/enable-guest-management-at-scale) to enable guest management for Arc-enabled SCVMM VMs.

1. Select **Add** to add the machine to the group.

   After adding, you can see the machine type as Azure virtual machine, Machine – Azure Arc , Machine – Azure Arc (VMware) or Machine – Azure Arc SCVMM. The **Platform** field shows the worker as **Agent based (V1)** or **Extension based (V2)**.

   :::image type="content" source="./media/extension-based-hybrid-runbook-worker-install/hybrid-worker-group-platform-inline.png" alt-text="Screenshot of platform field showing agent or extension based." lightbox="./media/extension-based-hybrid-runbook-worker-install/hybrid-worker-group-platform-expanded.png":::

## Migrate an existing Agent based to Extension based Hybrid Workers

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, ensure the [prerequisites](#prerequisites) are fulfilled before following these steps:

1. Under **Process Automation**, select **Hybrid worker groups**, and then select your existing hybrid worker group to go to the **Hybrid worker group** page.
1. Under **Hybrid worker group**, select **Hybrid Workers** > **+ Add** to go to the **Add machines as hybrid worker** page.
1. Select the checkbox next to the existing Agent based (V1) Hybrid worker.
1. 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. 
   
For at-scale migration of multiple Agent based Hybrid Workers, you can also use other [channels](#manage-hybrid-worker-extension-using-bicep--arm-templates-rest-api-azure-cli-and-powershell) such as - Bicep, ARM templates, PowerShell cmdlets, REST API, and Azure CLI.


## Delete a Hybrid Runbook Worker

You can delete the Hybrid Runbook Worker from the 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**.

   You'll be presented with a warning in a dialog box **Delete Hybrid worker** that the selected hybrid worker would be deleted permanently. Select **Delete**. This operation will delete the extension for the **Extension based (V2)** worker or remove the **Agent based (V1)** entry from the portal. However, it leaves the stale hybrid worker on the VM. To manually uninstall the agent, see [Uninstall agent](/azure/azure-monitor/agents/agent-manage#uninstall-agent).

   :::image type="content" source="./media/extension-based-hybrid-runbook-worker-install/delete-machine-from-group.png" alt-text="Screenshot showing to delete virtual machine from existing group.":::

   > [!NOTE]
   > - A hybrid worker can co-exist with both platforms: **Agent based (V1)** and **Extension based (V2)**. If you install **Extension based (V2)** on a hybrid worker already running **Agent based (V1)**, then you would see two entries of the Hybrid Runbook Worker in the group. One with Platform **Extension based (V2)** and the other **Agent based (V1)**. </br> </br>
   > - After you disable the Private Link in your Automation account, it might take up to 60 minutes to remove the Hybrid Runbook worker.
   > - Hybrid Runbook Worker proxy settings can be deleted from  HKLM\SOFTWARE\Microsoft\Azure\HybridWorker\Parameters, "Http Connection Proxy Url".

## Delete a Hybrid Runbook Worker group

You can delete an empty Hybrid Runbook Worker group from the portal.

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

1. Select **Delete**.

   A warning message appears to remove any machines that are defined as hybrid workers in the hybrid worker group. If there's already a worker added to the group, you'll first have to delete the worker from the group.

1. Select **Yes**.

   The hybrid worker group will be deleted.


## Automatic upgrade of extension

Hybrid Worker extension supports [Automatic upgrade](/azure/virtual-machines/automatic-extension-upgrade) of minor versions by default. We recommend that you enable Automatic upgrades to take advantage of any security or feature updates without manual overhead. However, to prevent the extension from automatically upgrading (for example, if there is a strict change windows and can only be updated at specific time), you can opt out of this feature by setting the `enableAutomaticUpgrade`property in ARM, Bicep file, PowerShell cmdlets to *false*. Set the same property to *true* whenever you want to re-enable the Automatic upgrade.

Major version upgrades must be managed manually. Run the below cmdlets with the latest TypeHandlerVersion.

> [!NOTE]
> If you had installed the Hybrid Worker extension during the public preview, ensure to upgrade it to the latest major version.

**Azure VMs**

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

#### [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. 

   > [!NOTE]  
   > If you want to add proxy server see [proxy server use](#proxy-server-use).
    

    

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.

**Hybrid Worker extension settings**

#### [Bicep file](#tab/bicep-file)

You can use the Bicep file 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).

Follow the steps mentioned below as an example:

1. Create a Hybrid Worker Group.
1. Create either an Azure VM or Arc-enabled server. Alternatively, you can also use an existing Azure VM or Arc-enabled server.
1. Connect the Azure VM or Arc-enabled server to the above created Hybrid Worker Group. 
1. Generate a new GUID and pass it as the name of the Hybrid Worker.
1. Enable System-assigned managed identity on the VM.
1. Install Hybrid Worker Extension on the VM.
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.

The following Azure resources are defined in the template:

- [hybridRunbookWorkerGroups/hybridRunbookWorkers](/azure/templates/microsoft.automation/automationaccounts/hybridrunbookworkergroups/hybridrunbookworkers)
- [Microsoft.Compute/virtualMachines/extensions](/azure/templates/microsoft.compute/virtualmachines/extensions)

**Review parameters**

Review the parameters used in this template.

| Property | Description |
| --- | --- |
| automationAccount | The name of the existing Automation account. |
| automationAccountLocation | The region of the existing Automation account. |
| workerGroupName | The name of the existing Hybrid Worker Group. |
| virtualMachineName | The name for the VM to be created. The default value is `simple-vm`. |
| adminUsername | The VM admin user name. |
| adminPassword | The VM admin password. |
| vmLocation | The region for the new VM. The default value is `North Central US`. |
| vmSize | The size for the new VM. The default value is `Standard_DS1_v2`. |
| osVersion | The OS for the new Windows VM. The default value is `2019-Datacenter`. |
| dnsNameForPublicIP | The DNS name for the public IP. |

 
#### [REST API](#tab/rest-api)

**Prerequisites**

You would require an Azure VM or Arc-enabled server. You can follow the steps [here](/azure/azure-arc/servers/onboard-portal) to create an Arc connected machine.

**Install and use Hybrid Worker extension**

To install and use Hybrid Worker extension using REST API, follow these steps. The West Central US region is considered in this example.

1. Create a Hybrid Worker Group by making this API call.

   

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. 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