Register Azure Local with Azure Arc using Arc gateway

Prerequisites

• You have access to Azure Local machines running release 2506 or later. Earlier versions don't support this scenario.

• You have assigned the appropriate permissions to the subscription used for registration. For more information, see Assign required permissions for Azure Local deployment.

• An Arc gateway resource is created in the same subscription used to deploy Azure Local. For more information, see Create the Arc gateway resource in Azure.

• You have reviewed the supported and unsupported scenarios. For more information, see Supported and unsupported scenarios.

• Required endpoints are open in your firewall. For more information, see Azure Local endpoints not redirected.

• Review guidance on handling preinstalled or outdated OS images during Azure Arc registration.

Step 1: Get the Arc gateway ID

• Get Arc gateway ID. To create Azure Arc gateway, see Set up an Azure Arc gateway and get the resource ID of the Arc gateway. This is also referred to as the ArcGatewayID.

  1. In the Azure portal, go to the Arc gateway resource that you created.
  2. On the Overview page, copy the Resource ID. You use this Arc gateway ID later.

  

Step 2: Review script parameters

Review the parameters used in the script:

Step 3: Set parameters

Set the parameters required for the registration script.

Here's an example of how you should change these parameters for the Invoke-AzStackHciArcInitialization initialization script.

#Define the tenant you will use to register your machine as Arc device
$Tenant = "YourTenantID"

#Define the subscription where you want to register your Azure Local machine with Arc.
$Subscription = "yourSubscriptionID" 

#Define the resource group where you want to register your Azure Local machine with Arc.
$RG = "yourResourceGroupName" 

#Define the region to use to register your server as Arc device
#Do not use spaces or capital letters when defining region
$Region = "eastus"

#Define the Arc gateway resource ID from Azure 
$ArcgwId = "/subscriptions/yoursubscriptionid/resourceGroups/yourResourceGroupName/providers/Microsoft.HybridCompute/gateways/yourArcGatewayName" 

#Define the proxy address for your Azure Local deployment to access the internet via proxy.
$ProxyServer = "http://proxyaddress:port"

#Define the bypass list for the proxy. Use comma to separate each item from the list.  
# Parameters must be separated with a comma `,`.
# Use "localhost" instead of <local> 
# Use specific IPs such as 127.0.0.1 without mask 
# Use * for subnets allowlisting. 192.168.1.* for /24 exclusions. Use 192.168.*.* for /16 exclusions. 
# Append * for domain names exclusions like *.contoso.com 
# DO NOT INCLUDE .svc on the list. The registration script takes care of Environment Variables configuration. 
# At least the IP address of each Azure Local machine.
# At least the IP address of the Azure Local cluster.
# At least the IPs you defined for your infrastructure network. Arc resource bridge, Azure Kubernetes Service (AKS), and future infrastructure services using these IPs require outbound connectivity.
# NetBIOS name of each machine.
# NetBIOS name of the Azure Local cluster.

$ProxyBypassList = "localhost,127.0.0.1,*.contoso.com,machine1,machine2,machine3,machine4,machine5,192.168.*.*,AzureLocal-1" 

#Optional: Define the Azure Resource Manager access token.
# Required only if you want to use token-based authentication instead of device code authentication.
$armTokenResponse = Get-AzAccessToken

# Convert token to string for use in initialization
# Required because Get-AzAccessToken returns SecureString
$ArmAccessToken = [System.Net.NetworkCredential]::new("", $armTokenResponse.Token).Password

# Define the target Azure Local solution version that the node must update to after registering with Azure Arc.
# Example: "12.2602.1002.10"
$TargetSolutionVersion = "<solution-version>" 

Step 4: Run registration script

1. Run the Arc registration script. The script takes a few minutes to run.

   Invoke-AzStackHciArcInitialization
   -TenantId $Tenant
   -SubscriptionID $Subscription
   -ResourceGroup $RG
   -Region $Region
   -Cloud "AzureCloud"
   -ArcGatewayID $ArcgwId
   # Optional
   -Proxy $ProxyServer
   # Optional
   -ProxyBypass $ProxyBypassList
   # Optional: include only when using token-based authentication
   -ArmAccessToken $ArmAccessToken
   # Optional
   -TargetSolutionVersion $TargetSolutionVersion
   

   Note

   If using -ArmAccessToken, convert the token to a plain text string using: $ArmAccessToken = [System.Net.NetworkCredential]::new("", $armTokenResponse.Token).Password.

   For a list of supported Azure regions, see Azure requirements.

