PowerShell Desired State Configuration

By Khimananda Oli | Last reviewed: August 2026

Managing Windows servers at scale requires moving beyond manual GUI clicks and fragile imperative scripts to a declarative model. PowerShell Desired State Configuration (DSC) solves this by defining the target state of your infrastructure in code, allowing the system to automatically enforce compliance and remediate drift. This guide covers the practical architecture, authoring patterns, and operational realities of DSC for modern Windows environments.

How does PowerShell Desired State Configuration architecture work?

Understanding the separation between authoring and execution is critical before writing your first configuration. Unlike standard PowerShell scripts that execute commands sequentially, DSC separates the "what" from the "how." You write a declarative configuration block which compiles into a Managed Object Format (MOF) file. This MOF is a static, platform-agnostic document describing the desired end state, not a script containing logic.

The execution engine is the Local Configuration Manager (LCM), a native Windows component that runs independently of the PowerShell console. The LCM reads the MOF, invokes the appropriate resource providers, and reports status. This decoupling means you can compile configurations on a Linux build agent and apply them to Windows targets, provided the necessary resources are available. For teams transitioning from imperative PowerShell automation for Windows servers, this shift to declarative intent is the most significant mental hurdle but also the source of DSC's reliability.

How do you write an idempotent DSC configuration?

Idempotency is the non-negotiable contract of DSC. Running the same configuration ten times against a compliant system must result in zero changes and identical output. To achieve this, avoid all conditional logic like if/else inside your configuration blocks. Instead, rely entirely on built-in resources that handle state testing internally.

Using Built-in Resources Correctly

The PSDesiredStateConfiguration module ships with core resources such as File, Service, WindowsFeature, and Registry. Each resource accepts specific properties that define the target state. Always specify the minimum required properties to reduce surface area for drift detection failures.

Configuration WebServerBaseline {
    Import-DscResource -ModuleName PSDesiredStateConfiguration

    Node 'localhost' {
        WindowsFeature IIS {
            Ensure = 'Present'
            Name   = 'Web-Server'
        }

        Service W3SVC {
            Name      = 'W3SVC'
            State     = 'Running'
            StartupType = 'Automatic'
            DependsOn = '[WindowsFeature]IIS'
        }

        File AppFolder {
            DestinationPath = 'C:\inetpub\wwwroot\app'
            Type          = 'Directory'
            Ensure        = 'Present'
        }
    }
}

In this example, the DependsOn property creates an explicit dependency graph rather than relying on line order. The LCM respects this graph during both test and set phases. Never assume resources execute top-to-bottom; always declare dependencies explicitly to prevent race conditions during parallel application.

Handling Credentials Securely

A common mistake is embedding plaintext credentials in MOF files. Since MOFs are often stored in source control or transferred over networks, this creates immediate security debt. Use the Credential parameter with encrypted certificates or Azure Automation credential assets. For local testing, generate a self-signed certificate specifically for DSC encryption:

