From 1e27d0be7874bce12c94ae2cfe3d257ad3efd712 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Fri, 22 Aug 2025 09:43:20 +0200 Subject: [PATCH 1/7] Add reference documentation for secret() --- docs/reference/cli/function/index.md | 12 +- .../schemas/config/functions/secret.md | 252 ++++++++++++++++++ 2 files changed, 254 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..a8719dd6d --- /dev/null +++ b/docs/reference/schemas/config/functions/secret.md @@ -0,0 +1,252 @@ +--- +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. + +```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: "Connection string with password: [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: "Connection string with password: MySecretPassword123" +messages: [] +hadErrors: false +``` + +### Example 2 - Retrieve a secret from a specific vault + +The following example retrieves a secret from a specific vault to avoid +ambiguity when the same secret name exists in multiple vaults. + +```yaml +# secret.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: API Configuration + type: Microsoft.DSC.Debug/Echo + properties: + output: "API Key: [secret('ApiKey', 'ProductionVault')]" +``` + +```bash +dsc config get --file secret.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: API Configuration + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "API Key: prod-api-key-xyz789" +messages: [] +hadErrors: false +``` + +### Example 3 - Multiple secrets in configuration + +The following example demonstrates using multiple secrets within a single +resource configuration. + +```yaml +# secret.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Service Configuration + type: Microsoft.DSC.Debug/Echo + properties: + output: + username: "[secret('ServiceUsername')]" + password: "[secret('ServicePassword')]" + connectionString: "Server=myserver;User=[secret('DbUser')];Password=[secret('DbPassword')]" +``` + +```bash +dsc config get --file secret.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Service Configuration + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + username: "serviceaccount" + password: "SecurePassword456" + connectionString: "Server=myserver;User=dbuser;Password=DbPass789" +messages: [] +hadErrors: false +``` + +### Example 4 - Conditional secret usage + +The following example shows using secrets conditionally based on environment +parameters. + +```yaml +# secret.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + environment: + type: string + defaultValue: production +resources: +- name: Environment-specific config + type: Microsoft.DSC.Debug/Echo + properties: + output: + apiKey: >- + [if(equals(parameters('environment'), 'production'), + secret('ProdApiKey', 'ProdVault'), + secret('DevApiKey', 'DevVault'))] +``` + +```bash +dsc config get --file secret.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Environment-specific config + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + apiKey: "prod-secure-key-abc123" +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 not logged in trace output for security reasons +- 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 + +- [`if()`][00] - Returns values based on a condition for conditional secret + usage +- [`equals()`][01] - Compares values for conditional logic +- [`parameters()`][02] - Access configuration parameters that may influence + secret selection + + +[00]: ./if.md +[01]: ./equals.md +[02]: ./parameters.md From ddd7bb2a2f4af73fc3f1a9250b4415ab61517b62 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Fri, 22 Aug 2025 09:43:20 +0200 Subject: [PATCH 2/7] Add reference documentation for secret() --- docs/reference/cli/function/index.md | 12 +- .../schemas/config/functions/secret.md | 252 ++++++++++++++++++ 2 files changed, 254 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..a8719dd6d --- /dev/null +++ b/docs/reference/schemas/config/functions/secret.md @@ -0,0 +1,252 @@ +--- +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. + +```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: "Connection string with password: [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: "Connection string with password: MySecretPassword123" +messages: [] +hadErrors: false +``` + +### Example 2 - Retrieve a secret from a specific vault + +The following example retrieves a secret from a specific vault to avoid +ambiguity when the same secret name exists in multiple vaults. + +```yaml +# secret.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: API Configuration + type: Microsoft.DSC.Debug/Echo + properties: + output: "API Key: [secret('ApiKey', 'ProductionVault')]" +``` + +```bash +dsc config get --file secret.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: API Configuration + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "API Key: prod-api-key-xyz789" +messages: [] +hadErrors: false +``` + +### Example 3 - Multiple secrets in configuration + +The following example demonstrates using multiple secrets within a single +resource configuration. + +```yaml +# secret.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Service Configuration + type: Microsoft.DSC.Debug/Echo + properties: + output: + username: "[secret('ServiceUsername')]" + password: "[secret('ServicePassword')]" + connectionString: "Server=myserver;User=[secret('DbUser')];Password=[secret('DbPassword')]" +``` + +```bash +dsc config get --file secret.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Service Configuration + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + username: "serviceaccount" + password: "SecurePassword456" + connectionString: "Server=myserver;User=dbuser;Password=DbPass789" +messages: [] +hadErrors: false +``` + +### Example 4 - Conditional secret usage + +The following example shows using secrets conditionally based on environment +parameters. + +```yaml +# secret.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + environment: + type: string + defaultValue: production +resources: +- name: Environment-specific config + type: Microsoft.DSC.Debug/Echo + properties: + output: + apiKey: >- + [if(equals(parameters('environment'), 'production'), + secret('ProdApiKey', 'ProdVault'), + secret('DevApiKey', 'DevVault'))] +``` + +```bash +dsc config get --file secret.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Environment-specific config + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + apiKey: "prod-secure-key-abc123" +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 not logged in trace output for security reasons +- 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 + +- [`if()`][00] - Returns values based on a condition for conditional secret + usage +- [`equals()`][01] - Compares values for conditional logic +- [`parameters()`][02] - Access configuration parameters that may influence + secret selection + + +[00]: ./if.md +[01]: ./equals.md +[02]: ./parameters.md From e4d551681febdfb6c2d3e35b31334b80066ceb76 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Mon, 25 Aug 2025 03:09:03 +0200 Subject: [PATCH 3/7] Lowercase secret --- docs/reference/schemas/config/functions/secret.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/schemas/config/functions/secret.md b/docs/reference/schemas/config/functions/secret.md index a8719dd6d..aa76cbdae 100644 --- a/docs/reference/schemas/config/functions/secret.md +++ b/docs/reference/schemas/config/functions/secret.md @@ -230,7 +230,7 @@ The `secret()` function can return errors in the following situations: To support the `secret()` function, extensions must: -1. Declare the `Secret` capability in their manifest +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 From 61920a8ba4069716c83c036e70e54ae7aee77e2e Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Fri, 22 Aug 2025 09:43:20 +0200 Subject: [PATCH 4/7] Add reference documentation for secret() --- docs/reference/cli/function/index.md | 12 +- .../schemas/config/functions/secret.md | 252 ++++++++++++++++++ 2 files changed, 254 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..a8719dd6d --- /dev/null +++ b/docs/reference/schemas/config/functions/secret.md @@ -0,0 +1,252 @@ +--- +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. + +```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: "Connection string with password: [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: "Connection string with password: MySecretPassword123" +messages: [] +hadErrors: false +``` + +### Example 2 - Retrieve a secret from a specific vault + +The following example retrieves a secret from a specific vault to avoid +ambiguity when the same secret name exists in multiple vaults. + +```yaml +# secret.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: API Configuration + type: Microsoft.DSC.Debug/Echo + properties: + output: "API Key: [secret('ApiKey', 'ProductionVault')]" +``` + +```bash +dsc config get --file secret.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: API Configuration + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "API Key: prod-api-key-xyz789" +messages: [] +hadErrors: false +``` + +### Example 3 - Multiple secrets in configuration + +The following example demonstrates using multiple secrets within a single +resource configuration. + +```yaml +# secret.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Service Configuration + type: Microsoft.DSC.Debug/Echo + properties: + output: + username: "[secret('ServiceUsername')]" + password: "[secret('ServicePassword')]" + connectionString: "Server=myserver;User=[secret('DbUser')];Password=[secret('DbPassword')]" +``` + +```bash +dsc config get --file secret.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Service Configuration + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + username: "serviceaccount" + password: "SecurePassword456" + connectionString: "Server=myserver;User=dbuser;Password=DbPass789" +messages: [] +hadErrors: false +``` + +### Example 4 - Conditional secret usage + +The following example shows using secrets conditionally based on environment +parameters. + +```yaml +# secret.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + environment: + type: string + defaultValue: production +resources: +- name: Environment-specific config + type: Microsoft.DSC.Debug/Echo + properties: + output: + apiKey: >- + [if(equals(parameters('environment'), 'production'), + secret('ProdApiKey', 'ProdVault'), + secret('DevApiKey', 'DevVault'))] +``` + +```bash +dsc config get --file secret.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Environment-specific config + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + apiKey: "prod-secure-key-abc123" +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 not logged in trace output for security reasons +- 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 + +- [`if()`][00] - Returns values based on a condition for conditional secret + usage +- [`equals()`][01] - Compares values for conditional logic +- [`parameters()`][02] - Access configuration parameters that may influence + secret selection + + +[00]: ./if.md +[01]: ./equals.md +[02]: ./parameters.md From 59091fa8ad68ed77bec82512e7ef82d83192d5d3 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Mon, 25 Aug 2025 03:09:03 +0200 Subject: [PATCH 5/7] Lowercase secret --- docs/reference/schemas/config/functions/secret.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/schemas/config/functions/secret.md b/docs/reference/schemas/config/functions/secret.md index a8719dd6d..aa76cbdae 100644 --- a/docs/reference/schemas/config/functions/secret.md +++ b/docs/reference/schemas/config/functions/secret.md @@ -230,7 +230,7 @@ The `secret()` function can return errors in the following situations: To support the `secret()` function, extensions must: -1. Declare the `Secret` capability in their manifest +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 From f2e409617e1a9077ed19c0bd60d2e737b277d1dd Mon Sep 17 00:00:00 2001 From: GijsR Date: Mon, 25 Aug 2025 14:32:11 +0200 Subject: [PATCH 6/7] Secret values are logged in trace output --- docs/reference/schemas/config/functions/secret.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/schemas/config/functions/secret.md b/docs/reference/schemas/config/functions/secret.md index aa76cbdae..8fa4de3cd 100644 --- a/docs/reference/schemas/config/functions/secret.md +++ b/docs/reference/schemas/config/functions/secret.md @@ -222,7 +222,7 @@ The `secret()` function can return errors in the following situations: - 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 not logged in trace output for security reasons +- Secret values are logged in trace output - Extensions should implement appropriate authentication and authorization for secret access From 33189d42539b8fe1574a2f0e515d86a27e5de4a0 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Wed, 27 Aug 2025 03:16:54 +0200 Subject: [PATCH 7/7] Rewrite examples --- .../schemas/config/functions/secret.md | 109 +++--------------- 1 file changed, 17 insertions(+), 92 deletions(-) diff --git a/docs/reference/schemas/config/functions/secret.md b/docs/reference/schemas/config/functions/secret.md index af9c1a41a..4fb531ce3 100644 --- a/docs/reference/schemas/config/functions/secret.md +++ b/docs/reference/schemas/config/functions/secret.md @@ -40,7 +40,7 @@ systems. ### Example 1 - Retrieve a secret by name The following example retrieves a secret named 'DatabasePassword' from any -available vault. +available vault. The secret expression is used directly as the output value. ```yaml # secret.example.1.dsc.config.yaml @@ -49,7 +49,7 @@ resources: - name: Database Connection type: Microsoft.DSC.Debug/Echo properties: - output: "Connection string with password: [secret('DatabasePassword')]" + output: "[secret('DatabasePassword')]" ``` ```bash @@ -62,112 +62,42 @@ results: type: Microsoft.DSC.Debug/Echo result: actualState: - output: "Connection string with password: MySecretPassword123" + output: "MySecretPassword123" messages: [] hadErrors: false ``` -### Example 2 - Retrieve a secret from a specific vault +### Example 2 - Pass a secret through a parameter default -The following example retrieves a secret from a specific vault to avoid -ambiguity when the same secret name exists in multiple vaults. +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 -resources: -- name: API Configuration - type: Microsoft.DSC.Debug/Echo - properties: - output: "API Key: [secret('ApiKey', 'ProductionVault')]" -``` - -```bash -dsc config get --file secret.example.2.dsc.config.yaml -``` - -```yaml -results: -- name: API Configuration - type: Microsoft.DSC.Debug/Echo - result: - actualState: - output: "API Key: prod-api-key-xyz789" -messages: [] -hadErrors: false -``` - -### Example 3 - Multiple secrets in configuration - -The following example demonstrates using multiple secrets within a single -resource configuration. - -```yaml -# secret.example.3.dsc.config.yaml -$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json -resources: -- name: Service Configuration - type: Microsoft.DSC.Debug/Echo - properties: - output: - username: "[secret('ServiceUsername')]" - password: "[secret('ServicePassword')]" - connectionString: "Server=myserver;User=[secret('DbUser')];Password=[secret('DbPassword')]" -``` - -```bash -dsc config get --file secret.example.3.dsc.config.yaml -``` - -```yaml -results: -- name: Service Configuration - type: Microsoft.DSC.Debug/Echo - result: - actualState: - output: - username: "serviceaccount" - password: "SecurePassword456" - connectionString: "Server=myserver;User=dbuser;Password=DbPass789" -messages: [] -hadErrors: false -``` - -### Example 4 - Conditional secret usage - -The following example shows using secrets conditionally based on environment -parameters. - -```yaml -# secret.example.4.dsc.config.yaml -$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json parameters: - environment: - type: string - defaultValue: production + myString: + type: secureString + defaultValue: "[secret('MySecret')]" resources: -- name: Environment-specific config +- name: Database Connection type: Microsoft.DSC.Debug/Echo properties: - output: - apiKey: >- - [if(equals(parameters('environment'), 'production'), - secret('ProdApiKey', 'ProdVault'), - secret('DevApiKey', 'DevVault'))] + output: "[parameters('myString')]" ``` ```bash -dsc config get --file secret.example.4.dsc.config.yaml +dsc config get --file secret.example.2.dsc.config.yaml ``` ```yaml results: -- name: Environment-specific config +- name: Database Connection type: Microsoft.DSC.Debug/Echo result: actualState: - output: - apiKey: "prod-secure-key-abc123" + output: "MySecretPassword123" messages: [] hadErrors: false ``` @@ -240,13 +170,8 @@ To support the `secret()` function, extensions must: ## Related functions -- [`if()`][00] - Returns values based on a condition for conditional secret - usage -- [`equals()`][01] - Compares values for conditional logic -- [`parameters()`][02] - Access configuration parameters that may influence +- [`parameters()`][00] - Access configuration parameters that may influence secret selection -[00]: ./if.md -[01]: ./equals.md -[02]: ./parameters.md +[00]: ./parameters.md