Skip to content

Commit 70ad912

Browse files
rwestMSFTmdrakiburrahmanMikeRayMSFT
authored
Add FAQ to Arc Agent extension article [PLEASE SQUASH!] (#36035)
* Add FAQ to Arc Agent extension article * Add sections on feature usage and table management for Arc SQL Extension * Clarify table recreation process in agent extension documentation * Refine documentation for Azure SQL Server extension system objects, enhancing clarity on managed items and table behavior. * Clarify connection behavior in agent extension documentation for least privilege mode * Fix formatting in agent extension documentation by removing trailing comma from tables list --------- Co-authored-by: Raki <46581776+mdrakiburrahman@users.noreply.github.com> Co-authored-by: Mike Ray <15928587+MikeRayMSFT@users.noreply.github.com>
1 parent dcaa14d commit 70ad912

File tree

1 file changed

+71
-20
lines changed

1 file changed

+71
-20
lines changed

‎docs/sql-server/azure-arc/agent-extension-files.md‎

Lines changed: 71 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,60 @@
11
---
2-
title: Azure extension for SQL Server system objects
2+
title: Azure Extension for SQL Server System Objects
33
description: Lists system objects - files, registry keys, and tables deployed and managed by the Azure extension for SQL Server.
44
author: MikeRayMSFT
55
ms.author: mikeray
66
ms.reviewer: nikitatakru
7-
ms.date: 04/26/2024
7+
ms.date: 12/08/2025
88
ms.topic: reference
99
---
1010

1111
# Azure extension for SQL Server system objects
1212

1313
[!INCLUDE [SQL Server](../../includes/applies-to-version/sqlserver.md)]
1414

15-
This article lists system objects - files, registry keys, Windows services and tables deployed and managed by the Azure extension for SQL Server.
15+
This article lists system objects that Azure extension for SQL Server deploys and manages. They include:
16+
17+
- Files
18+
- Registry keys
19+
- Windows services
20+
- Tables
1621

1722
## Windows server files
1823

1924
| Path | Description |
20-
| :----- | :----- |
25+
| --- | --- |
2126
| `%ProgramFiles%\AzureConnectedMachineAgent\*` | `azcmagent` CLI and instance metadata service executables |
2227
| `%ProgramFiles%\AzureConnectedMachineAgent\GCArcService\GC\*` | Extension service executables |
2328
| `%ProgramData%\AzureConnectedMachineAgent\*` | Configuration, log, and identity token files for `azcmagent` CLI and instance metadata service |
24-
| `%ProgramData%\Application Data\Microsoft\Crypto\RSA\MachineKeys` | Windows certificate private keys |
29+
| `%ProgramData%\Application Data\Microsoft\Crypto\RSA\MachineKeys` | Windows certificate private keys |
2530

2631
## SQL Server files
2732

2833
| Path | Description & notes |
29-
| :----- | :----- |
30-
| `%ProgramFiles%\Sql Server Extension\*` | Extension program files |
34+
| --- | --- |
35+
| `%ProgramFiles%\SQL Server Extension\*` | Extension program files |
3136
| `%SYSTEMDRIVE%\Packages\Plugins\Microsoft.AzureData.WindowsAgent.SQLServer\<extension_version>\*` | Extension executables |
3237
| `%SYSTEMDRIVE%\Windows\system32\extensionUpload\*` | Usage files |
3338
| `C:\Windows\System32\Tasks\Microsoft\SqlServerExtension` | XML for scheduled task for providing privileges |
34-
| `C:\Windows\ServiceProfiles\SqlServerExtension\AppData\Local\Microsoft SQL Server Extension Agent\*` | When configured for [least privilege](configure-least-privilege.md) <br/><br/> Feature application |
35-
| `C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft SQL Server Extension Agent\*`| When not configured for [least privilege](configure-least-privilege.md) <br/></br> Feature application |
39+
| `C:\Windows\ServiceProfiles\SqlServerExtension\AppData\Local\Microsoft SQL Server Extension Agent\*` | When configured for [least privilege](configure-least-privilege.md)<br /><br />Feature application |
40+
| `C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft SQL Server Extension Agent\*` | When not configured for [least privilege](configure-least-privilege.md)<br /><br />Feature application |
3641

37-
> [!NOTE]
42+
> [!NOTE]
3843
> [!INCLUDE [least-privilege-default](includes/least-privilege-default.md)]
3944
4045
## Windows Services
4146

4247
| Service name | Display name | Process name | Description |
43-
| :----- | :----- | :----- | :----- |
44-
| SqlServerExtension |Microsoft Sql Server Extension Service | SqlServerExtension.exe | Connects your SQL Server instance to Azure. |
45-
| himds | Azure Hybrid Instance Metadata Service | `himds.exe` | Synchronizes metadata with Azure and hosts a local REST API for extensions and applications to access the metadata and request Microsoft Entra managed identity tokens |
46-
| GCArcService | Machine configuration Arc Service | `gc_arc_service.exe` (gc_service.exe earlier than version 1.36) | Audits and enforces Azure machine configuration policies on the machine. |
47-
| ExtensionService | Machine configuration Extension Service | `gc_extension_service.exe` (gc_service.exe earlier than version 1.36) | Installs, updates, and manages extensions on the machine. |
48+
| --- | --- | --- | --- |
49+
| `SqlServerExtension` | Microsoft SQL Server Extension Service | SqlServerExtension.exe | Connects your SQL Server instance to Azure. |
50+
| `himds` | Azure Hybrid Instance Metadata Service | `himds.exe` | Synchronizes metadata with Azure and hosts a local REST API for extensions and applications to access the metadata and request Microsoft Entra managed identity tokens |
51+
| `GCArcService` | Machine configuration Arc Service | `gc_arc_service.exe` (gc_service.exe earlier than version 1.36) | Audits and enforces Azure machine configuration policies on the machine. |
52+
| `ExtensionService` | Machine configuration Extension Service | `gc_extension_service.exe` (gc_service.exe earlier than version 1.36) | Installs, updates, and manages extensions on the machine. |
4853

4954
## Virtual service accounts
5055

51-
| Virtual Account | Description |
52-
|------------------|-------------|
56+
| Virtual Account | Description |
57+
| --- | --- |
5358
| `NT SERVICE\himds` | Unprivileged account used to run the Hybrid Instance Metadata Service. |
5459
| `NT Service\SQLServerExtension` | Unprivileged account used to run the SQL Server Extension Service in least privilege mode. |
5560

@@ -58,7 +63,7 @@ This article lists system objects - files, registry keys, Windows services and t
5863
Base key: `HKEY_LOCAL_MACHINE`
5964

6065
| Key | Description & notes |
61-
| :----- | :----- |
66+
| --- | --- |
6267
| `SOFTWARE\Microsoft\Microsoft SQL Server\<InstanceRegistryName>\MSSQLSERVER` | Microsoft Entra ID registry key |
6368
| `SOFTWARE\Microsoft\Microsoft SQL Server\<InstanceRegistryName>\PurviewConfig` | Purview registry key |
6469
| `SOFTWARE\Microsoft\SystemCertificates` | Windows certificate registry key |
@@ -70,9 +75,55 @@ In each instance of SQL Server enabled by Azure Arc, the extension creates the f
7075
- `dq.arcJobTriggers00`
7176
- `dt.arcJobDefinitions`
7277

73-
These tables store background job definition and execution history. Background jobs perform scheduled and user-initiated actions. These tables allow long-running jobs to automatically resume in the event that the Azure Extension for SQL Server is restarted.
78+
These tables store background job definition and execution history. Background jobs perform scheduled and user-initiated actions. These tables allow long-running jobs to automatically resume if the Azure Extension for SQL Server is restarted.
79+
80+
Additionally, the table `dbo.SQLServerAzureArcProperties` contains the resource identity for the SQL Server instance in Azure Resource Manager. This table can be used to detect if the SQL Server instance is Arc-enabled, and if so, what the identity of the resource is in Azure.
81+
82+
## Frequently asked questions
83+
84+
### Where are these background jobs?
85+
86+
The background jobs are used to perform long-running tasks that can persist state if the computer restarts. The logic of the jobs is stored in the extension, while state is stored in `msdb`. For example, a migration assessment job can take a long time to execute, so the state is stored in `msdb`.
87+
88+
### What security context do the jobs run under?
89+
90+
For least privilege mode, the jobs run under the `C:\Program Files\SQL Server Extension\SqlServerExtension.Service.exe` service context. The service connects to the `msdb` database on [!INCLUDE [ssnoversion-md](../../includes/ssnoversion-md.md)] with the `NT Service\SQLServerExtension` account. This service has the minimum permissions required to operate on `msdb`.
91+
92+
If the agent extension is not in least privilege mode, the connection is made using the `LocalSystem` account.
93+
94+
### How long are the rows on this table retained for? What is the purge policy?
95+
96+
The maximum job lifetime is 15 days. This setting is currently not user configurable via the Azure Resource Manager API. After 15 days, the engine automatically purges old jobs that are finished executing.
97+
98+
A given job has a maximum lifetime of one day before it fails. This period limits the lifetime a job can remain on the system.
99+
100+
### How large are these tables expected to grow?
101+
102+
The tables are expected to be small. The retention period is finite, and there's only a few jobs.
103+
104+
### What indexes do I need on these tables?
105+
106+
Indexes don't help performance. The tables should be trivially sized as they're tied to the number of features/jobs running at a given point in time.
107+
108+
### Which features use these tables and jobs?
109+
110+
Various features of the Arc SQL Extension features use background jobs to store state.
111+
112+
Including:
113+
114+
- Best Practice Assessment
115+
- Migration Assessment
116+
- Database Backup/Restore
117+
118+
The tables allow the extension to continue expensive operations (such as discovery) that can take long periods of time, without starting from scratch each time.
119+
120+
### What happens if these tables are inadvertently dropped or if corruption occurs in these tables?
121+
122+
If the tables are dropped, state is lost, and the extension deployer recreates the table. If the tables are corrupted by mutating state the jobs are reading from, the extension might fail.
123+
124+
### How can these tables be manually recreated if they're missing?
74125

75-
Additionally, the table `dbo.SQLServerAzureArcProperties` contains the resource identity for the SQL Server instance in Azure Resource Manager. This table can be used to detect if the SQL Server instance is Arc-enabled, and if so, what the identity of the resource is in Azure.
126+
Any Arc action that invokes the extension deployer - such as an ARM settings change, or an upgrade - recreates the tables.
76127

77128
## Related content
78129

0 commit comments

Comments
 (0)