M365DSC: Getting Started Part 1- Desired State Configuration
It's time to start a new series of blog on a project I am a complete fan:
Microsoft 365 DSC
It is a combination of Microsoft 365, PowerShell , and Desired State Configuration (DSC) DSC is a management platform that enables the management of resources with configuration as code. A team from Microsoft lead by Nik Charlebois has developed and adapted this technology to manage initially Office 365 collaborative platform(SharePoint, Teams and Exchange) and have expended it across other workloads taking advantage of the Graph API and other PowerShell modules. The solution covers policies across:
Security & Compliance Center
It allows you to export your policies, monitor configuration drifts, generate reports, compare configurations and much more. It can be fully integrated to your DevOps processes.
It is Opensource, developed and maintained by Microsoft and the community. First stop is the official website, GitHub repository and YouTube channel:
Before digging more into the solution, I want to focus this blog on DSC and the structure of the solution. This first blog will be an introduction to DSC.
DSC is a declarative platform used for configuration, deployment and management of systems. It can be used on-premises in traditional Windows infrastructure but also in the cloud with Azure automation and Linux. It consists of 3 components:
The configuration: This is the settings you are monitoring or enforcing - the desired state
The resource: This is the code and logic that monitor configuration drifts and keep the system in the desired state
The Local Configuration Manager (LCM): This is the engine running the solution.
The DSC configuration is a PowerShell script using special type of functions and keywords:
Configuration: This is the declaration of the DSC object
Node: This is your engine declaration - For M365DSC we use localhost
Resource: This is your properties values per type of resource - in the screenshot below the resource type is WindowsFeature
Or here an example specific to M365DSC and the AADUser resource
Each resource block must include the Ensure parameter and accept 2 values:
"Present": means that the resource and its settings must be found in the desired state in the environment. The LCM will monitor this feature and if configured will create or update the resource.
"Absent": means that the resource should not be present and that the LCM should remove any instances found.
If you don't specify the Ensure parameter, the default value is "Present"
The DSC resource provides the building block to retrieve, test and update a resource. There are built-in resources part of the PSDesiredSateConfiguration module
Other DSC modules are available from PowerShellGet and other provider, and finally you can develop custom resources. As of today, M365DSC has reached a milestone with more than 200 resources available and the coverage is always expending! A resource is a PowerShell script that defines 3 functions Get-TargetResource, Test-TargetResource and Set-TargetResource.
1- Get-TargetResource: This is where you retrieve your resource/policy and format it as required. 2- Test-TargetResource: This is where you test your configuration file against your reference - In case of M365DSC this reference is the policy in your M365 tenant. 3- Set-TargetResource: This is where you define the code to create, update or remove a resource.
In M365DSC, an additional method is exposed called Export-TargetResource. This is the method allowing you to extract the resource from your tenant using the Reverse DSC proxy. Each resource has a schema that determines the syntax needed to use the resource in a Configuration. This schema is a declarative of all parameters, their types, possible values, permissions (key, read, write) and some description.
Finally you compile a Managed Object Format (mof) file from the combination of the configuration and the schema files and will be used by the LCM to enforce or monitor desired state. To compile your mof file you will execute your configuration file.
The Local Configuration Manager (LCM)
It can be any Windows Server or container running preferably PowerShell v5 and later (some down-level support available for v4.0). The LCM is configured using Set-DscLocalConfigurationManager and to retrieve the current configuration use Get-DscLocalConfigurationManager
We want to focus on a few parameters here:
ConfigurationModeFequencyMins: The interval of time the engine check for configuration drifts
ConfigurationMode: This setting specifies if the engine should monitor settings and/or autocorrect configuration drifts. Possible values are:
ApplyOnly: The engine will apply the configuration once only during initial setup
ApplyAndMonitor: The engine will apply the configuration during initial setup and then audit any drift.
ApplyAndAutoCorrect: The engine will apply the configuration during initial setup and then enforce the desired state configuration if any drift is detected
Push: The engine pushes configuration to remote nodes - In the case of M365DSC the remote node is localhost which pushes the config to the M365 tenant
Pull: Each node pull the configuration from the pull server.
DSC is highly dependent on WMI and CIM instances so make sure your Windows Management Service is running and that you don't have your ASR rule blocking WMI commands. To start the engine and apply the initial setup, run:
Start-DscConfiguration -Wait -Verbose -Force -Path .\MyConfiguration
With MyConfiguration the name of the Configuration block in the Configuration file 🤩
You can stop the engine using
That's a wrap for this blog, next time we will look into installing and getting started with M365DSC. Happy PowerShelling!