Edit

Share via

Connect hybrid machines to Azure using a deployment script

  • Article

You can enable Azure Arc-enabled servers for one or a small number of Windows or Linux machines in your environment by performing a set of steps manually. Or you can use an automated method by running a template script that we provide. This script automates the download and installation of both agents.

This method requires that you have administrator permissions on the machine to install and configure the agent. On Linux, by using the root account, and on Windows, you are member of the Local Administrators group.

Before you get started, be sure to review the prerequisites and verify that your subscription and resources meet the requirements. For information about supported regions and other related considerations, see supported Azure regions.

If you don't have an Azure subscription, create a free account before you begin.

Note

Follow best security practices and avoid using an Azure account with Owner access to onboard servers. Instead, use an account that only has the Azure Connected Machine onboarding or Azure Connected Machine resource administrator role assignment. See Azure Identity Management and access control security best practices for more information.

Automatic connection for SQL Server

When you connect a Windows or Linux server to Azure Arc that also has Microsoft SQL Server installed, the SQL Server instances will automatically be connected to Azure Arc as well. SQL Server enabled by Azure Arc provides a detailed inventory and additional management capabilities for your SQL Server instances and databases. As part of the connection process, an extension is deployed to your Azure Arc-enabled server and new roles will be applied to your SQL Server and databases. If you don't want to automatically connect your SQL Servers to Azure Arc, you can opt out by adding a tag to the Windows or Linux server with the name ArcSQLServerExtensionDeployment and value Disabled when it's connected to Azure Arc.

For more information, see Manage automatic connection for SQL Server enabled by Azure Arc.

Generate the installation script from the Azure portal

Use the Azure portal to create a script that automates the agent download and installation and establishes the connection with Azure Arc. To complete the process, perform the following steps:

  1. From your browser, sign in to the Azure portal.

  2. On the Azure Arc - Machines page, select Add/Create at the upper left, and then select Add a machine from the drop-down menu.

  3. On the Add servers with Azure Arc page, under the Add a single server tile, select Generate script.

  4. On the Basics page, provide the following:

    1. In the Project Details section, select the Subscription and Resource group the machine will be managed from.
    2. In the Region drop-down list, select the Azure region to store the servers metadata.
    3. In the Operating system drop-down list, select the operating system that the script is configured to run on.
    4. In the Connectivity method section, choose how the Azure Connected Machine agent should connect to the internet:
      • Public endpoint
      • Proxy server—If the machine is communicating through a proxy server, enter the proxy server IP address or the name and port number that the machine will use in the format http://<proxyURL>:<proxyport>.
      • Private endpoint—If the machine is communicating through a private endpoint, select an existing private link scope and endpoint or create a new one.
    5. In the Automanage machine best practices section, you may enable automanage if you want to onboard and configure best practice services like Machine configuration and Insights, based on your server needs.
    6. Select Next to go to the Tags page.

  5. On the Tags page, review the default Physical location tags suggested and enter a value, or specify one or more Custom tags to support your standards.

  6. Select Next to Download and run script page.

  7. On the Download and run script page, review the summary information, and then select Download. If you still need to make changes, select Previous.

Install and validate the agent on Windows

Install manually

You can install the Connected Machine agent manually by running the Windows Installer package AzureConnectedMachineAgent.msi. You can download the latest version of the Windows agent Windows Installer package from the Microsoft Download Center.

Note

  • To install or uninstall the agent, you must have Administrator permissions.
  • You must first download and copy the Installer package to a folder on the target server, or from a shared network folder. If you run the Installer package without any options, it starts a setup wizard that you can follow to install the agent interactively.

If the machine needs to communicate through a proxy server to the service, after you install the agent you need to run a command that's described in the steps below. This command sets the proxy server system environment variable https_proxy. Using this configuration, the agent communicates through the proxy server using the HTTP protocol.

If you are unfamiliar with the command-line options for Windows Installer packages, review Msiexec standard command-line options and Msiexec command-line options.

