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.

Task Classification

Execution Target: Azure-Only (control-plane API operation) Tab Profile: 3 tabs — Azure Portal · Azure CLI / PowerShell · Standalone Script

Azure API Resource

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

Terraform Reference

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	cluster.deployment.arc_gateway.name
Resource Group	Cluster RG	cluster.deployment.arc_gateway.resource_group
Gateway Type	Public	Only valid value currently
Allowed Features	All (*)	Default

Prerequisites

• Microsoft.HybridCompute resource provider registered
• Resource group for Arc Gateway exists
• Contributor role on target resource group

Variables from variables.yml

Variable	Config Path	Example (IIC)
Subscription ID	azure.subscriptions.<name>.id	(per environment)
Resource Group	cluster.deployment.arc_gateway.resource_group	rg-c01-azl-eus-01
Arc Gateway Name	cluster.deployment.arc_gateway.name	arcgw-c01azleus-azl-eus-01

---

Single Subscription Model

Landing Zone Placement

Field	Value	Config Path
Subscription	Customer subscription	azure.subscriptions.<name>.id
Resource Group	rg-{cluster}-{env}-{region}-01	cluster.deployment.arc_gateway.resource_group
Arc Gateway Name	Per config	cluster.deployment.arc_gateway.name

Execution Options

Azure Portal

Azure Portal

When to use: Learning Azure Local, single deployment, prefer visual interface

Procedure

1. Register Resource Provider (if not already):

• Subscription → Resource providers → Search Microsoft.HybridCompute → Register

2. Create Arc Gateway:

• Search for Arc Gateways (or Azure Arc → Arc Gateways)
• Click + Create | Field | Value | Source | |-------|-------|--------| | Name | Per config | cluster.deployment.arc_gateway.name | | Subscription | Target subscription | azure.subscriptions.<name>.id | | Resource Group | Cluster RG | cluster.deployment.arc_gateway.resource_group | | Region | Your region | azure.region | | Gateway Type | Public | Only option |

3. Review + create: Verify → Click Create → Record the Gateway Endpoint URL

4. 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 variables.yml at cluster.deployment.arc_gateway.id

Links

• Microsoft Learn: Arc Gateway

Orchestrated Script

Azure CLI / PowerShell

When to use: Scripted Azure operations from management workstation or pipeline — config-driven via variables.yml

Script

Primary: scripts/deploy/02-azure-foundation/phase-04-azure-management-infrastructure/task-08-arc-gateway/powershell/New-ArcGateway.ps1

Alternatives:

Variant	Path
PowerShell + Azure CLI	task-08-arc-gateway/azure-cli/New-ArcGateway.azcli.ps1
Bash + Azure CLI	task-08-arc-gateway/bash/invoke-arc-gateway.sh

Code

# ============================================================================
# Script: New-ArcGateway.ps1
# Execution: Run from management workstation — reads variables.yml
# Prerequisites: Az.Resources module, authenticated to Azure
# NOTE: Uses REST API (Microsoft.HybridCompute/gateways not in Az.* modules yet)
# ============================================================================

#Requires -Modules Az.Resources, Az.Accounts

param(
 [Parameter(Mandatory = $false)]
 [ValidateScript({Test-Path $_})]
 [string]$ConfigPath = "config/variables.yml"
)

$ErrorActionPreference = "Stop"
$scriptRoot = $PSScriptRoot

. "$scriptRoot/../../../../../common/utilities/helpers/config-loader.ps1"
. "$scriptRoot/../../../../../common/utilities/helpers/logging.ps1"

$config = Get-InfrastructureConfig -ConfigPath $ConfigPath

$SubscriptionId = $config.azure.subscriptions.($config.network.azure_vnets.management.subscription).id
$ResourceGroup = $config.cluster.deployment.arc_gateway.resource_group
$GatewayName = $config.cluster.deployment.arc_gateway.name
$Location = $config.network.azure_vnets.management.location

Set-AzContext -SubscriptionId $SubscriptionId | Out-Null

