From a7963efd62e04a06bf35544b889d2ee84816f40e Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Fri, 22 Aug 2025 09:43:20 +0200 Subject: [PATCH] Add reference documentation for secret() --- docs/reference/cli/function/index.md | 12 +- .../schemas/config/functions/secret.md | 233 ++++++++++++++++++ 2 files changed, 235 insertions(+), 10 deletions(-) create mode 100644 docs/reference/schemas/config/functions/secret.md diff --git a/docs/reference/cli/function/index.md b/docs/reference/cli/function/index.md index ca2774056..567cc8dfa 100644 --- a/docs/reference/cli/function/index.md +++ b/docs/reference/cli/function/index.md @@ -65,15 +65,7 @@ Numeric min 1 maxInt a-n-- Returns the smallest number Numeric mod 2 2 --n-- Divides the first number by the second and returns the remainder Numeric mul 2 2 --n-- Multiplies two or more numbers together Numeric sub 2 2 --n-- Subtracts the second number from the first -Resource reference 1 1 ---s- Retrieves the output of a previously executed resource -Resource resourceId 2 2 ---s- Constructs a resource ID from the given type and name -String base64 1 1 ---s- Encodes a string to Base64 format -String concat 2 maxInt a--s- Concatenates two or more strings or arrays -String format 2 maxInt -bns- Formats a string using the given arguments -System envvar 1 1 ---s- Retrieves the value of an environment variable -System path 2 maxInt ---s- Concatenates multiple strings into a file path -System secret 1 2 ---s- Retrieves a secret from a vault -System systemRoot 0 0 ---s- Returns the system root path +# truncated ``` ### Example 2 - List functions with JSON output @@ -84,7 +76,7 @@ This command returns function information in pretty JSON format. dsc function list --output-format pretty-json ``` -```json +```jsonc { "category": "Array", "name": "createArray", diff --git a/docs/reference/schemas/config/functions/secret.md b/docs/reference/schemas/config/functions/secret.md new file mode 100644 index 000000000..39ff0db41 --- /dev/null +++ b/docs/reference/schemas/config/functions/secret.md @@ -0,0 +1,233 @@ +--- +description: Reference for the 'secret' DSC configuration document function +ms.date: 08/22/2025 +ms.topic: reference +title: secret +--- + +# secret + +## Synopsis + +Retrieves secrets from registered secret management extensions. + +## Syntax + +```Syntax +secret() +secret(, ) +``` + +## Description + +The `secret()` function retrieves secrets from extensions that support the secret capability. It +queries all registered extensions that implement secret management and returns the requested secret +value. If multiple extensions return different values for the same secret name, an error is +returned unless a vault is specified to disambiguate. + +The function supports two calling patterns: + +- Single argument: Retrieves a secret by name from any available vault +- Two arguments: Retrieves a secret by name from a specific vault + +If multiple extensions return the same secret value, the function succeeds and returns that value. +This allows for redundancy across secret management systems. + +## Examples + +### Example 1 - Retrieve a secret by name + +The following example retrieves a secret named `DatabasePassword` from any available vault. The +secret expression is used directly as the output value. + +```yaml +# secret.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Database Connection + type: Microsoft.DSC.Debug/Echo + properties: + output: "[secret('DatabasePassword')]" +``` + +```bash +dsc config get --file secret.example.1.dsc.config.yaml +``` + +```yaml +executionInformation: + duration: PT11.2326172S + endDatetime: 2026-05-05T09:55:33.313388600-05:00 + executionType: actual + operation: get + securityContext: restricted + startDatetime: 2026-05-05T09:55:22.080771400-05:00 + version: 3.2.0 +metadata: + Microsoft.DSC: + duration: PT11.2325964S + endDatetime: 2026-05-05T09:55:33.313367800-05:00 + executionType: actual + operation: get + securityContext: restricted + startDatetime: 2026-05-05T09:55:22.080771400-05:00 + version: 3.2.0 +results: +- executionInformation: + duration: PT2.0098514S + metadata: + Microsoft.DSC: + duration: PT2.0098514S + name: Database Connection + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "MySecretPassword123" +messages: [] +hadErrors: false +``` + +> [!NOTE] +> In this example the secret is emitted in plain text in the output. This is because the `secret` +> function doesn't automatically wrap the result in a `secureString` wrapper. It passes the +> discovered secret directly to the resource as a string. +> +> DSC doesn't emit secrets to the console or through trace messages itself. However, DSC can't +> control whether a resource emits secrets. In this case, the secret was emitted by the `Echo` +> resource in its output. For more information about handling secrets in a configuration, see +> [Security considerations](#security-considerations). + +### Example 2 - Pass a secret through a parameter default + +The following example defines a `secureString` parameter whose default value is the secret. The +resource then uses the parameter value for the output property. + +```yaml +# secret.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + myString: + type: secureString + defaultValue: "[secret('MySecret')]" +resources: +- name: Database Connection + type: Microsoft.DSC.Debug/Echo + properties: + output: "[parameters('myString')]" +``` + +```bash +dsc config get --file secret.example.2.dsc.config.yaml +``` + +```yaml +executionInformation: + duration: PT13.5097206S + endDatetime: 2026-05-05T10:26:29.721210400-05:00 + executionType: actual + operation: get + securityContext: restricted + startDatetime: 2026-05-05T10:26:16.211489800-05:00 + version: 3.2.0 +metadata: + Microsoft.DSC: + duration: PT13.5097028S + endDatetime: 2026-05-05T10:26:29.721192600-05:00 + executionType: actual + operation: get + securityContext: restricted + startDatetime: 2026-05-05T10:26:16.211489800-05:00 + version: 3.2.0 +results: +- executionInformation: + duration: PT1.451969S + metadata: + Microsoft.DSC: + duration: PT1.451969S + name: Database Connection + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: +messages: [] +hadErrors: false +``` + +> [!NOTE] +> In this case, the value for the secret has been redacted because it was passed to the `Echo` +> resource as a `secureString` value. + +## Parameters + +### name + +The name of the secret to retrieve. + +DSC passes this value to every extension with the `secret` capability as-is. Whether this value is +case-sensitive depends on the extension and the secret vault that it uses. + +```yaml +Type: string +Required: true +Position: 1 +``` + +### vault + +The name of the vault or secret store to retrieve the secret from. When specified, only the named +vault is queried for the secret, which helps disambiguate when multiple vaults contain secrets with +the same name. + +DSC passes this value to every extension with the `secret` capability as-is. Whether this value is +case-sensitive depends on the extension and the secret vault that it uses. + +```yaml +Type: string +Required: false +Position: 2 +``` + +## Output + +The `secret()` function returns the secret value as a string. + +```yaml +Type: string +``` + +## Error conditions + +The `secret()` function can return errors in the following situations: + +- **No extensions available**: No secret management extensions are registered + or available +- **Secret not found**: The specified secret name does not exist in any + available vault +- **Multiple different values**: Multiple extensions return different values + for the same secret name (specify a vault to disambiguate) +- **Vault not found**: The specified vault does not exist or is not accessible +- **Extension error**: An underlying secret management extension returns an + error + +## Security considerations + +- DSC retrieves secret values at runtime and doesn't cache them. +- DSC invokes the `secret` operation for every available extension with that capability on each + usage of the `secret()` function in a configuration document. +- When you invoke DSC with `--trace-level` as `TRACE`, unwrapped secret values are emitted in trace + messages as part of the JSON Validation trace message for resource input. + + When the secret values are wrapped as a `secureObject` or `secureString`, DSC redacts the value + in trace messaging where it appears instead as ``. +- DSC doesn't automatically wrap retrieved secrets as `secureString` instances. When a secret is + wrapped as a `secureString`, like `{"secureString":""}`, the resource is responsible for + unwrapping the data. Check the JSON Schema and documentation for the resources you use to see + whether they support `secureString` values. + +## Related functions + +- [`parameters()`][00] - Access configuration parameters that may influence + secret selection + + +[00]: ./parameters.md