How to install the Connected Machine agent using Windows PowerShell DSC
Using Windows PowerShell Desired State Configuration (DSC), you can automate software installation and configuration for a Windows computer. This article describes how to use DSC to install the Azure Arc-enabled servers Connected Machine agent on hybrid Windows machines.
Windows PowerShell version 4.0 or higher
The AzureConnectedMachineDsc DSC module
A service principal to connect the machines to Azure Arc-enabled servers non-interactively. Follow the steps under the section Create a Service Principal for onboarding at scale if you have not created a service principal for Arc-enabled servers already.
Install the ConnectedMachine DSC module
To manually install the module, download the source code and unzip the contents of the project directory to the
$env:ProgramFiles\WindowsPowerShell\Modules folder. Or, run the following command to install from the PowerShell gallery using PowerShellGet (in PowerShell 5.0):
Find-Module -Name AzureConnectedMachineDsc -Repository PSGallery | Install-Module
To confirm installation, run the following command and ensure you see the Azure Connected Machine DSC resources available.
Get-DscResource -Module AzureConnectedMachineDsc
In the output, you should see something similar to the following:
Install the agent and connect to Azure
The resources in this module are designed to manage the Azure Connected Machine Agent configuration. Also included is a PowerShell script
AzureConnectedMachineAgent.ps1, found in the
AzureConnectedMachineDsc\examples folder. It uses community resources to automate the download and installation, and establish a connection with Azure Arc. This script performs similar steps described in the Connect hybrid machines to Azure from the Azure portal article.
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 here. This sets the proxy server system environment variable
https_proxy. Instead of running the command manually, you can perform this step with DSC by using the ComputeManagementDsc module.
To allow DSC to run, Windows needs to be configured to receive PowerShell remote commands even when you're running a localhost configuration. To easily configure your environment correctly, just run
Set-WsManQuickConfig -Force in an elevated PowerShell Terminal.
Configuration documents (MOF files) can be applied to the machine using the
The following are the parameters you pass to the PowerShell script to use.
TenantId: The unique identifier (GUID) that represents your dedicated instance of Azure AD.
SubscriptionId: The subscription ID (GUID) of your Azure subscription that you want the machines in.
ResourceGroup: The resource group name where you want your connected machines to belong to.
Location: See supported Azure regions. This location can be the same or different, as the resource group's location.
Tags: String array of tags that should be applied to the connected machine resource.
Credential: A PowerShell credential object with the ApplicationId and password used to register machines at scale using a service principal.
In a PowerShell console, navigate to the folder where you saved the
Run the following PowerShell commands to compile the MOF document (for information about compiling DSC configurations, see DSC Configurations:
.\`AzureConnectedMachineAgent.ps1 -TenantId <TenantId GUID> -SubscriptionId <SubscriptionId GUID> -ResourceGroup '<ResourceGroupName>' -Location '<LocationName>' -Tags '<Tag>' -Credential <psCredential>
This will create a
localhost.mof filein a new folder named
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 been successfully connected. View your machines in the Azure portal.
Adding to existing configurations
This resource can be added to existing DSC configurations to represent an end-to-end configuration for a machine. For example, you might wish to add this resource to a configuration that sets secure operating system settings.
Troubleshooting information can be found in the Troubleshoot Connected Machine agent guide.
Review the Planning and deployment guide to plan for deploying Azure Arc-enabled servers at any scale and implement centralized management and monitoring.
Learn how to manage your machine using Azure Policy, for such things as VM guest configuration, verifying the machine is reporting to the expected Log Analytics workspace, enable monitoring with VM insights, and much more.