Feature/dsc v3 native resources

CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog, and this project aims to follow Semantic Versioning.
+
+## [Unreleased]
+
+### Added
+
+- README setup guidance for installing DSC v3 and registering resource discovery paths.
+- Parameter reference documentation for Microsoft.Azure.Arc/AgentConfiguration.
+- Operation examples for export, get, test, and set.

README.md

@@ -1,2 +1,73 @@
 # AzureConnectedMachineDsc
-DSC resource for managing the state of Azure Arc for servers agent
+
+DSC resource for managing Azure Arc for Servers agent configuration.
+
+## Prerequisites
+
+- Windows PowerShell 7 (`pwsh`) available in `PATH`
+- Azure Arc agent installed (`azcmagent` command available)
+- Administrator session for `set` operations (resource requires elevated security context)
+
+## Install DSC v3
+
+### Stable
+
+```powershell
+winget install --id Microsoft.DSC --exact --source winget
+```
+
+### Preview (optional)
+
+```powershell
+winget install --id Microsoft.DSC.Preview --exact --source winget
+```
+
+### Verify installation
+
+```powershell
+dsc --version
+```
+
+## Make the resource discoverable
+
+This repository keeps the resource files in `dsc_resources`.
+
+You can use one of two methods:
+
+### Method 1 (recommended): set `DSC_RESOURCE_PATH`
+
+```powershell
+$repoRoot = "D:\Git\AzureConnectedMachineDsc"
+$env:DSC_RESOURCE_PATH = Join-Path $repoRoot 'dsc_resources'
+
+# Optional: persist for future sessions
+[System.Environment]::SetEnvironmentVariable('DSC_RESOURCE_PATH', $env:DSC_RESOURCE_PATH, 'User')
+```
+
+### Method 2: copy resource files to DSC root folder
+
+```powershell
+$repoRoot = "D:\Git\AzureConnectedMachineDsc"
+$resourceSource = Join-Path $repoRoot 'dsc_resources\*'
+$dscRoot = Split-Path (Get-Command dsc -ErrorAction Stop).Source -Parent
+
+Copy-Item -Path $resourceSource -Destination $dscRoot -Recurse -Force
+```
+
+## Quick validation
+
+```powershell
+# List resources and confirm the custom type is found
+dsc resource list | Select-String 'Microsoft.Azure.Arc/AgentConfiguration'
+
+# Get current state
+'{}' | dsc resource get -r Microsoft.Azure.Arc/AgentConfiguration -f - | ConvertFrom-Json
+```
+
+## Run tests
+
+```powershell
+Set-Location D:\Git\AzureConnectedMachineDsc\dsc_resources\tests
+$env:DSC_RESOURCE_PATH = "D:\Git\AzureConnectedMachineDsc\dsc_resources"
+Invoke-Pester -Path .\azure_arc_agent.tests.ps1 -Output Detailed
+```

docs/azure_arc_agent-operations-examples.md

@@ -0,0 +1,114 @@
+# Microsoft.Azure.Arc/AgentConfiguration operation examples
+
+Examples in this file are based on test behavior in dsc_resources/tests/azure_arc_agent.tests.ps1.
+
+## Prerequisites
+
+```powershell
+$env:DSC_RESOURCE_PATH = "D:\Git\AzureConnectedMachineDsc\dsc_resources"
+$resourceType = "Microsoft.Azure.Arc/AgentConfiguration"
+```
+
+## Get
+
+Use an empty input object to read current agent configuration.
+
+```powershell
+'{}' | dsc resource get -r $resourceType -f - | ConvertFrom-Json
+```
+
+Expected fields in output include:
+
+- actualState.agentInstalled
+- actualState.incomingConnectionsEnabled
+- actualState.guestConfigurationEnabled
+- actualState.extensionsEnabled
+- actualState.extensionAllowlist
+- actualState.extensionBlocklist
+- actualState.configMode
+
+## Test
+
+Provide the desired configuration and evaluate drift.
+
+```powershell
+$desired = @{
+  incomingConnectionsEnabled = $false
+  guestConfigurationEnabled  = $false
+  extensionsEnabled          = $false
+  extensionAllowlist         = @(
+    "Microsoft.Azure.AzureDefenderForServers/MDE.Windows"
+    "Microsoft.Azure.Monitor/AzureMonitorWindowsAgent"
+  )
+  extensionBlocklist         = @(
+    "Microsoft.Azure.Automation.HybridWorker/HybridWorkerForWindows"
+    "Microsoft.Azure.Automation/HybridWorkerForLinux"
+    "Microsoft.Azure.Extensions/CustomScript"
+    "Microsoft.Cplat.Core/RunCommandHandlerLinux"
+    "Microsoft.Cplat.Core/RunCommandHandlerWindows"
+    "Microsoft.Compute/CustomScriptExtension"
+    "Microsoft.EnterpriseCloud.Monitoring/MicrosoftMonitoringAgent"
+    "Microsoft.EnterpriseCloud.Monitoring/OMSAgentForLinux"
+  )
+  configMode = "full"
+}
+
+$desired | ConvertTo-Json -Depth 10 -Compress |
+  dsc resource test -r $resourceType -f - |
+  ConvertFrom-Json
+```
+
+Result includes:
+
+- desired properties echoed as current values for compared keys
+- _inDesiredState (true or false)
+
+## Set
+
+Set applies desired values. This operation requires elevated permissions.
+
+```powershell
+$desired = @{
+  incomingConnectionsEnabled = $false
+  guestConfigurationEnabled  = $false
+  extensionsEnabled          = $false
+  extensionAllowlist         = @(
+    "Microsoft.Azure.AzureDefenderForServers/MDE.Windows"
+    "Microsoft.Azure.Monitor/AzureMonitorWindowsAgent"
+  )
+  extensionBlocklist         = @(
+    "Microsoft.Azure.Automation.HybridWorker/HybridWorkerForWindows"
+    "Microsoft.Azure.Automation/HybridWorkerForLinux"
+    "Microsoft.Azure.Extensions/CustomScript"
+    "Microsoft.Cplat.Core/RunCommandHandlerLinux"
+    "Microsoft.Cplat.Core/RunCommandHandlerWindows"
+    "Microsoft.Compute/CustomScriptExtension"
+    "Microsoft.EnterpriseCloud.Monitoring/MicrosoftMonitoringAgent"
+    "Microsoft.EnterpriseCloud.Monitoring/OMSAgentForLinux"
+  )
+  configMode = "full"
+}
+
+$desired | ConvertTo-Json -Depth 10 -Compress |
+  dsc resource set -r $resourceType -f - |
+  ConvertFrom-Json
+```
+
+Expected afterState values in tests:
+
+- incomingConnectionsEnabled = false
+- guestConfigurationEnabled = false
+- extensionsEnabled = false
+- extensionAllowlist contains Microsoft.Azure.AzureDefenderForServers/MDE.Windows and Microsoft.Azure.Monitor/AzureMonitorWindowsAgent
+- extensionBlocklist contains Microsoft.Cplat.Core/RunCommandHandlerWindows
+- configMode = full
+
+## Export
+
+Export returns current non-null properties as reusable configuration state.
+
+```powershell
+'{}' | dsc resource export -r $resourceType -f - | ConvertFrom-Json
+```
+
+Typical use: pipe export output to file and use it as baseline desired state.