# Use Azure REST API
$apiVersion = "2025-01-13"
$resourceId = "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.HybridCompute/gateways/$GatewayName"

$body = @{
 location = $Location
 properties = @{
 allowedFeatures = @("*")
 gatewayType = "Public"
 }
} | ConvertTo-Json -Depth 5

Write-LogInfo "Creating Arc Gateway: $GatewayName"
$token = (Get-AzAccessToken).Token
$headers = @{ Authorization = "Bearer $token"; "Content-Type" = "application/json" }
$uri = "https://management.azure.com$resourceId`?api-version=$apiVersion"

$response = Invoke-RestMethod -Uri $uri -Method Put -Headers $headers -Body $body

Write-LogSuccess "Arc Gateway created: $GatewayName"
Write-LogInfo "Gateway Endpoint: $($response.properties.gatewayEndpoint)"
Write-LogInfo "Resource ID: $resourceId"
$response

Validation

$token = (Get-AzAccessToken).Token
$headers = @{ Authorization = "Bearer $token" }
$uri = "https://management.azure.com$resourceId`?api-version=$apiVersion"
(Invoke-RestMethod -Uri $uri -Headers $headers).properties | Format-List gatewayEndpoint, provisioningState

Standalone Script

Standalone Script

When to use: Copy-paste ready script — no config file, no helpers needed.

Code

# ============================================================================
# Script: New-ArcGateway-Standalone.ps1
# Execution: Run anywhere — fully self-contained
# Prerequisites: Az.Accounts module, authenticated to Azure
# ============================================================================

#Requires -Modules Az.Accounts

#region CONFIGURATION
$SubscriptionId = "00000000-0000-0000-0000-000000000000"
$ResourceGroup = "rg-azl-arc-gw-eus-01"
$GatewayName = "azl-arc-gw-centralus-01"
$Location = "eastus"
#endregion CONFIGURATION

Set-AzContext -SubscriptionId $SubscriptionId | Out-Null

$apiVersion = "2025-01-13"
$resourceId = "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroup/providers/Microsoft.HybridCompute/gateways/$GatewayName"

$body = @{
 location = $Location
 properties = @{
 allowedFeatures = @("*")
 gatewayType = "Public"
 }
} | ConvertTo-Json -Depth 5

$token = (Get-AzAccessToken).Token
$headers = @{ Authorization = "Bearer $token"; "Content-Type" = "application/json" }
$uri = "https://management.azure.com$resourceId`?api-version=$apiVersion"

Write-Host "Creating Arc Gateway: $GatewayName" -ForegroundColor Cyan
$response = Invoke-RestMethod -Uri $uri -Method Put -Headers $headers -Body $body

Write-Host "Arc Gateway created" -ForegroundColor Green
Write-Host "Gateway Endpoint: $($response.properties.gatewayEndpoint)"
Write-Host "Resource ID: $resourceId"

No External Dependencies

Self-contained. Edit the #region CONFIGURATION block and run.

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	azure.subscriptions.management.id
Resource Group	Per config	cluster.deployment.arc_gateway.resource_group
Arc Gateway Name	Per config	cluster.deployment.arc_gateway.name

Execution Options

Azure Portal

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

Orchestrated Script

Azure CLI / PowerShell

Same Script — Different Config

The orchestrated script is identical. variables.yml references the correct Management subscription for CAF/WAF.

Standalone Script

Standalone Script

Update #region CONFIGURATION for the Management subscription:

#region CONFIGURATION
$SubscriptionId = "00000000-0000-0000-0000-000000000000" # Management subscription
$ResourceGroup = "rg-azl-arc-gw-eus-01"
# ...
#endregion CONFIGURATION

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 scripted methods shown in the tabs above. Additional deployment methods including Azure CLI and Bash scripts are available in the azurelocal-toolkit repository under scripts/deploy/.

Method	Description
Azure CLI	PowerShell-based Azure CLI scripts for Azure resource operations
Bash	Linux/macOS compatible shell scripts for pipeline environments

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