Task 08: Arc Gateway
DOCUMENT CATEGORY: Runbook
SCOPE: Arc Gateway deployment
PURPOSE: Create Arc Gateway for hybrid server connectivity
MASTER REFERENCE: Microsoft Learn - Arc Gateway
Status: Active
Overview
This task deploys an Azure Arc Gateway resource. The Arc Gateway provides a centralized network endpoint that Arc-enabled servers use to communicate with Azure services, reducing the number of required firewall rules for on-premises infrastructure.
Execution Target: Azure-Only (control-plane API operation) Tab Profile: 3 tabs — Azure Portal · PowerShell · Azure CLI
The Arc gateway can only be enabled during deployment of a new Azure Local instance (software version 2506 or later). It cannot be enabled after deployment. Decide whether to use it, and create the gateway resource in the subscription that will host the instance, before you register the machines.
If your environment inspects or terminates TLS, Arc gateway is not recommended and does not support TLS-terminating proxies. Skip TLS inspection for the gateway endpoint (<your URL prefix>.gw.arc.azure.com).
Source: Overview of Azure Arc gateway for Azure Local and Azure Arc gateway limitations.
The Arc Gateway uses the Microsoft.HybridCompute/gateways resource type. As of this writing, it requires the AzAPI provider in Terraform (not yet in azurerm).
Module: azurelocal-toolkit
File: arcgw.tf
Mode: Cluster
Components Created
| Resource | Name Pattern | Purpose |
|---|---|---|
| Arc Gateway | arcgw-{instance}{env}{location}-{env}-{region}-01 | Centralized Arc connectivity |
Arc Gateway Configuration
| Setting | Value | Source |
|---|---|---|
| Name | Per naming convention | networking.outbound.arc_gateway.name |
| Resource Group | Cluster RG | networking.outbound.arc_gateway.resource_group |
| Gateway Type | Public | Only valid value currently |
| Allowed Features | All (*) | Default |
Prerequisites
-
Microsoft.HybridComputeresource provider registered - Resource group for Arc Gateway exists
- Contributor role on target resource group
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.location, azure.resource_group, tags
scenario.outbound_path
networking.outbound.arc_gateway.name, .resource_group
Single Subscription Model
Landing Zone Placement
| Field | Value | Config Path |
|---|---|---|
| Subscription | Customer subscription | landing_zone.subscriptions[].id |
| Resource Group | rg-{cluster}-{env}-{region}-01 | networking.outbound.arc_gateway.resource_group |
| Arc Gateway Name | Per config | networking.outbound.arc_gateway.name |
Execution Options
- Azure Portal
- Orchestrated Script
- Azure CLI
Azure Portal
When to use: Learning Azure Local, single deployment, prefer visual interface
Procedure
- Register Resource Provider (if not already):
- Subscription → Resource providers → Search
Microsoft.HybridCompute→ Register
- Create Arc Gateway:
- Search for Arc Gateways (or Azure Arc → Arc Gateways)
- Click + Create
Field Value Source Name Per config networking.outbound.arc_gateway.nameSubscription Target subscription landing_zone.subscriptions[].idResource Group Cluster RG networking.outbound.arc_gateway.resource_groupRegion Your region azure.locationGateway Type Public Only option
-
Review + create: Verify → Click Create → Record the Gateway Endpoint URL
-
Note the Gateway ID: Copy the full resource ID — it will be needed during Azure Local cluster deployment:
/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.HybridCompute/gateways/{name}
Validation
- Arc Gateway provisioning state: Succeeded
- Gateway endpoint URL recorded
- Resource ID saved in
infrastructure.ymlatnetworking.outbound.arc_gateway.name
Links
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/02-azure-foundation/phase-04-azure-management-infrastructure/02-manual-deployment/task-08-arc-gateway/powershell/New-ArcGateway.ps1 | Creates the Azure Arc gateway resource that networking.outbound.arc_gateway of infrastructure.yml names. Supports -WhatIf. |
Requires: PowerShell 7.
Run
./New-ArcGateway.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/02-azure-foundation/phase-04-azure-management-infrastructure/02-manual-deployment/task-08-arc-gateway/azurecli/New-ArcGateway.azcli.ps1 | Creates the Azure Arc gateway resource that networking.outbound.arc_gateway of infrastructure.yml names, 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 arcgateway (az extension add --name arcgateway).
It does something only when scenario.outbound_path is arc_gateway or proxy_arc_gateway; for another path it says so and exits 0. Creation takes about 10 to 30 minutes. It does not point the machines at the gateway: the OS configuration and the Arc registration do that.
Run
./New-ArcGateway.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./New-ArcGateway.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Validation
- Arc Gateway provisioning state: Succeeded
- Gateway endpoint URL available
- Resource ID recorded for cluster deployment
CAF/WAF Landing Zone Model
In the CAF/WAF model, the Arc Gateway is typically deployed in the Management or Identity subscription, depending on governance structure.
Landing Zone Placement
| Field | Value | Config Path |
|---|---|---|
| Subscription | Management subscription | landing_zone.subscriptions[].id |
| Resource Group | Per config | networking.outbound.arc_gateway.resource_group |
| Arc Gateway Name | Per config | networking.outbound.arc_gateway.name |
Execution Options
- Azure Portal
- Orchestrated Script
- Azure CLI
Azure Portal
Follow the same procedure as Single Subscription → Azure Portal, targeting the Management subscription.
Validation
- Arc Gateway in Management subscription
- Gateway endpoint URL accessible from on-premises network
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/02-azure-foundation/phase-04-azure-management-infrastructure/02-manual-deployment/task-08-arc-gateway/powershell/New-ArcGateway.ps1 | Creates the Azure Arc gateway resource that networking.outbound.arc_gateway of infrastructure.yml names. Supports -WhatIf. |
Requires: PowerShell 7.
Run
./New-ArcGateway.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/02-azure-foundation/phase-04-azure-management-infrastructure/02-manual-deployment/task-08-arc-gateway/azurecli/New-ArcGateway.azcli.ps1 | Creates the Azure Arc gateway resource that networking.outbound.arc_gateway of infrastructure.yml names, 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 arcgateway (az extension add --name arcgateway).
It does something only when scenario.outbound_path is arc_gateway or proxy_arc_gateway; for another path it says so and exits 0. Creation takes about 10 to 30 minutes. It does not point the machines at the gateway: the OS configuration and the Arc registration do that.
Run
./New-ArcGateway.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./New-ArcGateway.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Validation
- Arc Gateway in correct subscription
- Endpoint reachable for cluster registration
Troubleshooting
| Issue | Root Cause | Remediation |
|---|---|---|
| Resource provider not registered | Microsoft.HybridCompute not enabled | Register via Subscription → Resource providers |
| 403 Forbidden on REST API | Insufficient permissions | Need Contributor on resource group |
| Gateway endpoint not available | Deployment still propagating | Wait 5 minutes and query again |
| Arc agent cannot reach gateway | Firewall blocking gateway endpoint | Allow *.gw.arc.azure.net on port 443 |
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 |
|---|---|---|
| Task 07: NAT Gateway | Manual Deployment Index | Task 09: Log Analytics Workspace |
Version Control
- Created: 2025-09-15 by Hybrid Cloud Solutions
- Last Updated: 2026-03-03 by Hybrid Cloud Solutions
- Version: 4.0.0
- Tags: azure-local, arc-gateway, hybrid, connectivity
- Keywords: Arc Gateway, Azure Arc, hybrid compute, gateway endpoint, Arc-enabled servers
- Author: Hybrid Cloud Solutions
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |