|
| 1 | +--- |
| 2 | +title: Install Connected Machine agent using Windows PowerShell DSC |
| 3 | +description: In this article, you learn how to connect machines to Azure using Azure Arc for servers (preview) using Windows PowerShell DSC. |
| 4 | +services: azure-arc |
| 5 | +ms.service: azure-arc |
| 6 | +ms.subservice: azure-arc-servers |
| 7 | +author: mgoedtel |
| 8 | +ms.author: magoedte |
| 9 | +ms.date: 03/12/2020 |
| 10 | +ms.topic: conceptual |
| 11 | +--- |
| 12 | + |
| 13 | +# How to install the Connected Machine agent using Windows PowerShell DSC |
| 14 | + |
| 15 | +Using [Windows PowerShell Desired State Configuration](https://docs.microsoft.com/powershell/scripting/dsc/getting-started/winGettingStarted?view=powershell-7) (DSC), you can automate software installation and configuration for a Windows computer. This article describes how to use DSC to install the Azure Arc for servers Connected Machine agent on hybrid Windows machines. |
| 16 | + |
| 17 | +## Requirements |
| 18 | + |
| 19 | +- Windows PowerShell version 4.0 or higher |
| 20 | + |
| 21 | +- The [AzureConnectedMachineDsc](https://www.powershellgallery.com/packages/AzureConnectedMachineDsc/1.0.1.0) DSC module |
| 22 | + |
| 23 | +- A service principal to connect the machines to Azure Arc for servers non-interactively. Follow the steps under the section [Create a Service Principal for onboarding at scale](onboard-service-principal.md#create-a-service-principal-for-onboarding-at-scale) if you have not created a service principal for Arc for servers already. |
| 24 | + |
| 25 | +## Install the ConnectedMachine DSC module |
| 26 | + |
| 27 | +1. To manually install the module, download the source code and unzip the contents of the project directory to the |
| 28 | +`$env:ProgramFiles\WindowsPowerShell\Modules folder`. Or, run the following command to install from the PowerShell gallery using PowerShellGet (in PowerShell 5.0): |
| 29 | + |
| 30 | + ```powershell |
| 31 | + Find-Module -Name AzureConnectedMachineDsc -Repository PSGallery | Install-Module |
| 32 | + ``` |
| 33 | + |
| 34 | +2. To confirm installation, run the following command and ensure you see the Azure Connected Machine DSC resources available. |
| 35 | + |
| 36 | + ```powershell |
| 37 | + Get-DscResource -Module AzureConnectedMachineDsc |
| 38 | + ``` |
| 39 | +
|
| 40 | + In the output, you should see something similar to the following: |
| 41 | +
|
| 42 | +  |
| 43 | +
|
| 44 | +## Install the agent and connect to Azure |
| 45 | +
|
| 46 | +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](onboard-portal.md) article. |
| 47 | +
|
| 48 | +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](onboard-portal.md#configure-the-agent-proxy-setting). 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](https://www.powershellgallery.com/packages/ComputerManagementDsc/6.0.0.0) module. |
| 49 | +
|
| 50 | +>[!NOTE] |
| 51 | +>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. |
| 52 | +> |
| 53 | +
|
| 54 | +Configuration documents (MOF files) can be applied to the machine using the `Start-DscConfiguration` cmdlet. |
| 55 | +
|
| 56 | +The following are the parameters you pass to the PowerShell script to use. |
| 57 | +
|
| 58 | +- `TenantId`: The unique identifier (GUID) that represents your dedicated instance of Azure AD. |
| 59 | +
|
| 60 | +- `SubscriptionId`: The subscription ID (GUID) of your Azure subscription that you want the machines in. |
| 61 | +
|
| 62 | +- `ResourceGroup`: The resource group name where you want your connected machines to belong to. |
| 63 | +
|
| 64 | +- `Location`: See [supported Azure regions](overview.md#supported-regions). This location can be the same or different, as the resource group's location. |
| 65 | +
|
| 66 | +- `Tags`: String array of tags that should be applied to the connected machine resource. |
| 67 | +
|
| 68 | +- `Credential`: A PowerShell credential object with the **ApplicationId** and **password** used to register machines at scale using a [service principal](onboard-service-principal.md). |
| 69 | +
|
| 70 | +1. In a PowerShell console, navigate to the folder where you saved the `.ps1` file. |
| 71 | +
|
| 72 | +2. Run the following PowerShell commands to compile the MOF document (for information about compiling DSC configurations, see [DSC Configurations](https://docs.microsoft.com/powershell/scripting/dsc/configurations/configurations?view=powershell-7): |
| 73 | +
|
| 74 | + ```powershell |
| 75 | + .\`AzureConnectedMachineAgent.ps1 -TenantId <TenantId GUID> -SubscriptionId <SubscriptionId GUID> -ResourceGroup '<ResourceGroupName>' -Location '<LocationName>' -Tags '<Tag>' -Credential <psCredential> |
| 76 | + ``` |
| 77 | +
|
| 78 | +3. This will create a `localhost.mof file` in a new folder named `C:\dsc`. |
| 79 | +
|
| 80 | +After you install the agent and configure it to connect to Azure Arc for servers (preview), go to the Azure portal to verify that the server has been successfully connected. View your machines in the [Azure portal](https://aka.ms/hybridmachineportal). |
| 81 | +
|
| 82 | +## Adding to existing configurations |
| 83 | +
|
| 84 | +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. |
| 85 | +
|
| 86 | +The [CompsiteResource](https://www.powershellgallery.com/packages/compositeresource/0.4.0) module from the PowerShell Gallery can be used to create a [composite resource](https://docs.microsoft.com/powershell/scripting/dsc/resources/authoringResourceComposite?view=powershell-7) of the example configuration, to further simplify combining configurations. |
| 87 | +
|
| 88 | +## Next steps |
| 89 | +
|
| 90 | +- Learn how to manage your machine using [Azure Policy](../../governance/policy/overview.md), for such things as VM [guest configuration](../../governance/policy/concepts/guest-configuration.md), verifying the machine is reporting to the expected Log Analytics workspace, enable monitoring with [Azure Monitor with VMs](../../azure-monitor/insights/vminsights-enable-at-scale-policy.md), and much more. |
| 91 | +
|
| 92 | +- Learn more about the [Log Analytics agent](../../azure-monitor/platform/log-analytics-agent.md). The Log Analytics agent for Windows and Linux is required when you want to proactively monitor the OS and workloads running on the machine, manage it using Automation runbooks or solutions like Update Management, or use other Azure services like [Azure Security Center](../../security-center/security-center-intro.md). |
0 commit comments