Skip to content

Commit 8dc0655

Browse files
authored
Merge pull request #672 from michaeltlombardi/docs/main/v3-reference
(DOCS) Update CLI reference and conceptual docs for v3.0.0
2 parents 5a2a744 + ae29420 commit 8dc0655

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

72 files changed

+8460
-814
lines changed
Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
---
2+
description: >-
3+
DSC configuration documents are YAML or JSON data files that define the desired state of a system
4+
declaratively. They're used to retrieve, validate, and enforce the state of multiple resource
5+
instances.
6+
ms.date: 03/25/2025
7+
title: DSC configuration documents
8+
---
9+
10+
# DSC configuration documents
11+
12+
<!-- markdownlint-disable MD013 -->
13+
14+
In Microsoft's Desired State Configuration (DSC) platform, DSC configuration documents declare the
15+
desired state of a system as data files. Configuration documents define a collection of
16+
[DSC resource][01] instances to describe what the desired state should be, not how to put the
17+
system into that state. The DSC resources handle the _how_ for each instance.
18+
19+
DSC can process configuration documents to:
20+
21+
- Retrieve the current state of the defined resource instances with the `dsc config get` command.
22+
- Validate whether the instances are in the desired state with the `dsc config test` command.
23+
- Enforce the desired state for the instances with the `dsc config set` command.
24+
- Export a new configuration document with every instance of a set of resources with the
25+
`dsc config export` command.
26+
27+
Configuration documents are YAML or JSON files that contain a single object. The object's
28+
properties define how DSC processes the document. The top-level properties for a document are:
29+
30+
- `$schema` (required) - Defines the URI for the JSON Schema the document adheres to. DSC
31+
uses this URI to know how to validate and interpret the document.
32+
- `resources` (required) - Defines the collection of resource instances the document manages.
33+
- `metadata` (optional) - Defines an arbitrary set of annotations for the document. Except for
34+
metadata within the `Microsoft.DSC` property, DSC doesn't validate this data or use it directly.
35+
The annotations can include notes like who authored the document, the last time someone updated
36+
it, or any other information. DSC doesn't use the annotations. The metadata is for documentation
37+
or other tools to use.
38+
39+
DSC applies validation to the `Microsoft.DSC` property. For more information, see the
40+
[DSC Configuration document metadata schema][02] reference.
41+
- `parameters` (optional) - Defines a set of runtime options for the configuration. Resource
42+
instances can reference parameters to reduce duplicate definitions or enable dynamic values.
43+
Parameters can have default values and can be set on any configuration operation.
44+
- `variables` (optional) - Defines a set of reusable values for the configuration. Resource
45+
instances can reference variables to reduce duplicate definitions.
46+
47+
## Defining a configuration document
48+
49+
Minimally, a configuration document defines the `$schema` and `resources` properties. The
50+
`$schema` property must be a valid URI for the DSC configuration document schema. The `resources`
51+
property must define at least one DSC Resource instance.
52+
53+
For example:
54+
55+
```yaml
56+
# example.dsc.config.yaml
57+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
58+
resources:
59+
- name: example key value
60+
type: Microsoft.Windows/Registry
61+
properties:
62+
keyPath: HKCU\example\key
63+
valueName: Example
64+
valueData:
65+
String: This is an example.
66+
```
67+
68+
The example document defines a single resource instance named `example key value`. The instance
69+
uses the `Microsoft.Windows/Registry` resource to declare the following desired state:
70+
71+
- The `example\key` registry key should exist in the system's current user hive.
72+
- The `example\key` registry key should have a value called `Example`.
73+
- The `Example` value should be the string `This is an example`.
74+
75+
The example document is _declarative_. It describes the desired state, not how to put the system
76+
into that state. It relies on the `Microsoft.Windows/Registry` resource to handle getting, testing,
77+
and setting the state of the registry key and value.
78+
79+
For more information about the structure and validation of configuration documents, see
80+
[DSC Configuration document schema reference][03].
81+
82+
### Defining resource instances
83+
84+
As shown in the prior example, configuration documents include a collection of resource instances.
85+
Together, the instances describe the desired state of a system. A configuration document can
86+
include any number of resource instances.
87+
88+
A resource instance declaration always includes:
89+
90+
- `name` - A short, human-readable name for the instance that's unique in the document. This name
91+
is used for logging and it helps describe the purpose of the instance.
92+
- `type` - The [fully qualified type name][04] of the resource that DSC should use to manage the
93+
instance.
94+
- `properties` - The desired state for the instance. DSC validates the values against the
95+
resource's instance schema.
96+
97+
Configuration documents can't include the same instance more than once. Declaring the same instance
98+
with different properties leads to enforcement cycling, where each declaration enforces an
99+
incompatible state for the instance on every run.
100+
101+
## Getting the current state of a configuration
102+
103+
The `dsc config get` command retrieves the current state of the resource instances defined in a
104+
configuration document. When you use this command, DSC also:
105+
106+
- Collects any message emitted by the resources during the operation.
107+
- Indicates whether any of the resources raised an error.
108+
- Provides metadata about the operation as a whole and for each resource instance.
109+
110+
```sh
111+
dsc config get --file ./example.config.dsc.yaml
112+
```
113+
114+
```yaml
115+
metadata:
116+
Microsoft.DSC:
117+
version: 3.0.0
118+
operation: get
119+
executionType: actual
120+
startDatetime: 2025-02-24T16:09:40.671454400-06:00
121+
endDatetime: 2025-02-24T16:09:41.850086300-06:00
122+
duration: PT1.1786319S
123+
securityContext: restricted
124+
results:
125+
- metadata:
126+
Microsoft.DSC:
127+
duration: PT0.2751153S
128+
name: example key value
129+
type: Microsoft.Windows/Registry
130+
result:
131+
actualState:
132+
keyPath: HKCU\example\key
133+
_exist: false
134+
messages: []
135+
hadErrors: false
136+
```
137+
138+
## Testing a configuration
139+
140+
The `dsc config test` command compares the current state of the resource instances to their desired
141+
state. The result for each instance includes:
142+
143+
- The desired state for the instance.
144+
- The actual state of the instance.
145+
- Whether the instance is in the desired state.
146+
- The list of properties that are out of the desired state, if any.
147+
148+
When you use this command, DSC also:
149+
150+
- Collects any message emitted by the resources during the operation.
151+
- Indicates whether any of the resources raised an error.
152+
- Provides metadata about the operation as a whole and for each resource instance.
153+
154+
```sh
155+
dsc config test --file ./example.config.dsc.yaml
156+
```
157+
158+
```yaml
159+
metadata:
160+
Microsoft.DSC:
161+
version: 3.0.0
162+
operation: test
163+
executionType: actual
164+
startDatetime: 2025-02-24T16:11:42.798122500-06:00
165+
endDatetime: 2025-02-24T16:11:43.442216400-06:00
166+
duration: PT0.6440939S
167+
securityContext: restricted
168+
results:
169+
- metadata:
170+
Microsoft.DSC:
171+
duration: PT0.2234078S
172+
name: example key value
173+
type: Microsoft.Windows/Registry
174+
result:
175+
desiredState:
176+
keyPath: HKCU\example\key
177+
valueName: Example
178+
valueData:
179+
String: This is an example.
180+
actualState:
181+
keyPath: HKCU\example\key
182+
_exist: false
183+
inDesiredState: false
184+
differingProperties:
185+
- valueName
186+
- valueData
187+
- _exist
188+
messages: []
189+
hadErrors: false
190+
```
191+
192+
## Enforcing a configuration
193+
194+
The `dsc config set` command enforces the resource instances defined in a configuration document to
195+
their desired state. The result for each instance includes:
196+
197+
- The state of the instance before the operation.
198+
- The state of the instance after the operation.
199+
- Which properties the operation changed, if any.
200+
201+
When you use this command, DSC also:
202+
203+
- Collects any message emitted by the resources during the operation.
204+
- Indicates whether any of the resources raised an error.
205+
- Provides metadata about the operation as a whole and for each resource instance.
206+
207+
```sh
208+
dsc config set --file ./example.config.dsc.yaml
209+
```
210+
211+
```yaml
212+
metadata:
213+
Microsoft.DSC:
214+
version: 3.0.0
215+
operation: set
216+
executionType: actual
217+
startDatetime: 2025-02-24T16:13:32.746742600-06:00
218+
endDatetime: 2025-02-24T16:13:33.606785-06:00
219+
duration: PT0.8600424S
220+
securityContext: restricted
221+
results:
222+
- metadata:
223+
Microsoft.DSC:
224+
duration: PT0.4070001S
225+
name: example key value
226+
type: Microsoft.Windows/Registry
227+
result:
228+
beforeState:
229+
keyPath: HKCU\example\key
230+
_exist: false
231+
afterState:
232+
keyPath: HKCU\example\key
233+
valueName: Example
234+
valueData:
235+
String: This is an example.
236+
changedProperties:
237+
- valueName
238+
- valueData
239+
- _exist
240+
messages: []
241+
hadErrors: false
242+
```
243+
244+
## See also
245+
246+
- [DSC Resources][01] to learn about resources.
247+
- [DSC Configuration document schema reference][05]
248+
- [Command line reference for the 'dsc config' command][06]
249+
250+
[01]: ../resources/overview.md
251+
[02]: ../../reference/schemas/config/metadata.md#microsoftdsc
252+
[03]: ../../reference/schemas/config/document.md
253+
[04]: ../resources/overview.md#resource-type-names
254+
[05]: ../../reference/schemas/config/document.md
255+
[06]: ../../reference/cli/config/index.md

0 commit comments

Comments
 (0)