$cert = New-SelfSignedCertificate -DnsName 'DscEncryptionCert' `
    -CertStoreLocation Cert:\LocalMachine\My -KeyUsage KeyEncipherment

$securePassword = ConvertTo-SecureString 'P@ssw0rd!' -AsPlainText -Force
$cred = New-Object System.Management.Automation.PSCredential('admin', $securePassword)

# Reference in configuration with PsDscAllowDomainUser flag only in lab
# Production requires proper certificate thumbprint in LCM meta-config

What is the difference between Push and Pull DSC modes?

DSC supports two distinct delivery models, and choosing incorrectly leads to operational friction. Push mode uses Start-DscConfiguration to send MOFs directly to targets via WinRM. It is simple for ad-hoc tasks or small fleets but lacks scalability and persistent compliance checking. Pull mode configures nodes to periodically check a central SMB share or HTTP pull server for new configurations and modules.

For production environments requiring audit-ready compliance evidence, Pull mode is mandatory. It provides automatic drift correction and centralized versioning. However, setting up a secure HTTP pull server with registration keys adds initial complexity. Many teams now use Azure Automation State Configuration or AWS Systems Manager State Manager as managed pull services to avoid maintaining on-prem pull infrastructure.

How do you configure the Local Configuration Manager?

The LCM is configured separately from your node configurations using a special [DscLocalConfigurationManager()] attribute. This meta-configuration controls refresh frequency, reboot behavior, and pull server endpoints. A misconfigured LCM is the most frequent cause of silent DSC failures.

[DscLocalConfigurationManager()]
Configuration LcmPullConfig {
    Settings {
        RefreshMode       = 'Pull'
        ConfigurationMode = 'ApplyAndAutoCorrect'
        RebootNodeIfNeeded = $true
        ActionAfterReboot  = 'ContinueConfiguration'
        RefreshFrequencyMins = 30
        ConfigurationModeFrequencyMins = 15
    }

    ConfigurationRepositoryWeb PullServer {
        ServerURL          = 'https://dsc-pull.internal.corp:8080/PSDSCPullServer.svc'
        RegistrationKey    = 'your-registration-key-here'
        AllowUnsecureConnection = $false
    }

    ReportServerWeb PullServer {
        ServerURL          = 'https://dsc-pull.internal.corp:8080/PSDSCPullServer.svc'
        RegistrationKey    = 'your-registration-key-here'
    }
}

LcmPullConfig -OutputPath C:\Dsc\LcmMeta
Set-DscLocalConfigurationManager -Path C:\Dsc\LcmMeta -Verbose

Set ConfigurationMode to ApplyAndAutoCorrect for production systems requiring continuous compliance. The ApplyOnly mode applies configuration once but never remediates drift, defeating the purpose of DSC for regulated environments. Always enable reporting in pull mode; without it, you have no visibility into which nodes are non-compliant or why.

When should you choose DSC v3 or alternative tools?

While classic DSC (v2) remains fully supported in Windows Server 2025 and 2026, Microsoft has introduced DSC v3 as a cross-platform, Rust-based successor. Understanding when to adopt each prevents technical debt.

• Use Classic DSC (v2) when: Managing pure Windows Server fleets with existing MOF investments, requiring Group Policy integration, or operating in air-gapped environments with established pull servers.
• Use DSC v3 when: Targeting hybrid Linux/Windows estates, integrating with modern CI/CD pipelines that prefer YAML/JSON over MOF, or requiring faster performance without WMF dependencies.
• Consider Terraform/Ansible when: Your primary infrastructure is cloud-native (AWS/Azure/GCP), you need multi-cloud abstraction, or your team lacks Windows-specific expertise.

DSC v3 eliminates the LCM entirely, treating configuration as a CLI-invoked artifact similar to Terraform. This aligns better with GitOps workflows where agents run ephemeral containers. However, the ecosystem of v3 resources is still maturing. For most enterprise Windows shops in 2026, classic DSC with Azure Automation State Configuration remains the pragmatic choice for compliance-heavy workloads.

Implementing PowerShell Desired State Configuration in Production

Adopting PowerShell Desired State Configuration successfully requires treating it as a software engineering discipline, not an administrative afterthought. Store all configurations in version control, implement peer review for MOF changes, and integrate compilation into your CI pipeline. Test configurations against disposable VMs before touching production nodes. Monitor LCM event logs (Microsoft-Windows-Dsc/Operational) as critically as application logs; they are your single source of truth for compliance state.

Start small with baseline configurations for security hardening and service availability before attempting full application stack management. This builds organizational muscle memory around declarative thinking. When you encounter limitations in built-in resources, evaluate community modules from the PowerShell Gallery cautiously, preferring those with active maintenance and Pester test coverage.

If your team needs guidance implementing DSC for SOC 2 compliance or integrating it with existing Azure DevOps pipelines, reach out to discuss your specific infrastructure requirements. Properly implemented, DSC transforms Windows administration from reactive firefighting into predictable, auditable engineering.