docs/azure_arc_agent-parameters.md

@@ -0,0 +1,39 @@
+# Microsoft.Azure.Arc/AgentConfiguration parameters
+
+This document describes all resource properties, allowed values, and usage notes for the DSC v3 resource type:
+
+- Microsoft.Azure.Arc/AgentConfiguration
+
+## Writable properties
+
+| Property | Type | Allowed values | Notes |
+|---|---|---|---|
+| incomingConnectionsEnabled | boolean or null | true, false, null | Maps to azcmagent config key incomingconnections.enabled. |
+| guestConfigurationEnabled | boolean or null | true, false, null | Maps to azcmagent config key guestconfiguration.enabled. |
+| extensionsEnabled | boolean or null | true, false, null | Maps to azcmagent config key extensions.enabled. |
+| extensionAllowlist | array of string or null | null or list of extension names | Maps to azcmagent config key extensions.allowlist. Empty list is allowed. |
+| extensionBlocklist | array of string or null | null or list of extension names | Maps to azcmagent config key extensions.blocklist. Empty list is allowed. |
+| configMode | string or null | monitor, full, null | Any other value fails validation. Comparison is case-insensitive in processing. |
+| proxyUrl | string or null | any string, null | Maps to azcmagent config key proxy.url. |
+
+## Read-only properties
+
+| Property | Type | Allowed values | Notes |
+|---|---|---|---|
+| agentInstalled | boolean or null | true, false, null | Returned by get/test/set state output. Not intended as input. |
+| _inDesiredState | boolean or null | true, false, null | Returned by test output. Not intended as input. |
+
+## Input validation behavior
+
+- Unknown properties are rejected.
+- Boolean properties accept boolean values and boolean-like strings convertible to true/false.
+- configMode accepts only monitor or full.
+- extensionAllowlist and extensionBlocklist are normalized as string lists (trimmed, deduplicated, sorted).
+
+## Security context requirement
+
+The set operation requires elevated security context.
+
+In resource manifest terms:
+
+- set.requireSecurityContext = elevated

dsc_config_example/arc-agent-export.dsc.yaml

@@ -0,0 +1,10 @@
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+metadata:
+  Microsoft.DSC:
+    requiredSecurityContext: current # this is the default and just used as an example indicating this config works for admins and non-admins
+resources:
+  - name: Azure Arc - Guest Config
+    type: Microsoft.Azure.Arc/AgentConfiguration
+    properties: {}
+
+

dsc_config_example/arc-agent.dsc.yaml

@@ -0,0 +1,16 @@
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+metadata:
+  Microsoft.DSC:
+    requiredSecurityContext: current # this is the default and just used as an example indicating this config works for admins and non-admins
+resources:
+  - name: Azure Arc - Guest Config
+    type: Microsoft.Azure.Arc/AgentConfiguration
+    properties:
+      guestConfigurationEnabled: true
+      incomingConnectionsEnabled: true
+      extensionAllowlist:
+        - Microsoft.Azure.Monitor/AzureMonitorWindowsAgent
+      extensionsEnabled: true
+      proxyUrl: http://myproxy:8080
+
+

dsc_resources/.project.data.json

@@ -0,0 +1,11 @@
+{
+    "Name": "azure_arc_agent",
+    "Kind": "Resource",
+    "SupportedPlatformOS": "Windows",
+    "CopyFiles": {
+        "Windows": [
+            "azure_arc_agent.resource.ps1",
+            "azure_arc_agent.dsc.resource.json"
+        ]
+    }
+}