Skip to content

Commit 0f60c42

Browse files
v-dihansv-dihans
authored
Merge pull request #114293 from MGoedtel/task1698590
new agent overview article
2 parents 1fa6e29 + 528c87f commit 0f60c42

File tree

6 files changed

+260
-131
lines changed

6 files changed

+260
-131
lines changed

‎articles/azure-arc/servers/agent-overview.md

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
---
2+
title: Overview of the Connected Machine Windows agent
3+
description: This article provides a detailed overview of the Azure Arc for servers agent available which support monitoring virtual machines hosted in hybrid environments.
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: 05/18/2020
10+
ms.topic: conceptual
11+
---
12+
13+
# Overview of Azure Arc for servers agent
14+
15+
The Azure Arc for servers Connected Machine agent enables you to manage your Windows and Linux machines hosted outside of Azure on your corporate network or other cloud provider. This article provides a detailed overview of the agent, system and network requirements, and the different deployment methods.
16+
17+
## Download agents
18+
19+
You can download the Azure Connected Machine agent package for Windows and Linux from the locations listed below.
20+
21+
- [Windows agent Windows Installer package](https://aka.ms/AzureConnectedMachineAgent) from the Microsoft Download Center.
22+
- Linux agent package is distributed from Microsoft's [package repository](https://packages.microsoft.com/) using the preferred package format for the distribution (.RPM or .DEB).
23+
24+
>[!NOTE]
25+
>During this preview, only one package has been released, which is suitable for Ubuntu 16.04 or 18.04.
26+
27+
The Azure Connected Machine agent for Windows and Linux can be upgraded to the latest release manually or automatically depending on your requirements. For more information, see [here](manage-agent.md).
28+
29+
## Windows agent installation details
30+
31+
The Connected Machine agent for Windows can be installed by using one of the following three methods:
32+
33+
* Double-click the file `AzureConnectedMachineAgent.msi`.
34+
* Manually by running the Windows Installer package `AzureConnectedMachineAgent.msi` from the Command shell.
35+
* From a PowerShell session using a scripted method.
36+
37+
After installing the Connected Machine agent for Windows, the following additional system-wide configuration changes are applied.
38+
39+
* The following installation folders are created during setup.
40+
41+
|Folder |Description |
42+
|-------|------------|
43+
|C:\Program Files\AzureConnectedMachineAgent |Default installation path containing the agent support files.|
44+
|%ProgramData%\AzureConnectedMachineAgent |Contains the agent configuration files.|
45+
|%ProgramData%\AzureConnectedMachineAgent\Tokens |Contains the acquired tokens.|
46+
|%ProgramData%\AzureConnectedMachineAgent\Config |Contains the agent configuration file `agentconfig.json` recording its registration information with the service.|
47+
|%ProgramData%\GuestConfig |Contains the (applied) Azure policies related files.|
48+
49+
* The following Windows services are created on the target machine during installation of the agent.
50+
51+
|Service name |Display name |Process name |Description |
52+
|-------------|-------------|-------------|------------|
53+
|himds |Azure Hybrid Instance Metadata Service |himds.exe |This service implements the Azure Instance Metadata service (IMDS) to track the machine.|
54+
|DscService |Guest Configuration Service |dsc_service.exe |This is the Desired State Configuration (DSC v2) codebase used inside Azure to implement In-Guest Policy.|
55+
56+
* The following environmental variables are created during agent installation.
57+
58+
|Name |Default value |Description |
59+
|-----|--------------|------------|
60+
|IDENTITY_ENDPOINT |http://localhost:40342/metadata/identity/oauth2/token ||
61+
|IMDS_ENDPOINT |http://localhost:40342 ||
62+
63+
* There are four log files available for troubleshooting. They are described in the following table.
64+
65+
|Log |Description |
66+
|----|------------|
67+
|%ProgramData%\AzureConnectedMachineAgent\Log\himds.log |Records details of the agents (himds) service and interaction with Azure.|
68+
|%ProgramData%\AzureConnectedMachineAgent\Log\azcmagent.log |Contains the output of the azcmagent tool commands, when the verbose (-v) argument is used.|
69+
|%ProgramData%\GuestConfig\gc_agent_logs\gc_agent.log |Records details of the DSC service activity,<br> in particular the connectivity between the himds service and Azure Policy.|
70+
|%ProgramData%\GuestConfig\gc_agent_logs\gc_agent_telemetry.txt |Records details about DSC service telemetry and verbose logging.|
71+
72+
* The local security group **Hybrid agent extension applications** is created.
73+
74+
* During uninstall of the agent, the following artifacts are not removed.
75+
76+
* C:\Program Files\AzureConnectedMachineAgent\Logs
77+
* %ProgramData%\AzureConnectedMachineAgent and subdirectories
78+
* %ProgramData%\GuestConfig
79+
80+
## Linux agent installation details
81+
82+
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](https://packages.microsoft.com/). The agent is installed and configured with the shell script bundle [Install_linux_azcmagent.sh](https://aka.ms/azcmagent).
83+
84+
After installing the Connected Machine agent for Linux, the following additional system-wide configuration changes are applied.
85+
86+
* The following installation folders are created during setup.
87+
88+
|Folder |Description |
89+
|-------|------------|
90+
|/var/opt/azcmagent/ |Default installation path containing the agent support files.|
91+
|/opt/azcmagent/ |
92+
|/opt/DSC/ |
93+
|/var/opt/azcmagent/tokens |Contains the acquired tokens.|
94+
|/var/lib/GuestConfig |Contains the (applied) Azure policies related files.|
95+
96+
* The following daemons are created on the target machine during installation of the agent.
97+
98+
|Service name |Display name |Process name |Description |
99+
|-------------|-------------|-------------|------------|
100+
|himdsd.service |Azure Hybrid Instance Metadata Service |/opt/azcmagent/bin/himds |This service implements the Azure Instance Metadata service (IMDS) to track the machine.|
101+
|dscd.service |Guest Configuration Service |/opt/DSC/dsc_linux_service |This is the Desired State Configuration (DSC v2) codebase used inside Azure to implement In-Guest Policy.|
102+
103+
* There are four log files available for troubleshooting. They are described in the following table.
104+
105+
|Log |Description |
106+
|----|------------|
107+
|/var/opt/azcmagent/log/himds.log |Records details of the agents (himds) service and interaction with Azure.|
108+
|/var/opt/azcmagent/log/azcmagent.log |Contains the output of the azcmagent tool commands, when the verbose (-v) argument is used.|
109+
|/opt/logs/dsc.log |Records details of the DSC service activity,<br> in particular the connectivity between the himds service and Azure Policy.|
110+
|/opt/logs/dsc.telemetry.txt |Records details about DSC service telemetry and verbose logging.|
111+
112+
* The following environmental variables are created during agent installation. These variables are set in `/lib/systemd/system.conf.d/azcmagent.conf`.
113+
114+
|Name |Default value |Description |
115+
|-----|--------------|------------|
116+
|IDENTITY_ENDPOINT |http://localhost:40342/metadata/identity/oauth2/token ||
117+
|IMDS_ENDPOINT |http://localhost:40342 ||
118+
119+
* During uninstall of the agent, the following artifacts are not removed.
120+
121+
* /var/opt/azcmagent
122+
* /opt/logs
123+
124+
## Prerequisites
125+
126+
### Supported operating systems
127+
128+
The following versions of the Windows and Linux operating system are officially supported for the Azure Connected Machine agent:
129+
130+
- Windows Server 2012 R2 and higher (including Windows Server Core)
131+
- Ubuntu 16.04 and 18.04
132+
- CentOS Linux 7
133+
- SUSE Linux Enterprise Server (SLES) 15
134+
- Red Hat Enterprise Linux (RHEL) 7
135+
- Amazon Linux 2
136+
137+
>[!NOTE]
138+
>This preview release of the Connected Machine agent for Windows only supports Windows Server configured to use the English language.
139+
>
140+
141+
### Required permissions
142+
143+
- To onboard machines, you are a member of the **Azure Connected Machine Onboarding** role.
144+
145+
- To read, modify, re-onboard, and delete a machine, you are a member of the **Azure Connected Machine Resource Administrator** role.
146+
147+
### Azure subscription and service limits
148+
149+
Before configuring your machines with Azure Arc for servers (preview), you should review the Azure Resource Manager [subscription limits](../../azure-resource-manager/management/azure-subscription-service-limits.md#subscription-limits) and [resource group limits](../../azure-resource-manager/management/azure-subscription-service-limits.md#resource-group-limits) to plan for the number of machines to be connected.
150+
151+
## TLS 1.2 protocol
152+
153+
To ensure the security of data in transit to Azure, we strongly encourage you to configure machine to use Transport Layer Security (TLS) 1.2. Older versions of TLS/Secure Sockets Layer (SSL) have been found to be vulnerable and while they still currently work to allow backwards compatibility, they are **not recommended**.
154+
155+
|Platform/Language | Support | More Information |
156+
| --- | --- | --- |
157+
|Linux | Linux distributions tend to rely on [OpenSSL](https://www.openssl.org) for TLS 1.2 support. | Check the [OpenSSL Changelog](https://www.openssl.org/news/changelog.html) to confirm your version of OpenSSL is supported.|
158+
| Windows Server 2012 R2 and higher | Supported, and enabled by default. | To confirm that you are still using the [default settings](https://docs.microsoft.com/windows-server/security/tls/tls-registry-settings).|
159+
160+
### Networking configuration
161+
162+
The Connected Machine agent for Linux and Windows communicates outbound securely to Azure Arc over TCP port 443. If the machine connects through a firewall or proxy server to communicate over the Internet, review requirements below to understand the network configuration requirements.
163+
164+
If outbound connectivity is restricted by your firewall or proxy server, make sure the URLs listed below are not blocked. If you only allow the IP ranges or domain names required for the agent to communicate with the service, you must also allow access to the following Service Tags and URLs.
165+
166+
Service Tags:
167+
168+
- AzureActiveDirectory
169+
- AzureTrafficManager
170+
171+
URLs:
172+
173+
| Agent resource | Description |
174+
|---------|---------|
175+
|management.azure.com|Azure Resource Manager|
176+
|login.windows.net|Azure Active Directory|
177+
|dc.services.visualstudio.com|Application Insights|
178+
|agentserviceapi.azure-automation.net|Guest Configuration|
179+
|*-agentservice-prod-1.azure-automation.net|Guest Configuration|
180+
|*.his.arc.azure.com|Hybrid Identity Service|
181+
182+
For a list of IP addresses for each service tag/region, see the JSON file - [Azure IP Ranges and Service Tags – Public Cloud](https://www.microsoft.com/download/details.aspx?id=56519). Microsoft publishes weekly updates containing each Azure Service and the IP ranges it uses. For more information, review [Service tags](https://docs.microsoft.com/azure/virtual-network/security-overview#service-tags).
183+
184+
The URLs in the previous table are required in addition to the Service Tag IP address range information because the majority of services do not currently have a Service Tag registration. As such, the IP addresses are subject to change. If IP address ranges are required for your firewall configuration, then the **AzureCloud** Service Tag should be used to allow access to all Azure services. Do not disable security monitoring or inspection of these URLs, allow them as you would other Internet traffic.
185+
186+
### Register Azure resource providers
187+
188+
Azure Arc for servers (preview) depends on the following Azure resource providers in your subscription in order to use this service:
189+
190+
- **Microsoft.HybridCompute**
191+
- **Microsoft.GuestConfiguration**
192+
193+
If they are not registered, you can register them using the following commands:
194+
195+
Azure PowerShell:
196+
197+
```azurepowershell-interactive
198+
Login-AzAccount
199+
Set-AzContext -SubscriptionId [subscription you want to onboard]
200+
Register-AzResourceProvider -ProviderNamespace Microsoft.HybridCompute
201+
Register-AzResourceProvider -ProviderNamespace Microsoft.GuestConfiguration
202+
```
203+
204+
Azure CLI:
205+
206+
```azurecli-interactive
207+
az account set --subscription "{Your Subscription Name}"
208+
az provider register --namespace 'Microsoft.HybridCompute'
209+
az provider register --namespace 'Microsoft.GuestConfiguration'
210+
```
211+
212+
You can also register the resource providers in the Azure portal by following the steps under [Azure portal](../../azure-resource-manager/management/resource-providers-and-types.md#azure-portal).
213+
214+
215+
## Installation and configuration
216+
217+
Connecting machines in your hybrid environment directly with Azure can be accomplished using different methods depending on your requirements. The following table highlights each method to determine which works best for your organization.
218+
219+
| Method | Description |
220+
|--------|-------------|
221+
| Interactively | Manually install the agent on a single or small number of machines following the steps in [Connect machines from Azure portal](onboard-portal.md).<br> From the Azure portal, you can generate a script and execute it on the machine to automate the install and configuration steps of the agent.|
222+
| At scale | Install and configure the agent for multiple machines following the [Connect machines using a Service Principal](onboard-service-principal.md).<br> This method creates a service principal to connect machines non-interactively.|
223+
| At scale | Install and configure the agent for multiple machines following the method [Using Windows PowerShell DSC](onboard-dsc.md).<br> This method uses a service principal to connect machines non-interactively with PowerShell DSC. |
224+
225+
## Next steps
226+
227+
To begin evaluating Azure Arc for servers (preview), follow the article [Connect hybrid machines to Azure from the Azure portal](onboard-portal.md).

‎articles/azure-arc/servers/manage-agent.md

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ ms.service: azure-arc
66
ms.subservice: azure-arc-servers
77
author: mgoedtel
88
ms.author: magoedte
9-
ms.date: 04/29/2020
9+
ms.date: 05/18/2020
1010
ms.topic: conceptual
1111
---
1212

@@ -23,11 +23,19 @@ The Azure Connected Machine agent for Windows and Linux can be upgraded to the l
2323
| Windows | Manually<br> Windows Update |
2424
| Ubuntu | [Apt](https://help.ubuntu.com/lts/serverguide/apt.html) |
2525
| SUSE Linux Enterprise Server | [zypper](https://en.opensuse.org/SDB:Zypper_usage_11.3) |
26-
| RedHat Enterprise, Amazon, CentOS Linux | [yum](https://wiki.centos.org/PackageManagement/Yum) |
26+
| RedHat Enterprise, Amazon, CentOS Linux | [yum](https://wiki.centos.org/PackageManagement/Yum) |
2727

2828
### Windows agent
2929

30-
To update the agent on a Windows machine to the latest version, the agent is available from Microsoft Update and can be deployed using your existing software update management process. It can also be run manually from the Command Prompt, from a script or other automation solution, or from the UI wizard by executing `AzureConnectedMachine.msi`.
30+
Update package for the Connected Machine agent for Windows is available from:
31+
32+
* Microsoft Update
33+
34+
* [Microsoft Update Catalog](https://www.catalog.update.microsoft.com/Home.aspx)
35+
36+
* [Windows agent Windows Installer package](https://aka.ms/AzureConnectedMachineAgent) from the Microsoft Download Center.
37+
38+
The agent can be upgraded following a variety of methods to support your software update management process. Outside of obtaining from Microsoft Update, you can download and run manually from the Command Prompt, from a script or other automation solution, or from the UI wizard by executing `AzureConnectedMachine.msi`.
3139

3240
> [!NOTE]
3341
> * To upgrade the agent, you must have *Administrator* permissions.
@@ -55,7 +63,9 @@ The Setup Wizard discovers if a previous version exists, and then it automatical
5563
5664
### Linux agent
5765
58-
To update the agent on a Linux machine to the latest version, it involves two commands. One command to update the local package index with the list of latest available packages from the repositories, and one command to upgrade the local package.
66+
To update the agent on a Linux machine to the latest version, it involves two commands. One command to update the local package index with the list of latest available packages from the repositories, and one command to upgrade the local package.
67+
68+
You can download the latest agent package from Microsoft's [package repository](https://packages.microsoft.com/).
5969
6070
> [!NOTE]
6171
> To upgrade the agent, you must have *root* access permissions or with an account that has elevated rights using Sudo.
@@ -166,7 +176,7 @@ To disconnect with your elevated logged-on credentials (interactive), run the fo
166176
167177
This parameter reconnects the already registered or connected machine with Azure Arc for servers (preview). This may be necessary if the machine has been turned off, at least 45 days, for its certificate to expire. This parameter uses the authentication options provided to retrieve new credentials corresponding to the Azure Resource Manager resource representing this machine.
168178
169-
This command requires higher privileges than the [Azure Connected Machine Onboarding](overview.md#required-permissions) role.
179+
This command requires higher privileges than the [Azure Connected Machine Onboarding](agent-overview.md#required-permissions) role.
170180
171181
To reconnect using a service principal, run the following command:
172182
@@ -202,7 +212,7 @@ Both of the following methods remove the agent, but they do not remove the *C:\P
202212
#### Uninstall from the command line
203213
204214
To uninstall the agent manually from the Command Prompt or to use an automated method, such as a script, you can use the following example. First you need to retrieve the product code, which is a GUID that is the principal identifier of the application package, from the operating system. The uninstall is performed by using the Msiexec.exe command line - `msiexec /x {Product Code}`.
205-
215+
206216
1. Open the Registry Editor.
207217
208218
2. Under registry key `HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall`, look for and copy the product code GUID.

0 commit comments

Comments
 (0)