For example, run the installation program with the /? parameter to review the help and quick reference option.

msiexec.exe /i AzureConnectedMachineAgent.msi /?

  1. To install the agent silently and create a setup log file in the C:\Support\Logs folder that exist, run the following command.

    msiexec.exe /i AzureConnectedMachineAgent.msi /qn /l*v "C:\Support\Logs\Azcmagentsetup.log"

    If the agent fails to start after setup is finished, check the logs for detailed error information. The log directory is %ProgramData%\AzureConnectedMachineAgent\log.

  2. If the machine needs to communicate through a proxy server, to set the proxy server environment variable, run the following command:

    [Environment]::SetEnvironmentVariable("https_proxy", "http://{proxy-url}:{proxy-port}", "Machine")
$env:https_proxy = [System.Environment]::GetEnvironmentVariable("https_proxy","Machine")
# For the changes to take effect, the agent service needs to be restarted after the proxy environment variable is set.
Restart-Service -Name himds

    For more information, see Agent-specific proxy configuration.

  3. After installing the agent, you need to configure it to communicate with the Azure Arc service by running the following command:

    "%ProgramFiles%\AzureConnectedMachineAgent\azcmagent.exe" connect --resource-group "resourceGroupName" --tenant-id "tenantID" --location "regionName" --subscription-id "subscriptionID"

Install with the scripted method

  1. Log in to the server.

  2. Open an elevated PowerShell command prompt.

    Note

    The script only supports running from a 64-bit version of Windows PowerShell.

  3. Change to the folder or share that you copied the script to, and execute it on the server by running the ./OnboardingScript.ps1 script.

If the agent fails to start after setup is finished, check the logs for detailed error information. The log directory is %ProgramData%\AzureConnectedMachineAgent\log.

Install and validate the agent on Linux

The Connected Machine agent for Linux is provided in the preferred package format for the distribution (.RPM or .DEB) that's hosted in the Microsoft package repository. The shell script bundle Install_linux_azcmagent.sh performs the following actions:

  • Configures the host machine to download the agent package from packages.microsoft.com.

  • Installs the Hybrid Resource Provider package.

Optionally, you can configure the agent with your proxy information by including the --proxy "{proxy-url}:{proxy-port}" parameter. Using this configuration, the agent communicates through the proxy server using the HTTP protocol.

The script also contains logic to identify the supported and unsupported distributions, and it verifies the permissions that are required to perform the installation.

The following example downloads the agent and installs it:

# Download the installation package.
wget https://aka.ms/azcmagent -O ~/Install_linux_azcmagent.sh

# Install the Azure Connected Machine agent.
bash ~/Install_linux_azcmagent.sh

  1. To download and install the agent, run the following commands. If your machine needs to communicate through a proxy server to connect to the internet, include the --proxy parameter.

    # Download the installation package.
wget https://aka.ms/azcmagent -O ~/Install_linux_azcmagent.sh

# Install the AZure Connected Machine agent.
bash ~/Install_linux_azcmagent.sh --proxy "{proxy-url}:{proxy-port}"

  2. After installing the agent, you need to configure it to communicate with the Azure Arc service by running the following command:

    azcmagent connect --resource-group "resourceGroupName" --tenant-id "tenantID" --location "regionName" --subscription-id "subscriptionID" --cloud "cloudName"
if [ $? = 0 ]; then echo "\033[33mTo view your onboarded server(s), navigate to https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.HybridCompute%2Fmachines\033[m"; fi

Install with the scripted method

  1. Log in to the server with an account that has root access.

  2. Change to the folder or share that you copied the script to, and execute it on the server by running the ./OnboardingScript.sh script.

If the agent fails to start after setup is finished, check the logs for detailed error information. The log directory is /var/opt/azcmagent/log.

Verify the connection with Azure Arc

After you install the agent and configure it to connect to Azure Arc-enabled servers, go to the Azure portal to verify that the server has successfully connected. View your machines in the Azure portal.

A successful server connection

Next steps