Merge pull request #251124 from polatengin/enpolat/adding-bicepparam-getsecret-function

adding `az.getSecret` function documentation for bicepparam files

Author: v-dirichards

articles/azure-resource-manager/bicep/bicep-functions-parameters-file.md

@@ -1,6 +1,6 @@
 ---
 title: Bicep functions - parameters file
-description: Describes the functions used in the Bicep parameters files.
+description: This article describes the Bicep functions to be used in Bicep parameter files.
 ms.topic: conceptual
 ms.custom: devx-track-bicep
 ms.date: 06/05/2023
@@ -10,6 +10,58 @@ ms.date: 06/05/2023
 
 Bicep provides a function called `readEnvironmentVariable()` that allows you to retrieve values from environment variables. It also offers the flexibility to set a default value if the environment variable does not exist. This function can only be used in the `.bicepparam` files. For more information, see [Bicep parameters file](./parameter-files.md).
 
+## getSecret
+
+`getSecret(subscriptionId, resourceGroupName, keyVaultName, secretName, secretVersion)`
+
+Returns a secret from an [Azure Key Vault](../../key-vault/secrets/about-secrets.md). Use this function to pass a secret to a secure string parameter of a Bicep file.
+
+> [!NOTE]
+> You can also use the [keyVaultName.getSecret(secretName)](./bicep-functions-resource.md#getsecret) function from within a `.bicep` file.
+
+```bicep
+using './main.bicep'
+
+param secureUserName = getSecret('exampleSubscription', 'exampleResourceGroup', 'exampleKeyVault', 'exampleSecretUserName')
+param securePassword = getSecret('exampleSubscription', 'exampleResourceGroup', 'exampleKeyVault', 'exampleSecretPassword')
+```
+
+You'll get an error if you use this function with string interpolation.
+
+A [namespace qualifier](bicep-functions.md#namespaces-for-functions) (`az`) can be used, but it's optional, because the function is available from the _default_ Azure Namespace.
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| subscriptionId | Yes | string | The ID of the subscription that has the key vault resource. |
+| resourceGroupName | Yes | string | The name of the resource group that has the key vault resource. |
+| keyVaultName | Yes | string | The name of the key vault. |
+| secretName | Yes | string | The name of the secret stored in the key vault. |
+| secretVersion | No | string | The version of the secret stored in the key vault. |
+
+### Return value
+
+The value for the secret.
+
+### Example
+
+The following `.bicepparam` file has a `securePassword` parameter that will have the latest value of the _\<secretName\>_ secret.
+
+```bicep
+using './main.bicep'
+
+param securePassword = getSecret('exampleSubscription', 'exampleResourceGroup', 'exampleKeyVault', 'exampleSecretPassword')
+```
+
+The following `.bicepparam` file has a `securePassword` parameter that will have the value of the _\<secretName\>_ secret, but it's pinned to a specific _\<secretValue\>_.
+
+```bicep
+using './main.bicep'
+
+param securePassword = getSecret('exampleSubscription', 'exampleResourceGroup', 'exampleKeyVault', 'exampleSecretPassword', 'exampleSecretVersion')
+```
+
 ## readEnvironmentVariable()
 
 `readEnvironmentVariable(variableName, [defaultValue])`

articles/azure-resource-manager/bicep/bicep-functions-resource.md

@@ -106,6 +106,9 @@ Built-in policy definitions are tenant level resources. For an example of deploy
 
 Returns a secret from an Azure Key Vault. Use this function to pass a secret to a secure string parameter of a Bicep module.
 
+> [!NOTE]
+> `az.getSecret(subscriptionId, resourceGroupName, keyVaultName, secretName, secretVersion)` function can be used in `.bicepparam` files to retrieve key vault secrets. For more information, see [getSecret](./bicep-functions-parameters-file.md#getsecret).
+
 You can only use the `getSecret` function from within the `params` section of a module. You can only use it with a `Microsoft.KeyVault/vaults` resource.
 
 ```bicep
@@ -117,7 +120,7 @@ module sql './sql.bicep' = {
 }
 ```
 
-You'll get an error if you attempt to use this function in any other part of the Bicep file. You'll also get an error if you use this function with string interpolation, even when used in the params section.
+You get an error if you attempt to use this function in any other part of the Bicep file. You also get an error if you use this function with string interpolation, even when used in the params section.
 
 The function can be used only with a module parameter that has the `@secure()` decorator.
 
@@ -137,7 +140,7 @@ The secret value for the secret name.
 
 ### Example
 
-The following Bicep file is used as a module.  It has an `adminPassword` parameter defined with the `@secure()` decorator.
+The following Bicep file is used as a module. It has an `adminPassword` parameter defined with the `@secure()` decorator.
 
 ```bicep
 param sqlServerName string

articles/azure-resource-manager/bicep/bicep-functions.md

@@ -123,6 +123,8 @@ The following functions are available for working with objects. All of these fun
 
 ## Parameters file functions
 
+The [getSecret function](./bicep-functions-parameters-file.md) is available in Bicep to get secure value from a KeyVault. This function is in the `az` namespace.
+
 The [readEnvironmentVariable function](./bicep-functions-parameters-file.md) is available in Bicep to read environment variable values. This function is in the `sys` namespace.
 
 ## Resource functions

articles/azure-resource-manager/bicep/key-vault-parameter.md

@@ -202,6 +202,15 @@ module sql './sql.bicep' = {
 }
 ```
 
+Also, `getSecret` function (or with the namespace qualifier `az.getSecret`) can be used in a `.bicepparam` file to retrieve the value of a secret from a key vault.
+
+```bicep
+using './main.bicep'
+
+param secureUserName = getSecret('exampleSubscription', 'exampleResourceGroup', 'exampleKeyVault', 'exampleSecretUserName', 'exampleSecretVersion')
+param securePassword = az.getSecret('exampleSubscription', 'exampleResourceGroup', 'exampleKeyVault', 'exampleSecretPassword')
+```
+
 ## Reference secrets in parameters file
 
 If you don't want to use a module, you can reference the key vault directly in the parameters file. The following image shows how the parameters file references the secret and passes that value to the Bicep file.

articles/azure-resource-manager/bicep/scenarios-secrets.md

@@ -80,6 +80,19 @@ module exampleModule 'module.bicep' = {
 }
 ```
 
+### Use a key vault in a .bicepparam file
+
+When you use `.bicepparam` file format, you can provide secure values to parameters by using [the `getSecret` function](bicep-functions-parameters-file.md#getsecret).
+
+Reference the KeyVault by providing the subscription ID, resource group name, and key vault name. You can get the value of the secret by providing the secret name. You can optionally provide the secret version. If you don't provide the secret version, the latest version is used.
+
+```bicep
+using './main.bicep'
+
+param secureUserName = az.getSecret('<subscriptionId>', '<resourceGroupName>', '<keyVaultName>', '<secretName>', '<secretVersion>')
+param securePassword = az.getSecret('<subscriptionId>', '<resourceGroupName>', '<keyVaultName>', '<secretName>')
+```
+
 ## Work with secrets in pipelines
 
 When you deploy your Azure resources by using a pipeline, you need to take care to handle your secrets appropriately.