Merge pull request #120346 from Cadacious/users/scady/update-arm-template-deployment-doc

bicepparam usage in azure pipelines

Author: ShannonLeavitt

articles/azure-resource-manager/bicep/add-template-to-azure-pipelines.md

@@ -1,9 +1,9 @@
 ---
-title: CI/CD with Azure Pipelines and Bicep files
-description: In this quickstart, you learn how to configure continuous integration in Azure Pipelines by using Bicep files. It shows how to use an Azure CLI task to deploy a Bicep file.
+title: CI/CD with Azure Pipelines, Bicep, and bicepparam files
+description: In this quickstart, you learn how to configure continuous integration in Azure Pipelines by using Bicep and bicepparam files. It shows how to use an Azure CLI task to deploy a bicepparam file.
 ms.topic: quickstart
 ms.custom: devx-track-bicep, devx-track-azurecli
-ms.date: 06/21/2023
+ms.date: 02/29/2024
 ---
 
 # Quickstart: Integrate Bicep with Azure Pipelines
@@ -22,6 +22,8 @@ You need to have configured a [service connection](/azure/devops/pipelines/libra
 
 You need a [Bicep file](./quickstart-create-bicep-use-visual-studio-code.md) that defines the infrastructure for your project. This file is in a repository.
 
+You need a [bicepparam file](/azure/azure-resource-manager/bicep/parameter-files) that defines the parameters used by your bicep file. This file is in a repository.
+
 ## Create pipeline
 
 1. From your Azure DevOps organization, select **Pipelines** and **Create pipeline**.
@@ -47,88 +49,101 @@ You can use Azure Resource Group Deployment task or Azure CLI task to deploy a B
 ### Use Azure Resource Manager Template Deployment task
 
 > [!NOTE]
-> *AzureResourceManagerTemplateDeployment@3* task won't work if you have a *bicepparam* file.
+> As of version 3.235.0 of the [Azure Resource Manager Template Deployment task](/azure/devops/pipelines/tasks/reference/azure-resource-manager-template-deployment-v3), usage of [bicepparam](/azure/azure-resource-manager/bicep/parameter-files) files is supported.
+
+> [!NOTE]
+> The `AzureResourceManagerTemplateDeployment@3` task requires both Bicep and bicepparam files be provided when using bicepparam. The Bicep file can reference all supported locations for module references. The bicepparam file must reference the local Bicep file in the `using` statement.
 
-1. Replace your starter pipeline with the following YAML. It creates a resource group and deploys a Bicep file by using an [Azure Resource Manager Template Deployment task](/azure/devops/pipelines/tasks/reference/azure-resource-manager-template-deployment-v3).
+1. Replace your starter pipeline with the following YAML. It creates a resource group and deploys a Bicep and bicepparam file by using the Azure Resource Manager Template Deployment task.
 
     ```yml
     trigger:
     - main
 
     name: Deploy Bicep files
 
+    parameters:
+      azureServiceConnection: '<your-connection-name>'
+
     variables:
       vmImageName: 'ubuntu-latest'
-
-      azureServiceConnection: '<your-connection-name>'
       resourceGroupName: 'exampleRG'
       location: '<your-resource-group-location>'
       templateFile: './main.bicep'
+      csmParametersFile: './main.bicepparam'
+
     pool:
       vmImage: $(vmImageName)
 
     steps:
     - task: AzureResourceManagerTemplateDeployment@3
       inputs:
         deploymentScope: 'Resource Group'
-        azureResourceManagerConnection: '$(azureServiceConnection)'
+        azureSubscription: '${{ parameters.azureServiceConnection }}'
         action: 'Create Or Update Resource Group'
         resourceGroupName: '$(resourceGroupName)'
         location: '$(location)'
         templateLocation: 'Linked artifact'
         csmFile: '$(templateFile)'
+        csmParametersFile: '$(csmParametersFile)'
         overrideParameters: '-storageAccountType Standard_LRS'
         deploymentMode: 'Incremental'
         deploymentName: 'DeployPipelineTemplate'
     ```
 
 1. Update the values of `azureServiceConnection` and `location`.
-1. Verify you have a `main.bicep` in your repo, and the content of the Bicep file.
+1. Verify you have a valid `main.bicep` file in your repo.
+1. Verify you have a valid `main.bicepparam` file in your repo that contains a [using](/azure/azure-resource-manager/bicep/bicep-using) statement.
 1. Select **Save**. The build pipeline automatically runs. Go back to the summary for your build pipeline, and watch the status.
 
 ### Use Azure CLI task
 
-1. Replace your starter pipeline with the following YAML. It creates a resource group and deploys a Bicep file by using an [Azure CLI task](/azure/devops/pipelines/tasks/reference/azure-cli-v2):
+> [!NOTE]
+> The [az deployment group create](/cli/azure/deployment/group?view=azure-cli-latest#az-deployment-group-create&preserve-view=true) command requires only a bicepparam file. The `using` statement in the bicepparam file can target any supported location to reference the Bicep file. A Bicep file is only required in your repository when `using` from a local disk path with Azure CLI.
+
+> [!NOTE]
+> When you use a *[bicepparam](/azure/azure-resource-manager/bicep/parameter-files)* file with the [az deployment group create](/cli/azure/deployment/group?view=azure-cli-latest#az-deployment-group-create&preserve-view=true) command, you can't override parameters.
+
+1. Replace your starter pipeline with the following YAML. It creates a resource group and deploys a [bicepparam](/azure/azure-resource-manager/bicep/parameter-files) file by using an [Azure CLI task](/azure/devops/pipelines/tasks/reference/azure-cli-v2):
 
     ```yml
     trigger:
     - main
 
     name: Deploy Bicep files
 
+    parameters:
+      azureServiceConnection: '<your-connection-name>'
+
     variables:
       vmImageName: 'ubuntu-latest'
-
-      azureServiceConnection: '<your-connection-name>'
       resourceGroupName: 'exampleRG'
       location: '<your-resource-group-location>'
-      templateFile: 'main.bicep'
+      bicepParamFile: './main.bicepparam'
+
     pool:
       vmImage: $(vmImageName)
 
     steps:
     - task: AzureCLI@2
       inputs:
-        azureSubscription: $(azureServiceConnection)
+        azureSubscription: '${{ parameters.azureServiceConnection }}'
         scriptType: bash
         scriptLocation: inlineScript
         useGlobalConfig: false
         inlineScript: |
           az --version
           az group create --name $(resourceGroupName) --location $(location)
-          az deployment group create --resource-group $(resourceGroupName) --template-file $(templateFile)
-    ```
-
-    To override the parameters, update the last line of `inlineScript` to:
-
-    ```bicep
-    az deployment group create --resource-group $(resourceGroupName) --template-file $(templateFile) --parameters storageAccountType='Standard_GRS' location='eastus'
+          az deployment group create `
+            --resource-group $(resourceGroupName) `
+            --parameters $(bicepParamFile) `
+            --name DeployPipelineTemplate
     ```
 
     For the descriptions of the task inputs, see [Azure CLI task](/azure/devops/pipelines/tasks/reference/azure-cli-v2). When using the task on air-gapped cloud, you must set the `useGlobalConfig` property of the task to `true`. The default value is `false`.
 
 1. Update the values of `azureServiceConnection` and `location`.
-1. Verify you have a `main.bicep` in your repo, and the content of the Bicep file.
+1. Verify you have a valid `main.bicepparam` file in your repo that contains a [using](/azure/azure-resource-manager/bicep/bicep-using) statement.
 1. Select **Save**. The build pipeline automatically runs. Go back to the summary for your build pipeline, and watch the status.
 
 ## Clean up resources