2. During the Arc registration process, you must authenticate with your Azure account. The console window displays a code that you must enter in the URL, displayed in the app, in order to authenticate. Follow the instructions to complete the authentication process.

   

Handle preinstalled or outdated OS images during Azure Arc registration

During Azure Arc registration, Azure Local verifies whether the OS image is current for its release baseline. If the image is outdated or unsupported, the system automatically detects it during initialization and provides a list of available update versions to select from. You can proactively specify a target solution version using the optional TargetSolutionVersion parameter.

• The update typically takes 40-45 minutes followed by a reboot.

• Rerun Invoke-AzStackHciArcInitialization cmdlet post reboot.

• During the update, the registration status appears as Update: InProgress.

  

Monitor and complete registration

1. If registration times out or the machine reboots, reconnect and check the registration progress using the following commands:

   $status = Get-ArcBootstrapStatus
   $status.Response.Status
   

2. Review the status value:

   • Succeeded: Registration completed successfully after the update.
   • Failed: Rerun registration using a new ARM token or device code flow.
   • If the issue persists, collect logs using Collect-ArcBootstrapSupportLogs and share them for further troubleshooting.

3. After the reboot, rerun the Invoke-AzStackHciArcInitialization cmdlet to continue.

Step 4: Verify the Azure Arc gateway setup is successful

Once the registration is complete, follow these steps to verify that Azure Arc gateway setup is successful.

1. Connect to the first Azure Local machine from your system.

2. Open the Arc gateway log to monitor which endpoints are being redirected to the Arc gateway and which ones continue using your firewall or proxy. You can find the Arc gateway log at: c:\programdata\AzureConnectedMAchineAgent\Log\arcproxy.log.

   

3. To check the Arc agent configuration and verify that it's using the gateway, run the following command:

   C:\program files\AzureConnectedMachineAgent>.\azcmagent show
   

   The values displayed should be as follows:

   1. Agent version is 1.45 or later.

   2. Agent Status should show as Connected.

   3. Using HTTPS Proxy shows as http://localhost:40343when the Arc gateway is enabled.

   4. Upstream Proxy shows your enterprise proxy server and port.

   5. Azure Arc Proxy shows as running when the Arc gateway is enabled.

   

4. Additionally, to verify that the setup was done successfully, run the following command:

   C:\program files\AzureConnectedMachineAgent>.\azcmagent check
   

   The response should indicate that the connection.type is set to gateway, and the Reachable column should indicate true for all URLs.

   Here's an example of the Arc agent using the Arc gateway:

   

   You can also audit your gateway traffic by viewing the gateway router logs.

   To view gateway router logs on Windows, run the azcmagent logs command in PowerShell. In the resulting .zip file, the logs are located in the C:\ProgramData\Microsoft\ArcGatewayRouter folder.

If you plan to deploy a few machines per site, use the Configurator app to register your Azure Local machines with Azure Arc.

Prerequisites

Before you begin, make sure to complete the following prerequisites:

Azure Local machine prerequisites

• Download the Configurator App for Azure Local on a client machine that is connected to the same network as the Azure Local machines.

• Note down:

  • The serial number for each machine.
  • Local administrator credentials to sign into each machine.

Azure prerequisites

• Get Arc gateway ID. To create Azure Arc gateway, see Set up an Azure Arc gateway and get the resource ID of the Arc gateway. This is also referred to as the ArcGatewayID.

  1. In the Azure portal, go to the Arc gateway resource that you created.
  2. On the Overview page, copy the Resource ID. You use this Arc gateway ID later.

  

Step 1: Configure the network and connect to Azure

Follow these steps to configure network settings and connect the machines to Azure. Start this action a few minutes after you turn on the machine.

1. Open the Configurator app. Right-click the Configurator app exe and run as administrator. Wait a few minutes for the app to open up.

   

2. Enter the machine serial number and select Next.

   

3. Sign in to the machine with local administrator credentials.

   

Prerequisites tab

1. On the Prerequisites tab, verify that the minimum requirements are met and then select Next.

   

   If a requirement isn't met, the app displays a warning or errors. You can't proceed if there are errors though warnings are ignored. Resolve the errors before you proceed. For more information, see Troubleshooting registration issues.

   

Basics tab

1. On the Basics tab, configure one network interface that is connected to the internet. Select the Pencil icon to modify network interface settings.

   

2. Provide the interface name, IP allocation as static or Dynamic Host Configuration Protocol (DHCP), IP address, subnet, gateway, and preferred DNS servers. Optionally, enter an alternate DNS server.

   

   Important

   Make sure that the IPs you assign are free and not in use.

