Skip to content

Commit a7963ef

Browse files
Gijsreynmichaeltlombardi
Gijsreyn
authored and
michaeltlombardi
committed
Add reference documentation for secret()
1 parent 0b4eb02 commit a7963ef

2 files changed

Lines changed: 235 additions & 10 deletions

File tree

‎docs/reference/cli/function/index.md‎

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -65,15 +65,7 @@ Numeric min 1 maxInt a-n-- Returns the smallest number
6565
Numeric mod 2 2 --n-- Divides the first number by the second and returns the remainder
6666
Numeric mul 2 2 --n-- Multiplies two or more numbers together
6767
Numeric sub 2 2 --n-- Subtracts the second number from the first
68-
Resource reference 1 1 ---s- Retrieves the output of a previously executed resource
69-
Resource resourceId 2 2 ---s- Constructs a resource ID from the given type and name
70-
String base64 1 1 ---s- Encodes a string to Base64 format
71-
String concat 2 maxInt a--s- Concatenates two or more strings or arrays
72-
String format 2 maxInt -bns- Formats a string using the given arguments
73-
System envvar 1 1 ---s- Retrieves the value of an environment variable
74-
System path 2 maxInt ---s- Concatenates multiple strings into a file path
75-
System secret 1 2 ---s- Retrieves a secret from a vault
76-
System systemRoot 0 0 ---s- Returns the system root path
68+
# truncated
7769
```
7870

7971
### Example 2 - List functions with JSON output
@@ -84,7 +76,7 @@ This command returns function information in pretty JSON format.
8476
dsc function list --output-format pretty-json
8577
```
8678

