Deploy an agent-based Linux Hybrid Runbook Worker in Automation
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 on how to migrate from an existing Agent-based User Hybrid Runbook Workers to Extension-based Hybrid Workers.
You can use the user Hybrid Runbook Worker feature of Azure Automation to run runbooks directly on the Azure or non-Azure machine, including servers registered with Azure Arc-enabled servers. From the machine or server that's hosting the role, you can run runbooks directly it and against resources in the environment to manage those local resources.
The Linux Hybrid Runbook Worker executes runbooks as a special user that can be elevated for running commands that need elevation. Azure Automation stores and manages runbooks and then delivers them to one or more chosen machines. This article describes how to: install the Hybrid Runbook Worker on a Linux machine, remove the worker, and remove a Hybrid Runbook Worker group. For User Hybrid Runbook Workers, see also Deploy an extension-based Windows or Linux User Hybrid Runbook Worker in Automation
After you successfully deploy a runbook worker, review Run runbooks on a Hybrid Runbook Worker to learn how to configure your runbooks to automate processes in your on-premises datacenter or other cloud environment.
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). Learn more.
Prerequisites
Before you start, make sure that you've the following.
A Log Analytics workspace
The Hybrid Runbook Worker role depends on an Azure Monitor Log Analytics workspace to install and configure the role. You can create it through Azure Resource Manager, through PowerShell, or in the Azure portal.
If you don't have an Azure Monitor Log Analytics workspace, review the Azure Monitor Log design guidance before you create the workspace.
Log Analytics agent
The Hybrid Runbook Worker role requires the Log Analytics agent for the supported Linux operating system. For servers or machines hosted outside of Azure, you can install the Log Analytics agent using Azure Arc-enabled servers. The agent is installed with certain service accounts that execute commands requiring root permissions. For more information, see Service accounts.
Supported Linux operating systems
The Hybrid Runbook Worker feature supports the following distributions. All operating systems are assumed to be x64. x86 isn't supported for any operating system.
Amazon Linux 2012.09 to 2015.09
Oracle Linux 6, 7, and 8
Red Hat Enterprise Linux Server 5, 6, 7, and 8
Debian GNU/Linux 6, 7, and 8
SUSE Linux Enterprise Server 12, 15, and 15.1 (SUSE didn't release versions numbered 13 or 14)
Ubuntu
Linux OS Name 20.04 LTS Focal Fossa 18.04 LTS Bionic Beaver 16.04 LTS Xenial Xerus 14.04 LTS Trusty Tahr
Note
Hybrid Worker would follow support timelines of the OS vendor.
Important
Before enabling the Update Management feature, which depends on the system Hybrid Runbook Worker role, confirm the distributions it supports here.
Minimum requirements
The minimum requirements for a Linux system and user Hybrid Runbook Worker are:
- Two cores
- 4 GB of RAM
- Port 443 (outbound)
| 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. See Installing PowerShell Core on Linux to learn how to install it. | 6.0.0 |
Adding a machine to a Hybrid Runbook Worker group
You can add the worker machine to a Hybrid Runbook Worker group in one of your Automation accounts. For machines hosting the system Hybrid Runbook worker managed by Update Management, they can be added to a Hybrid Runbook Worker group. But you must use the same Automation account for both Update Management and the Hybrid Runbook Worker group membership.
Note
Azure Automation Update Management automatically installs the system Hybrid Runbook Worker on an Azure or non-Azure machine that's enabled for Update Management. However, this worker is not registered with any Hybrid Runbook Worker groups in your Automation account. To run your runbooks on those machines, you need to add them to a Hybrid Runbook Worker group. Follow step 4 under the section Install a Linux Hybrid Runbook Worker to add it to a group.
Supported Linux hardening
The following aren't yet supported:
- CIS
Supported runbook types
Linux Hybrid Runbook Workers support a limited set of runbook types in Azure Automation, and they're described in the following table.
| Runbook type | Supported |
|---|---|
| Python 3 (preview) | Yes, required for these distros only: SUSE LES 15, RHEL 8 |
| Python 2 | Yes, for any distro that doesn't require Python 31 |
| PowerShell | Yes2 |
| PowerShell Workflow | No |
| Graphical | No |
| Graphical PowerShell Workflow | No |
1See Supported Linux operating systems.
2PowerShell runbooks require PowerShell Core to be installed on the Linux machine. See Installing PowerShell Core on Linux to learn how to install it.
Network configuration
For networking requirements for the Hybrid Runbook Worker, see Configuring your network.
Install a Linux Hybrid Runbook Worker
There are two methods to deploy a Hybrid Runbook Worker. You can import and run a runbook from the Runbook Gallery in the Azure portal, or you can manually run a series of PowerShell commands.
Importing a runbook from the Runbook Gallery
The import procedure is described in detail in Import runbooks from GitHub with the Azure portal. The name of the runbook to import is Create Automation Linux HybridWorker.
The runbook uses the following parameters.
| Parameter | Status | Description |
|---|---|---|
Location |
Mandatory | The location for the Log Analytics workspace. |
ResourceGroupName |
Mandatory | The resource group for your Automation account. |
AccountName |
Mandatory | The Automation account name in which the Hybrid Run Worker will be registered. |
CreateLA |
Mandatory | If true, uses the value of WorkspaceName to create a Log Analytics workspace. If false, the value of WorkspaceName must refer to an existing workspace. |
LAlocation |
Optional | The location where the Log Analytics workspace will be created, or where it already exists. |
WorkspaceName |
Optional | The name of the Log Analytics workspace to be created or used. |
CreateVM |
Mandatory | If true, use the value of VMName as the name of a new VM. If false, use VMName to find and register existing VM. |
VMName |
Optional | The name of the virtual machine that's either created or registered, depending on the value of CreateVM. |
VMImage |
Optional | The name of the VM image to be created. |
VMlocation |
Optional | Location of the VM that's either created or registered. If this location isn't specified, the value of LAlocation is used. |
RegisterHW |
Mandatory | If true, register the VM as a hybrid worker. |
WorkerGroupName |
Mandatory | Name of the Hybrid Worker Group. |
Manually run PowerShell commands
To install and configure a Linux Hybrid Runbook Worker, perform the following steps.
Enable the Azure Automation solution in your Log Analytics workspace by running the following command in an elevated PowerShell command prompt or in Cloud Shell in the Azure portal:
Set-AzOperationalInsightsIntelligencePack -ResourceGroupName <resourceGroupName> -WorkspaceName <workspaceName> -IntelligencePackName "AzureAutomation" -Enabled $trueDeploy the Log Analytics agent to the target machine.
For Azure VMs, install the Log Analytics agent for Linux using the virtual machine extension for Linux. The extension installs the Log Analytics agent on Azure virtual machines, and enrolls virtual machines into an existing Log Analytics workspace. You can use an Azure Resource Manager template, the Azure CLI, or Azure Policy to assign the Deploy Log Analytics agent for Linux or Windows VMs built-in policy definition. Once the agent is installed, the machine can be added to a Hybrid Runbook Worker group in your Automation account.
For non-Azure machines, you can install the Log Analytics agent using Azure Arc-enabled servers. Azure Arc-enabled servers support deploying the Log Analytics agent using the following methods:
Using the VM extensions framework.
This feature in Azure Arc-enabled servers allows you to deploy the Log Analytics agent VM extension to a non-Azure Windows and/or Linux server. VM extensions can be managed using the following methods on your hybrid machines or servers managed by Azure Arc-enabled servers:
- The Azure portal
- The Azure CLI
- Azure PowerShell
- Azure Resource Manager templates
Using Azure Policy.
Using this approach, you use the Azure Policy Deploy Log Analytics agent to Linux or Microsoft Azure Arc machines built-in policy definition to audit if the Arc-enabled server has the Log Analytics agent installed. If the agent isn't installed, it automatically deploys it using a remediation task. If you plan to monitor the machines with Azure Monitor for VMs, instead use the Enable Azure Monitor for VMs initiative to install and configure the Log Analytics agent.
We recommend installing the Log Analytics agent for Windows or Linux using Azure Policy.
Note
To manage the configuration of machines that support the Hybrid Runbook Worker role with Desired State Configuration (DSC), you must add the machines as DSC nodes.
Note
The nxautomation account with the corresponding sudo permissions must be present during installation of the Linux Hybrid Worker. If you try to install the worker and the account is not present or doesn't have the appropriate permissions, the installation fails.
Verify agent is reporting to workspace.
The Log Analytics agent for Linux connects machines to an Azure Monitor Log Analytics workspace. When you install the agent on your machine and connect it to your workspace, it automatically downloads the components that are required for the Hybrid Runbook Worker.
When the agent has successfully connected to your Log Analytics workspace after a few minutes, you can run the following query to verify that it's sending heartbeat data to the workspace.
Heartbeat | where Category == "Direct Agent" | where TimeGenerated > ago(30m)In the search results, you should see heartbeat records for the machine, indicating that it's connected and reporting to the service. By default, every agent forwards a heartbeat record to its assigned workspace.
Run the following command to add the machine to a Hybrid Runbook Worker group, specifying the values for the parameters
-w,-k,-g, and-e.You can get the information required for parameters
-kand-efrom the Keys page in your Automation account. Select Keys under the Account settings section from the left-hand side of the page.
For the
-eparameter, copy the value for URL.For the
-kparameter, copy the value for PRIMARY ACCESS KEY.For the
-gparameter, specify the name of the Hybrid Runbook Worker group that the new Linux Hybrid Runbook worker should join. If this group already exists in the Automation account, the current machine is added to it. If this group doesn't exist, it's created with that name.For the
-wparameter, specify your Log Analytics workspace ID.
sudo python /opt/microsoft/omsconfig/modules/nxOMSAutomationWorker/DSCResources/MSFT_nxOMSAutomationWorkerResource/automationworker/scripts/onboarding.py --register -w <logAnalyticsworkspaceId> -k <automationSharedKey> -g <hybridGroupName> -e <automationEndpoint>Verify the deployment after the script is completed. From the Hybrid Runbook Worker Groups page in your Automation account, under the User hybrid runbook workers group tab, it shows the new or existing group and the number of members. If it's an existing group, the number of members is incremented. You can select the group from the list on the page, from the left-hand menu choose Hybrid Workers. On the Hybrid Workers page, you can see each member of the group listed.
Note
If you are using the Log Analytics virtual machine extension for Linux for an Azure VM, we recommend setting
autoUpgradeMinorVersiontofalseas auto-upgrading versions can cause issues with the Hybrid Runbook Worker. To learn how to upgrade the extension manually, see Azure CLI deployment.
Turn off signature validation
By default, Linux Hybrid Runbook Workers require signature validation. If you run an unsigned runbook against a worker, you see a Signature validation failed error. To turn off signature validation, run the following command as root. Replace the second parameter with your Log Analytics workspace ID.
sudo python /opt/microsoft/omsconfig/modules/nxOMSAutomationWorker/DSCResources/MSFT_nxOMSAutomationWorkerResource/automationworker/scripts/require_runbook_signature.py --false <logAnalyticsworkspaceId>
Remove the Hybrid Runbook Worker
Run the following commands as root on the agent-based Linux Hybrid Worker:
sudo bash rm -r /home/nxautomationUnder Process Automation, select Hybrid worker groups and then your hybrid worker group to go to the Hybrid Worker Group page.
Under Hybrid worker group, select Hybrid Workers.
Select the checkbox next to the machine(s) you want to delete from the hybrid worker group.
Select Delete to remove the agent-based Linux Hybrid Worker.
Note
- This script doesn't remove the Log Analytics agent for Linux from the machine. It only removes the functionality and configuration of the Hybrid Runbook Worker role.
- 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.
Remove a Hybrid Worker group
To remove a Hybrid Runbook Worker group of Linux machines, you use the same steps as for a Windows hybrid worker group. See Remove a Hybrid Worker group.
Manage Role permissions for Hybrid Worker Groups and Hybrid Workers
You can create custom Azure Automation roles and grant following permissions to Hybrid Worker Groups and Hybrid Workers. To learn more about how to create Azure Automation custom roles, see Azure custom roles
| Actions | Description |
|---|---|
| Microsoft.Automation/automationAccounts/hybridRunbookWorkerGroups/read | Reads a Hybrid Runbook Worker Group. |
| Microsoft.Automation/automationAccounts/hybridRunbookWorkerGroups/write | Creates a Hybrid Runbook Worker Group. |
| Microsoft.Automation/automationAccounts/hybridRunbookWorkerGroups/delete | Deletes a Hybrid Runbook Worker Group. |
| Microsoft.Automation/automationAccounts/hybridRunbookWorkerGroups/hybridRunbookWorkers/read | Reads a Hybrid Runbook Worker. |
| Microsoft.Automation/automationAccounts/hybridRunbookWorkerGroups/hybridRunbookWorkers/delete | Deletes a Hybrid Runbook Worker. |
Check version of Hybrid Worker
To check the version of agent-based Linux Hybrid Runbook Worker, go to the following path:
sudo cat /opt/microsoft/omsconfig/modules/nxOMSAutomationWorker/VERSION
The file VERSION has the version number of Hybrid Runbook Worker.
Next steps
To learn how to configure your runbooks to automate processes in your on-premises datacenter or other cloud environment, see Run runbooks on a Hybrid Runbook Worker.
To learn how to troubleshoot your Hybrid Runbook Workers, see Troubleshoot Hybrid Runbook Worker issues - Linux.