3. To specify more details, select Enter additional details.

4. On the Additional details page, provide the following inputs and then select Apply.

   

   1. Select ON to enable Remote desktop protocol. Remote desktop protocol is disabled by default.

   2. Select Proxy server as the connectivity method. Provide the proxy URL and the bypass list. The bypass list is required and can be provided in a comma separated format.

      When defining your proxy bypass string, make sure you meet the following conditions:

      • Include at least the IP address of each Azure Local machine.
      • Include at least the IP address of the Azure Local cluster.
      • Include at least the IPs you defined for your infrastructure network. Arc resource bridge, Azure Kubernetes Service (AKS), and future infrastructure services using these IPs require outbound connectivity.
      • Or you can bypass the entire infrastructure subnet.
      • Provide the NetBIOS name of each machine.
      • Provide the NetBIOS name of the Azure Local cluster.
      • Domain name or domain name with asterisk * wildcard at the beginning to include any host or subdomain. For example, 192.168.1.* for subnets or *.contoso.com for domain names.
      • Parameters must be separated with a comma ,.
      • Classless Inter-Domain Routing (CIDR) notation to bypass subnets isn't supported.
      • The use of <local> strings isn't supported in the proxy bypass list.

   3. Select a time zone.

   4. Specify a preferred and an alternate NTP server to act as a time server or accept the Default. The default is time.windows.com.

   5. Set the hostname for your machine to what you specified during the preparation of Active Directory. Changing the hostname automatically reboots the system.

5. Select Next on the Basics tab.

Arc agent setup tab

1. On the Arc agent setup tab, provide the following inputs:

   

   1. The Cloud type is populated automatically as Azure.

   2. Enter a Subscription ID to register the machine.

   3. Provide a Resource group name. This resource group contains the machine and system resources that you create.

   4. Specify the Region where you want to create the resources. The region should be the same as the region where you want to deploy the Azure Local instance.

      Important

      Specify the region with spaces removed. For example, specify the East US region as EastUS.

   5. Provide a Tenant ID. The tenant ID is the directory ID of your Microsoft Entra tenant. To get the tenant ID, see Find your Microsoft Entra tenant.

   6. Specify the Arc gateway ID. This is the resource ID of the Arc gateway that you set up. For more information, see About Azure Arc gateways.

   Important

   Make sure to verify all the inputs before you proceed. Any incorrect inputs here might result in a setup failure.

2. Select Next.

Review and apply tab

1. On the Review and apply tab, verify machine details. To modify any settings, go back. If satisfied with the current settings, select Finish. If you changed the hostname, your machines boot up automatically at this point and you must sign in again.

   

Step 2: Complete registration of machines to Azure

1. Wait for the configuration to complete. First, machine is configured with the basic details followed by registration of the machines to Azure.

2. During the Arc registration process, you must authenticate with your Azure account. The app displays a code that you must enter in the URL, displayed in the app, in order to authenticate. Follow the instructions to complete the authentication process.

   

3. Once the configuration is complete, status for Arc configuration should display Success (Open in Azure portal).

4. Repeat all steps on the other machines until the Arc configuration succeeds. Select the Open in Azure portal link.

Step 3: Verify machines are connected to Arc

1. In the Azure portal, go to the resource group that you used for bootstrapping.

2. On the resource group used to bootstrap, you should see your Arc-enabled machines. In this example, you see a single machine.

   

Prerequisites

• You have access to Azure Local machines running release 2506 or later. Earlier versions don't support this scenario.

• You have assigned the appropriate permissions to the subscription used for registration. For more information, see Assign required permissions for Azure Local deployment.

• An Arc gateway resource is created in the same subscription used to deploy Azure Local. For more information, see Create the Arc gateway resource in Azure.

• You have reviewed the supported and unsupported scenarios. For more information, see Supported and unsupported scenarios.

• Required endpoints are open in your firewall. For more information, see Azure Local endpoints not redirected.

• Review guidance on handling preinstalled or outdated OS images during Azure Arc registration.

Step 1: Get the Arc gateway ID

• Get Arc gateway ID. To create Azure Arc gateway, see Set up an Azure Arc gateway and get the resource ID of the Arc gateway. This is also referred to as the ArcGatewayID.

  1. In the Azure portal, go to the Arc gateway resource that you created.
  2. On the Overview page, copy the Resource ID. You use this Arc gateway ID later.

  

Step 2: Review script parameters

Review the parameters used in the script:

Step 3: Set parameters

