Task 01: Enable Azure Hybrid Benefit
DOCUMENT CATEGORY: Runbook SCOPE: Enable Azure Hybrid Benefit on Azure Local cluster to reduce Windows VM compu... PURPOSE: Enable Azure Hybrid Benefit on Azure Local cluster to reduce Windows VM compute costs MASTER REFERENCE: Azure Hybrid Benefit for Azure Local
Status: Active
Azure Hybrid Benefit is NOT included by default. This benefit requires the customer to have:
- Windows Server Datacenter licenses with active Software Assurance (SA), obtained through:
- Enterprise Agreement (EA) with active Software Assurance
- Cloud Solution Provider (CSP) subscription
- Microsoft Customer Agreement (MCA) with qualifying subscription
-
Sufficient core licenses - Each Windows Server core license entitles use on one physical core of Azure Local. You must allocate enough core licenses to cover all physical cores on all servers in the Azure Local cluster.
-
Ongoing compliance - Workloads using Azure Hybrid Benefit can run only during the Software Assurance or subscription license term. When the term approaches expiration, you must:
- Renew your agreement with Software Assurance or subscription license, OR
- Disable the Azure Hybrid Benefit functionality, OR
- Deprovision workloads using Azure Hybrid Benefit
⚠️ Microsoft reserves the right to audit customers at any time to verify eligibility for Azure Hybrid Benefit utilization.
Reference: Azure Hybrid Benefit for Windows Server | Azure Hybrid Benefit for Azure Local
Azure Hybrid Benefit allows you to use existing Windows Server licenses with Software Assurance to reduce costs for Windows VMs running on Azure Local.
Azure Hybrid Benefit for Azure Local waives the Azure Local host service fee and the Windows Server guest subscription fee. It applies only to hyperconverged deployments with cloud-connected management and no external storage. Disaggregated deployments, hyperconverged deployments with external storage, and disconnected operations are not eligible for the Azure Local benefit. You can't deactivate the benefit after activation. Source: Azure Hybrid Benefit for Azure Local.
Overview
Azure Hybrid Benefit provides:
- Up to 40% savings on Windows VM compute costs
- License mobility from on-premises to Azure Local
- Compliance with Microsoft licensing requirements
Prerequisites
- Windows Server licenses with active Software Assurance
- Azure Local cluster registered with Azure Arc
- Owner or Contributor role on the cluster resource
Values from infrastructure.yml
The script reads these keys from infrastructure.yml (schema 5). Each key, with its type, default and example, is in the variables reference.
azure.tenant_id, azure.subscription_id, azure.resource_group, cluster.name
scenario.storage_architecture, scenario.connectivity
operations.licensing.azure_hybrid_benefit
Execution Options
- Azure Portal
- Orchestrated Script
- Azure CLI
Steps
- Navigate to the Azure portal → Azure Arc → Azure Local
- Select your cluster resource
- Go to Settings → Configuration
- Locate Azure Hybrid Benefit section
- Toggle Enable Azure Hybrid Benefit to On
- Review the licensing attestation
- Click Save
Verification
- Return to the cluster Overview page
- Confirm Azure Hybrid Benefit shows as Enabled
PowerShell
When to use: Run the task from a management workstation or a pipeline. The script reads
infrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/05-operational-foundations/phase-05-licensing-telemetry/task-01-enable-azure-hybrid-benefit/powershell/Enable-AzureHybridBenefit.ps1 | Activates Azure Hybrid Benefit for the Azure Local instance when operations.licensing.azure_hybrid_benefit of infrastructure.yml is true. Supports -WhatIf. |
Requires: PowerShell 7.
Run
./Enable-AzureHybridBenefit.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
Azure CLI
When to use: Run the task from a host that has the Azure CLI and not the Az PowerShell modules. The script is PowerShell 7 that calls
az; it readsinfrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/05-operational-foundations/phase-05-licensing-telemetry/task-01-enable-azure-hybrid-benefit/azurecli/Enable-AzureHybridBenefit.azcli.ps1 | Activates Azure Hybrid Benefit for the Azure Local instance when operations.licensing.azure_hybrid_benefit of infrastructure.yml is true, with the Azure CLI. Supports -WhatIf. |
Requires: PowerShell 7 and the Azure CLI, signed in with az login --tenant <azure.tenant_id>. Needs the Azure CLI extension stack-hci (az extension add --name stack-hci); the script does not install it.
The script never turns the benefit off. It refuses scenario.storage_architecture san or hybrid and scenario.connectivity disconnected (exit 2) and sends nothing to Azure. Whether your organization has Software Assurance is not checked: Azure answers that it cannot find the contract when there is none. You need Contributor or Owner on the instance.
Run
./Enable-AzureHybridBenefit.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Enable-AzureHybridBenefit.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Verification
After enabling Azure Hybrid Benefit, verify the configuration:
# On the cluster node
Get-AzStackHCI | Select-Object ClusterName, AzureHybridBenefit
# From management server
$cluster = Get-AzResource -ResourceId $ClusterResourceId
$cluster.Properties.softwareAssuranceProperties
Troubleshooting
| Issue | Resolution |
|---|---|
| "Cluster not connected" | Verify Arc connection with Get-AzStackHCI |
| Permission denied | Ensure Owner or Contributor role on cluster resource |
| License attestation required | Review and accept the licensing terms in Azure Portal |
Related Documentation
Scripts for this task are located in the azurelocal-toolkit repository under scripts/deploy/ in the appropriate task folder.
Alternatives
The procedures in this task use the methods shown in the tabs above. The toolkit is PowerShell 7 only and has no Bash scripts. A few tasks that act on Azure also have an Azure CLI script written in PowerShell. The script status page of the toolkit lists which task has which script.
Navigation
| Previous | Up | Next |
|---|---|---|
| ← Phase 04: Security & Governance | Phase 05: Licensing & Telemetry | Task 02: Windows Server Subscription → |
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2026-03-24 | Azure Local Cloud | Initial release |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |