Share via

Issue installing HybridWorkerExtension on Azure Arc-enabled machine

Eric Morsa 20 Reputation points
2025-09-22T15:17:09.6966667+00:00

I’m trying to install the HybridWorkerExtension on a local machine connected to Azure via Azure Arc. The machine is correctly onboarded, the managed identity is enabled, and the connectedmachine CLI extension is installed.

I used a valid payload.json with a REST API call to deploy the extension, but:

  • The extension does not appear in the Azure portal.
  • No HybridWorkerService is running on the machine.
  • No worker group has been created.

I’ve noticed that the V1 extension is no longer available, and the V2 version is not yet publicly released or documented.

🔍 Has anyone found a working method to deploy the Hybrid Worker in this situation? Any workaround or updated guidance would be greatly appreciated.

Azure Arc
Azure Arc
A Microsoft cloud service that enables deployment of Azure services across hybrid and multicloud environments.
Answer accepted by question author
  1. Bharath Y P 1,515 Reputation points Microsoft External Staff Moderator
    2025-09-23T00:30:33.9766667+00:00

    Hello Eric Morsa,

    As you mentioned, you are trying to install the Azure Automation Hybrid Worker Extension on a local machine connected via Azure Arc.

    The Azure portal method is the most reliable way to install the Hybrid Worker because it automatically handles the V2 extension deployment, which is the current and supported version.

    https://free.blessedness.top/en-us/azure/automation/automation-hybrid-runbook-worker

    Before you start, ensure these are in place:

    • Azure Automation Account: You must have an Automation Account.
    • System-Assigned Managed Identity: This must be enabled on your Azure Arc-enabled server. This identity gives the extension the necessary permissions to securely register and communicate with your Automation Account.
    • Hybrid Worker Group: Create a Hybrid Runbook Worker group in your Automation Account. The machine will be added to this group during installation.
    • Network Connectivity: The machine needs outbound access on port 443 to the Azure Automation endpoints. Without this, the extension won't be able to connect and report its status.

    By using the portal's Extensions blade on your Arc-enabled machine, you can avoid the common pitfalls of manual deployments, such as using an outdated or incorrect extension name. The portal's UI guides you to the correct and supported extension for your OS.

    This process will handle the following automatically:

    • It verifies the correct extension publisher (Microsoft.Azure.Automation.HybridWorker) and extension type (HybridWorkerForWindows or HybridWorkerForLinux).
    • It passes the required settings, such as your Automation Account name and Hybrid Worker Group name, to the extension.
    • It ensures the HybridWorkerService starts and is running on the machine after installation.

    If the installation fails, check the Extension status in the portal for the error message. It often points to a network, managed identity, or a prerequisite that was missed.

    Kindly check the below documentation for more details:

    Migrate an existing agent-based hybrid workers to extension-based-workers in Azure Automation | Microsoft Learn

    Deploy an extension-based Windows or Linux User Hybrid Runbook Worker in Azure Automation | Microsoft Learn

    Hope this helps. and please feel free to reach out if you have any further questions.

    1 person found this answer helpful.
    0 comments

2 additional answers

Sort by: Most helpful
Most helpful Newest Oldest
  1. Eric Morsa 20 Reputation points
    2025-09-24T15:16:17.0366667+00:00

    Thank you very much for your reply.

    I'm currently working on the issue and will share the outcome as soon as it's resolved. Just to note, when trying to add the Hybrid Worker extension via the Azure portal, the process gets stuck after selecting the extension. The “Next” button appears, but nothing happens when clicked.

    Also, your clarification regarding the use of an incorrect URL (e.g., RegistrationUrl) instead of the required AutomationHybridServiceUrl for the V2 extension was extremely helpful.

    Thanks again for your support!

    0 comments
  2. Eric Morsa 20 Reputation points
    2025-09-24T21:38:26.7733333+00:00

    The issue has been successfully resolved. Below is the step-by-step procedure that was followed to fix the problem with v2 version !

    HYBRID WORKER V2 INSTALLATION PROCEDURE (AZURE ARC, WINDOWS)

    SECTION 1: CONNECT TO AZURE AND SELECT SUBSCRIPTION

    az login

az account set --subscription "<SUBSCRIPTION_ID>"

    SECTION 2: CREATE RESOURCE GROUP

    az group create --name <RESOURCE_GROUP_NAME> --location <LOCATION>

    SECTION 3: CREATE AUTOMATION ACCOUNT

    az automation account create --name <AUTOMATION_ACCOUNT_NAME> --resource-group <RESOURCE_GROUP_NAME> --location <LOCATION>

    SECTION 4: CREATE HYBRID WORKER GROUP

    New-AzAutomationHybridRunbookWorkerGroup `

    -ResourceGroupName "<RESOURCE_GROUP_NAME>" `

    -AutomationAccountName "<AUTOMATION_ACCOUNT_NAME>" `

    -Name "<HYBRID_WORKER_GROUP_NAME>"

    SECTION 5: CONNECT THE LOCAL MACHINE TO AZURE ARC

    - Download the onboarding script from the Azure Portal or Microsoft Learn documentation.

- Run the script (e.g., OnboardingScript.ps1) on the target machine to register it as an Azure Arc resource.

    SECTION 6: ENABLE SYSTEM ASSIGNED MANAGED IDENTITY

    az connectedmachine identity assign --machine-name <MACHINE_NAME> --resource-group <RESOURCE_GROUP_NAME>

    SECTION 7: RETRIEVE THE AUTOMATION HYBRID SERVICE URL

    az automation account show --resource-group <RESOURCE_GROUP_NAME> --name <AUTOMATION_ACCOUNT_NAME> --query "automationHybridServiceUrl"

    SECTION 8: PREPARE THE SETTINGS FILE

    - Create a JSON file (e.g., settings.json) with the following content:

    {

        "AutomationAccountURL": "<AUTOMATION_HYBRID_SERVICE_URL>"

    }

    SECTION 9: INSTALL THE HYBRID WORKER EXTENSION (V2)

    az connectedmachine extension create `

    --name HybridWorkerExtension `

    --machine-name <MACHINE_NAME> `

    --resource-group <RESOURCE_GROUP_NAME> `

    --location <LOCATION> `

    --publisher Microsoft.Azure.Automation.HybridWorker `

    --type HybridWorkerForWindows `

    --settings @<PATH_TO_SETTINGS_JSON>

    SECTION 10: REGISTER THE MACHINE AS A HYBRID WORKER (IF REQUIRED)

    az automation hrwg create `

    --automation-account-name <AUTOMATION_ACCOUNT_NAME> `

    --resource-group <RESOURCE_GROUP_NAME> `

    --name <HYBRID_WORKER_GROUP_NAME>

az automation hrwg hrw create `

    --automation-account-name <AUTOMATION_ACCOUNT_NAME> `

    --resource-group <RESOURCE_GROUP_NAME> `

    --hybrid-runbook-worker-group-name <HYBRID_WORKER_GROUP_NAME> `

    --name <WORKER_GUID> `

    --vm-resource-id <AZURE_ARC_MACHINE_RESOURCE_ID>

    NOTE:

    The onboarding script (OnboardingScript.ps1) is generated and downloaded from the Azure Portal or Microsoft Learn, specifically for Azure Arc onboarding.

Replace all placeholders (e.g., <SUBSCRIPTION_ID>, <RESOURCE_GROUP_NAME>, <LOCATION>, etc.) with your actual values.
    0 comments

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.