Skip to content

Latest commit

 

History

History
255 lines (212 loc) · 8.95 KB

overview.md

File metadata and controls

255 lines (212 loc) · 8.95 KB
description ms.date title
DSC configuration documents are YAML or JSON data files that define the desired state of a system declaratively. They're used to retrieve, validate, and enforce the state of multiple resource instances.
03/25/2025
DSC configuration documents

DSC configuration documents

In Microsoft's Desired State Configuration (DSC) platform, DSC configuration documents declare the desired state of a system as data files. Configuration documents define a collection of DSC resource instances to describe what the desired state should be, not how to put the system into that state. The DSC resources handle the how for each instance.

DSC can process configuration documents to:

  • Retrieve the current state of the defined resource instances with the dsc config get command.
  • Validate whether the instances are in the desired state with the dsc config test command.
  • Enforce the desired state for the instances with the dsc config set command.
  • Export a new configuration document with every instance of a set of resources with the dsc config export command.

Configuration documents are YAML or JSON files that contain a single object. The object's properties define how DSC processes the document. The top-level properties for a document are:

  • $schema (required) - Defines the URI for the JSON Schema the document adheres to. DSC uses this URI to know how to validate and interpret the document.

  • resources (required) - Defines the collection of resource instances the document manages.

  • metadata (optional) - Defines an arbitrary set of annotations for the document. Except for metadata within the Microsoft.DSC property, DSC doesn't validate this data or use it directly. The annotations can include notes like who authored the document, the last time someone updated it, or any other information. DSC doesn't use the annotations. The metadata is for documentation or other tools to use.

    DSC applies validation to the Microsoft.DSC property. For more information, see the DSC Configuration document metadata schema reference.

  • parameters (optional) - Defines a set of runtime options for the configuration. Resource instances can reference parameters to reduce duplicate definitions or enable dynamic values. Parameters can have default values and can be set on any configuration operation.

  • variables (optional) - Defines a set of reusable values for the configuration. Resource instances can reference variables to reduce duplicate definitions.

Defining a configuration document

Minimally, a configuration document defines the $schema and resources properties. The $schema property must be a valid URI for the DSC configuration document schema. The resources property must define at least one DSC Resource instance.

For example:

# example.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: example key value
    type: Microsoft.Windows/Registry
    properties:
      keyPath:   HKCU\example\key
      valueName: Example
      valueData:
        String: This is an example.

The example document defines a single resource instance named example key value. The instance uses the Microsoft.Windows/Registry resource to declare the following desired state:

  • The example\key registry key should exist in the system's current user hive.
  • The example\key registry key should have a value called Example.
  • The Example value should be the string This is an example.

The example document is declarative. It describes the desired state, not how to put the system into that state. It relies on the Microsoft.Windows/Registry resource to handle getting, testing, and setting the state of the registry key and value.

For more information about the structure and validation of configuration documents, see DSC Configuration document schema reference.

Defining resource instances

As shown in the prior example, configuration documents include a collection of resource instances. Together, the instances describe the desired state of a system. A configuration document can include any number of resource instances.

A resource instance declaration always includes:

  • name - A short, human-readable name for the instance that's unique in the document. This name is used for logging and it helps describe the purpose of the instance.
  • type - The fully qualified type name of the resource that DSC should use to manage the instance.
  • properties - The desired state for the instance. DSC validates the values against the resource's instance schema.

Configuration documents can't include the same instance more than once. Declaring the same instance with different properties leads to enforcement cycling, where each declaration enforces an incompatible state for the instance on every run.

Getting the current state of a configuration

The dsc config get command retrieves the current state of the resource instances defined in a configuration document. When you use this command, DSC also:

  • Collects any message emitted by the resources during the operation.
  • Indicates whether any of the resources raised an error.
  • Provides metadata about the operation as a whole and for each resource instance.
dsc config get --file ./example.config.dsc.yaml
metadata:
  Microsoft.DSC:
    version: 3.0.0
    operation: get
    executionType: actual
    startDatetime: 2025-02-24T16:09:40.671454400-06:00
    endDatetime: 2025-02-24T16:09:41.850086300-06:00
    duration: PT1.1786319S
    securityContext: restricted
results:
- metadata:
    Microsoft.DSC:
      duration: PT0.2751153S
  name: example key value
  type: Microsoft.Windows/Registry
  result:
    actualState:
      keyPath: HKCU\example\key
      _exist: false
messages: []
hadErrors: false

Testing a configuration

The dsc config test command compares the current state of the resource instances to their desired state. The result for each instance includes:

  • The desired state for the instance.
  • The actual state of the instance.
  • Whether the instance is in the desired state.
  • The list of properties that are out of the desired state, if any.

When you use this command, DSC also:

  • Collects any message emitted by the resources during the operation.
  • Indicates whether any of the resources raised an error.
  • Provides metadata about the operation as a whole and for each resource instance.
dsc config test --file /example.config.dsc.yaml
metadata:
  Microsoft.DSC:
    version: 3.0.0
    operation: test
    executionType: actual
    startDatetime: 2025-02-24T16:11:42.798122500-06:00
    endDatetime: 2025-02-24T16:11:43.442216400-06:00
    duration: PT0.6440939S
    securityContext: restricted
results:
- metadata:
    Microsoft.DSC:
      duration: PT0.2234078S
  name: example key value
  type: Microsoft.Windows/Registry
  result:
    desiredState:
      keyPath: HKCU\example\key
      valueName: Example
      valueData:
        String: This is an example.
    actualState:
      keyPath: HKCU\example\key
      _exist: false
    inDesiredState: false
    differingProperties:
    - valueName
    - valueData
    - _exist
messages: []
hadErrors: false

Enforcing a configuration

The dsc config set command enforces the resource instances defined in a configuration document to their desired state. The result for each instance includes:

  • The state of the instance before the operation.
  • The state of the instance after the operation.
  • Which properties the operation changed, if any.

When you use this command, DSC also:

  • Collects any message emitted by the resources during the operation.
  • Indicates whether any of the resources raised an error.
  • Provides metadata about the operation as a whole and for each resource instance.
dsc config set --file ./example.config.dsc.yaml
metadata:
  Microsoft.DSC:
    version: 3.0.0
    operation: set
    executionType: actual
    startDatetime: 2025-02-24T16:13:32.746742600-06:00
    endDatetime: 2025-02-24T16:13:33.606785-06:00
    duration: PT0.8600424S
    securityContext: restricted
results:
- metadata:
    Microsoft.DSC:
      duration: PT0.4070001S
  name: example key value
  type: Microsoft.Windows/Registry
  result:
    beforeState:
      keyPath: HKCU\example\key
      _exist: false
    afterState:
      keyPath: HKCU\example\key
      valueName: Example
      valueData:
        String: This is an example.
    changedProperties:
    - valueName
    - valueData
    - _exist
messages: []
hadErrors: false

See also