87-
```json
79+
```jsonc
8880
{
8981
"category": "Array",
9082
"name": "createArray",

‎docs/reference/schemas/config/functions/secret.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
---
2+
description: Reference for the 'secret' DSC configuration document function
3+
ms.date: 08/22/2025
4+
ms.topic: reference
5+
title: secret
6+
---
7+
8+
# secret
9+
10+
## Synopsis
11+
12+
Retrieves secrets from registered secret management extensions.
13+
14+
## Syntax
15+
16+
```Syntax
17+
secret(<name>)
18+
secret(<name>, <vault>)
19+
```
20+
21+
## Description
22+
23+
The `secret()` function retrieves secrets from extensions that support the secret capability. It
24+
queries all registered extensions that implement secret management and returns the requested secret
25+
value. If multiple extensions return different values for the same secret name, an error is
26+
returned unless a vault is specified to disambiguate.
27+
28+
The function supports two calling patterns:
29+
30+
- Single argument: Retrieves a secret by name from any available vault
31+
- Two arguments: Retrieves a secret by name from a specific vault
32+
33+
If multiple extensions return the same secret value, the function succeeds and returns that value.
34+
This allows for redundancy across secret management systems.
35+
36+
## Examples
37+
38+
### Example 1 - Retrieve a secret by name
39+
40+
The following example retrieves a secret named `DatabasePassword` from any available vault. The
41+
secret expression is used directly as the output value.
42+
43+
```yaml
44+
# secret.example.1.dsc.config.yaml
45+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
46+
resources:
47+
- name: Database Connection
48+
type: Microsoft.DSC.Debug/Echo
49+
properties:
50+
output: "[secret('DatabasePassword')]"
51+
```
52+
53+
```bash
54+
dsc config get --file secret.example.1.dsc.config.yaml
55+
```
56+
57+
```yaml
58+
executionInformation:
59+
duration: PT11.2326172S
60+
endDatetime: 2026-05-05T09:55:33.313388600-05:00
61+
executionType: actual
62+
operation: get
63+
securityContext: restricted
64+
startDatetime: 2026-05-05T09:55:22.080771400-05:00
65+
version: 3.2.0
66+
metadata:
67+
Microsoft.DSC:
68+
duration: PT11.2325964S
69+
endDatetime: 2026-05-05T09:55:33.313367800-05:00
70+
executionType: actual
71+
operation: get
72+
securityContext: restricted
73+
startDatetime: 2026-05-05T09:55:22.080771400-05:00
74+
version: 3.2.0
75+
results:
76+
- executionInformation:
77+
duration: PT2.0098514S
78+
metadata:
79+
Microsoft.DSC:
80+
duration: PT2.0098514S
81+
name: Database Connection
82+
type: Microsoft.DSC.Debug/Echo
83+
result:
84+
actualState:
85+
output: "MySecretPassword123"
86+
messages: []
87+
hadErrors: false
88+
```
89+
90+
> [!NOTE]
91+
> In this example the secret is emitted in plain text in the output. This is because the `secret`
92+
> function doesn't automatically wrap the result in a `secureString` wrapper. It passes the
93+
> discovered secret directly to the resource as a string.
94+
>
95+
> DSC doesn't emit secrets to the console or through trace messages itself. However, DSC can't
96+
> control whether a resource emits secrets. In this case, the secret was emitted by the `Echo`
97+
> resource in its output. For more information about handling secrets in a configuration, see
98+
> [Security considerations](#security-considerations).
99+
100+
### Example 2 - Pass a secret through a parameter default
101+
102+
The following example defines a `secureString` parameter whose default value is the secret. The
103+
resource then uses the parameter value for the output property.
104+
105+
```yaml
106+
# secret.example.2.dsc.config.yaml
107+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
108+
parameters:
109+
myString:
110+
type: secureString
111+
defaultValue: "[secret('MySecret')]"
112+
resources:
113+
- name: Database Connection
114+
type: Microsoft.DSC.Debug/Echo
115+
properties:
116+
output: "[parameters('myString')]"
117+
```
118+
119+
```bash
120+
dsc config get --file secret.example.2.dsc.config.yaml
121+
```
122+
123+
```yaml
124+
executionInformation:
125+
duration: PT13.5097206S
126+
endDatetime: 2026-05-05T10:26:29.721210400-05:00
127+
executionType: actual
128+
operation: get
129+
securityContext: restricted
130+
startDatetime: 2026-05-05T10:26:16.211489800-05:00
131+
version: 3.2.0
132+
metadata:
133+
Microsoft.DSC:
134+
duration: PT13.5097028S
135+
endDatetime: 2026-05-05T10:26:29.721192600-05:00
136+
executionType: actual
137+
operation: get
138+
securityContext: restricted
139+
startDatetime: 2026-05-05T10:26:16.211489800-05:00
140+
version: 3.2.0
141+
results:
142+
- executionInformation:
143+
duration: PT1.451969S
144+
metadata:
145+
Microsoft.DSC:
146+
duration: PT1.451969S
147+
name: Database Connection
148+
type: Microsoft.DSC.Debug/Echo
149+
result:
150+
actualState:
151+
output: <secureValue>
152+
messages: []
153+
hadErrors: false
154+
```
155+
156+
> [!NOTE]
157+
> In this case, the value for the secret has been redacted because it was passed to the `Echo`
158+
> resource as a `secureString` value.
159+
160+
## Parameters
161+
162+
### name
163+
164+
The name of the secret to retrieve.
165+
166+
DSC passes this value to every extension with the `secret` capability as-is. Whether this value is
167+
case-sensitive depends on the extension and the secret vault that it uses.
168+
169+
```yaml
170+
Type: string
171+
Required: true
172+
Position: 1
173+
```
174+
175+
### vault
176+
177+
The name of the vault or secret store to retrieve the secret from. When specified, only the named
178+
vault is queried for the secret, which helps disambiguate when multiple vaults contain secrets with
179+
the same name.
180+
181+
DSC passes this value to every extension with the `secret` capability as-is. Whether this value is
182+
case-sensitive depends on the extension and the secret vault that it uses.
183+
184+
```yaml
185+
Type: string
186+
Required: false
187+
Position: 2
188+
```
189+
190+
## Output
191+
192+
The `secret()` function returns the secret value as a string.
193+
194+
```yaml
195+
Type: string
196+
```
197+
198+
## Error conditions
199+
200+
The `secret()` function can return errors in the following situations:
201+
202+
- **No extensions available**: No secret management extensions are registered
203+
or available
204+
- **Secret not found**: The specified secret name does not exist in any
205+
available vault
206+
- **Multiple different values**: Multiple extensions return different values
207+
for the same secret name (specify a vault to disambiguate)
208+
- **Vault not found**: The specified vault does not exist or is not accessible
209+
- **Extension error**: An underlying secret management extension returns an
210+
error
211+
212+
## Security considerations
213+
214+
- DSC retrieves secret values at runtime and doesn't cache them.
215+
- DSC invokes the `secret` operation for every available extension with that capability on each
216+
usage of the `secret()` function in a configuration document.
217+
- When you invoke DSC with `--trace-level` as `TRACE`, unwrapped secret values are emitted in trace
218+
messages as part of the JSON Validation trace message for resource input.
219+
220+
When the secret values are wrapped as a `secureObject` or `secureString`, DSC redacts the value
221+
in trace messaging where it appears instead as `<secureValue>`.
222+
- DSC doesn't automatically wrap retrieved secrets as `secureString` instances. When a secret is
223+
wrapped as a `secureString`, like `{"secureString":"<secret>"}`, the resource is responsible for
224+
unwrapping the data. Check the JSON Schema and documentation for the resources you use to see
225+
whether they support `secureString` values.
226+
227+
## Related functions
228+
229+
- [`parameters()`][00] - Access configuration parameters that may influence
230+
secret selection
231+
232+
<!-- Link reference definitions -->
233+
[00]: ./parameters.md

0 commit comments

Comments
 (0)