Migrate the existing agent-based hybrid workers to extension-based hybrid workers

  • Article

Important

Azure Automation Agent-based User Hybrid Runbook Worker (Windows and Linux) has retired on 31 August 2024 and is no longer supported. Follow the guidelines in this article on how to migrate from an existing Agent-based User Hybrid Runbook Workers to Extension-based Hybrid Workers.

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.

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

  • Microsoft Entra ID based authentication – It uses a VM system-assigned managed identities provided by Microsoft Entra ID. 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.

Note

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.

Prerequisites

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.
  • The system-assigned managed identity must be enabled on the Azure virtual machine, Arc-enabled server. 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

Windows (x64) Linux (x64)
● Windows Server 2022 (including Server Core)
● Windows Server 2019 (including Server Core)
● Windows Server 2016, version 1709 and 1803 (excluding Server Core)
● Windows Server 2012, 2012 R2 (excluding Server Core)
● Windows 10 Enterprise (including multi-session) and Pro		 ● Debian GNU/Linux 8,9,10, and 11
● Ubuntu 18.04 LTS, 20.04 LTS, and 22.04 LTS
● SUSE Linux Enterprise Server 15.2, and 15.3
● Red Hat Enterprise Linux Server 7, 8, and 9
● SUSE Linux Enterprise Server (SLES) 15
● Rocky Linux 9
● Oracle Linux 7 and 8
Hybrid Worker extension would follow support timelines of the OS vendor. 

Other Requirements

Windows (x64) Linux (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 package Description Minimum version
Glibc GNU C Library 2.5-12
Openssl OpenSSL Libraries 1.0 (TLS 1.1 and TLS 1.2 are supported)
Curl cURL web client 7.15.5
Python-ctypes Foreign function library for Python Python 2.x or Python 3.x are required
PAM Pluggable Authentication Modules
Optional package Description Minimum version
PowerShell Core To run PowerShell runbooks, PowerShell Core needs to be installed. For instructions, see Installing PowerShell Core on Linux 6.0.0

Permissions for Hybrid worker credentials

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

Resource Type Folder permissions
Azure VM C:\Packages\Plugins\Microsoft.Azure.Automation.HybridWorker.HybridWorkerForWindows (read and execute)

Note

  • 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, ensure the 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.

  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.

    Screenshot of adding machines as hybrid worker.

  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.

    Screenshot of platform field showing agent or extension based hybrid worker.

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

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.

Follow the steps mentioned below as an example:

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

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

  1. Open PowerShell session in Administrator mode and run the following command:

     Remove-Item -Path "HKLM:\SOFTWARE\Microsoft\HybridRunbookWorker\<AutomationAccountID>\<HybridWorkerGroupName>" -Force -Verbose

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

  3. Under Hybrid worker group, select Hybrid Workers.

  4. Select the checkbox next to the machine(s) you want to delete from the hybrid worker group.

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

Next steps