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..4fb531ce3 --- /dev/null +++ b/docs/reference/schemas/config/functions/secret.md @@ -0,0 +1,177 @@ +--- +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 +results: +- name: Database Connection + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "MySecretPassword123" +messages: [] +hadErrors: false +``` + +### 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 +results: +- name: Database Connection + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "MySecretPassword123" +messages: [] +hadErrors: false +``` + +## Parameters + +### name + +The name of the secret to retrieve. + +```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. + +```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 + +- Secret values are retrieved at runtime and should be handled securely +- Secrets are not cached by DSC and are retrieved fresh on each function call +- Secret values are logged when `--trace-level` is "TRACE" +- Extensions should implement appropriate authentication and authorization for + secret access + +## Extension requirements + +To support the `secret()` function, extensions must: + +1. Declare the `secret` capability in their manifest +2. Implement a secret retrieval method that accepts name and optional vault + parameters +3. Return secret values as single-line strings (multi-line values are not + supported) +4. Handle authentication and authorization according to their secret + management system + +## Related functions + +- [`parameters()`][00] - Access configuration parameters that may influence + secret selection + + +[00]: ./parameters.md