Set the parameters required for the registration script.

Here's an example of how you should change these parameters for the Invoke-AzStackHciArcInitialization initialization script.

#Define the tenant you will use to register your machine as Arc device
$Tenant = "YourTenantID"

#Define the subscription where you want to register your Azure Local machine with Arc.
$Subscription = "yourSubscriptionID" 

#Define the resource group where you want to register your Azure Local machine with Arc.
$RG = "yourResourceGroupName" 

#Define the region to use to register your server as Arc device
#Do not use spaces or capital letters when defining region
$Region = "eastus"

#Define the Arc gateway resource ID from Azure 
$ArcgwId = "/subscriptions/yoursubscriptionid/resourceGroups/yourResourceGroupName/providers/Microsoft.HybridCompute/gateways/yourArcGatewayName" 

#Optional: Define the Azure Resource Manager access token.
# Required only if you want to use token-based authentication instead of device code authentication.
$armTokenResponse = Get-AzAccessToken

# Convert token to string for use in initialization
# Required because Get-AzAccessToken returns SecureString
$ArmAccessToken = [System.Net.NetworkCredential]::new("", $armTokenResponse.Token).Password

# Define the target Azure Local solution version that the node must update to after registering with Azure Arc.
# Example: "12.2602.1002.10"
$TargetSolutionVersion = "<solution-version>" 

Step 4: Run the registration script

To use the Arc gateway feature for Azure Local systems without a proxy, only use the ArcGatewayID parameter.

1. Run the initialization script as follows.

   Invoke-AzStackHciArcInitialization
   -TenantId $Tenant
   -SubscriptionID $Subscription
   -ResourceGroup $RG
   -Region $Region
   -Cloud "AzureCloud"
   -ArcGatewayID $ArcgwId
   # Optional: include only when using token-based authentication
   -ArmAccessToken $ArmAccessToken
   # Optional
   -TargetSolutionVersion $TargetSolutionVersion
   

   Note

   If using -ArmAccessToken, convert the token to a plain text string using: $ArmAccessToken = [System.Net.NetworkCredential]::new("", $armTokenResponse.Token).Password.

2. During the Arc registration process, you must authenticate with your Azure account. The console window displays a code that you must enter in the URL, in order to authenticate. Follow the instructions to complete the authentication process.

   

Handle preinstalled or outdated OS images during Azure Arc registration

During Azure Arc registration, Azure Local verifies whether the OS image is current for its release baseline. If the image is outdated or unsupported, the system automatically detects it during initialization and provides a list of available update versions to select from. You can proactively specify a target solution version using the optional TargetSolutionVersion parameter.

• The update typically takes 40-45 minutes followed by a reboot.

• Rerun Invoke-AzStackHciArcInitialization cmdlet post reboot.

• During the update, the registration status appears as Update: InProgress.

  

Monitor and complete registration

1. If registration times out or the machine reboots, reconnect and check the registration progress using the following commands:

   $status = Get-ArcBootstrapStatus
   $status.Response.Status
   

2. Review the status value:

   • Succeeded: Registration completed successfully after the update.
   • Failed: Rerun registration using a new ARM token or device code flow.
   • If the issue persists, collect logs using Collect-ArcBootstrapSupportLogs and share them for further troubleshooting.

3. After the reboot, rerun the Invoke-AzStackHciArcInitialization cmdlet to continue.

Step 5: Verify the setup is successful

Once the registration is complete, follow these steps to verify that Azure Arc gateway setup is successful.

1. Connect to the first Azure Local machine from your system.

2. Open the Arc gateway log to monitor the endpoints that are being redirected to the Arc gateway and which ones continue using your firewall. You can find the Arc gateway log at: c:\programdata\AzureConnectedMAchineAgent\Log\arcproxy.log.

   

3. To check the Arc agent configuration and verify that it's using the gateway, run the following command:

   C:\program files\AzureConnectedMachineAgent>.\azcmagent show
   

   The values displayed should be as follows:

   1. Agent version is 1.45 or later.

   2. Agent Status should show as Connected.

   3. Using HTTPS Proxy shows as http://localhost:40343when the Arc gateway is enabled.

   4. Upstream Proxy shows your enterprise proxy server and port.

   5. Azure Arc Proxy shows as running when the Arc gateway is enabled.

   The Arc agent using the Arc gateway:

   

4. Additionally, to verify that the setup was done successfully, run the following command:

   C:\program files\AzureConnectedMachineAgent>.\azcmagent check
   

   The response should indicate that the connection.type is set to gateway, and the Reachable column should indicate true for all URLs.

   The Arc agent using the Arc gateway:

   

   You can also audit your gateway traffic by viewing the gateway router logs.

   To view gateway router logs on Windows, run the azcmagent logs command in PowerShell. In the resulting .zip file, the logs are located in the C:\ProgramData\Microsoft\ArcGatewayRouter folder.

If you plan to deploy a few machines per site, use the Configurator app to register your Azure Local machines with Azure Arc gateway.

Prerequisites

Before you begin, make sure that you complete the following prerequisites:

Azure Local machine prerequisites

• Download the Configurator App for Azure Local on a client machine that is connected to the same network as the Azure Local machines.

• Note down:

  • The serial number for each machine.
  • Local administrator credentials to sign into each machine.

Azure prerequisites

• Get Arc gateway ID. To create Azure Arc gateway, see Set up an Azure Arc gateway and get the resource ID of the Arc gateway. This is also referred to as the ArcGatewayID.

  1. In the Azure portal, go to the Arc gateway resource that you created.
  2. On the Overview page, copy the Resource ID. You use this Arc gateway ID later.

  

Step 1: Configure the network and connect to Azure

Follow these steps to configure network settings and connect the machines to Azure. Start this action a few minutes after you turn on the machine.

1. Open the Configurator app. Right-click the Configurator app exe and run as administrator. Wait a few minutes for the app to open up.

   

2. Enter the machine serial number and select Next.

   

3. Sign in to the machine with local administrator credentials.

   

Prerequisites tab

1. On the Prerequisites tab, verify that the minimum requirements are met and then select Next.

   

   If a requirement isn't met, the app displays a warning or errors. You can't proceed if there are errors though warnings are ignored. Resolve the errors before you proceed. For more information, see Troubleshooting registration issues.

   

Basics tab

1. On the Basics tab, configure one network interface that is connected to the internet. Select the Pencil icon to modify network interface settings.

   

2. Provide the interface name, IP allocation as static or DHCP, IP address, subnet, gateway, and preferred DNS servers. Optionally, enter an alternate DNS server.

   

   Important

   Make sure that the IPs you assign are free and not in use.

3. To specify more details, select Enter additional details.

4. On the Additional details page, provide the following inputs and then select Apply.

   

   1. Select ON to enable Remote desktop protocol. Remote desktop protocol is disabled by default.

   2. Select Public endpoint as the connectivity method.

   3. Select a time zone.

   4. Specify a preferred and an alternate NTP server to act as a time server or accept the Default. The default is time.windows.com.

   5. Set the hostname for your machine to what you specified during the preparation of Active Directory. Changing the hostname automatically reboots the system.

5. Select Next on the Basics tab.

Arc agent setup tab

1. On the Arc agent setup tab, provide the following inputs:

   

   1. The Cloud type is populated automatically as Azure.

   2. Enter a Subscription ID to register the machine.

   3. Provide a Resource group name. This resource group contains the machine and system resources that you create.

   4. Specify the Region where you want to create the resources. The region should be the same as the region where you want to deploy the Azure Local instance.

      Important

      Specify the region with spaces removed. For example, specify the East US region as EastUS.

   5. Provide a Tenant ID. The tenant ID is the directory ID of your Microsoft Entra tenant. To get the tenant ID, see Find your Microsoft Entra tenant.

   6. Specify the Arc gateway ID. This is the resource ID of the Arc gateway that you got earlier when completing the Azure prerequisites.

   Important

   Make sure to verify all the inputs before you proceed. Any incorrect inputs here might result in a setup failure.

2. Select Next.

Review and apply tab

1. On the Review and apply tab, verify machine details. To modify any settings, go back. If satisfied with the current settings, select Finish. If you changed the hostname, your machines boot up automatically at this point and you must sign in again.

   

Step 2: Complete registration of machines to Azure

1. Wait for the configuration to complete. First, machine is configured with the basic details followed by registration of the machines to Azure.

2. During the Arc registration process, you must authenticate with your Azure account. The app displays a code that you must enter in the URL, displayed in the app, in order to authenticate. Follow the instructions to complete the authentication process.

   

3. Once the configuration is complete, status for Arc configuration should display Success (Open in Azure portal).

4. Repeat all steps on the other machines until the Arc configuration succeeds. Select the Open in Azure portal link.

Step 3: Verify machines are connected to Arc

1. In the Azure portal, go to the resource group that you used for bootstrapping.

2. On the resource group used to bootstrap, you should see your Arc-enabled machines. In this example, you see a single machine.