[Wiki] Updated deployment & usage examples & further cleanup (#2389)

* Init cleanup * Further cleanup * Updated module usage * Latest update * Update to latest * Update to latest * Update to latest * Update to latest * Update docs/wiki/Solution creation.md Co-authored-by: Erika Gressi <[email protected]> * Update to latest * Update to latest Co-authored-by: Erika Gressi <[email protected]>
Azure · Nov 30, 2022 · 7ed7e76 · 7ed7e76
1 parent cc7ce0e
commit 7ed7e76
Show file tree

Hide file tree

Showing 8 changed files with 245 additions and 279 deletions.
diff --git a/.azuredevops/pipelineTemplates/jobs.getModuleTestFiles.yml b/.azuredevops/pipelineTemplates/jobs.getModuleTestFiles.yml
@@ -40,13 +40,7 @@ jobs:
 
             $testTable = @{}
             foreach ($deploymentTestPath in $deploymentTestPaths) {
-                if((Split-Path (Split-Path $deploymentTestPath) -Leaf) -ne '.test') {
-                  # Using test files in subfolders (e.g. '.test/deploy.test.json')
-                  $deploymentTestFileName = Split-Path (Split-Path $deploymentTestPath -Parent) -Leaf
-                } else {
-                  # Using parameter files (e.g. '.test/parameters.json')
-                  $deploymentTestFileName = Split-Path $deploymentTestPath -Leaf
-                }
+                $deploymentTestFileName = Split-Path (Split-Path $deploymentTestPath -Parent) -Leaf
                 $testTable[$deploymentTestFileName] += @{
                     moduleTestFilePath = $deploymentTestPath
                 }

diff --git a/docs/wiki/Solution creation.md b/docs/wiki/Solution creation.md
diff --git a/docs/wiki/The library - Module usage.md b/docs/wiki/The library - Module usage.md
@@ -7,6 +7,7 @@ This section provides a guideline on how to use the CARML Bicep modules.
 - [Deploy template](#deploy-template)
   - [PowerShell](#powershell)
   - [Azure CLI](#azure-cli)
+  - [As nested deployment](#as-nested-deployment)
 - [Orchestrate deployment](#orchestrate-deployment)
 ---
 
@@ -22,9 +23,10 @@ This sub-section gives you an example on how to deploy a template from your loca
 <summary><i>Resource Group</i> scope</summary>
 
 To be used if the targeted scope in the first line of the template is:
-- **Bicep:** `targetScope = 'resourceGroup'`
+- **Bicep:** `targetScope = 'resourceGroup'` or empty (as default)
 - **ARM:** `"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#"`
 
+Using parameter file
 ```PowerShell
 New-AzResourceGroup -Name 'ExampleGroup' -Location "Central US"
 
@@ -123,7 +125,7 @@ For more information, please refer to the official [Microsoft docs](https://docs
 <summary><i>Resource Group</i> scope</summary>
 
 To be used if the targeted scope in the first line of the template is:
-- **Bicep:** `targetScope = 'resourceGroup'`
+- **Bicep:** `targetScope = 'resourceGroup'` or empty (as default)
 - **ARM:** `"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#"`
 
 ```bash
@@ -217,6 +219,33 @@ For more information, please refer to the official [Microsoft docs](https://docs
 
 </details>
 
+# As nested deployment
+
+You can also reference modules in another template using the below syntax. To deploy this 'orchestration template' you can again use the commands described [above](#deploy-template). You can also find further information in the 'Template Orchestration' section of [Solution Creation](./Solution%20creation) site.
+
+```bicep
+// Using local reference
+module testDeployment 'ResourceModules/modules/Microsoft.KeyVaults/vaults/deploy.bicep' = {
+  scope: resourceGroup
+  name: '${uniqueString(deployment().name)}-example'
+  params: { ... }
+}
+
+// Using Template-Specs reference (with configuration file)
+module testDeployment 'ts/modules:microsoft.keyvaults.vaults:1.0.0' = {
+  scope: resourceGroup
+  name: '${uniqueString(deployment().name)}-example'
+  params: { ... }
+}
+
+// Using Bicep reference
+module testDeployment 'br:<registry-name>.azurecr.io/bicep/modules/microsoft.keyvaults.vaults:1.0.0' = {
+  scope: resourceGroup
+  name: '${uniqueString(deployment().name)}-example'
+  params: { ... }
+}
+```
+
 ---
 
 # Orchestrate deployment

diff --git a/utilities/pipelines/resourceDeployment/New-TemplateDeployment.ps1 b/utilities/pipelines/resourceDeployment/New-TemplateDeployment.ps1
@@ -102,16 +102,21 @@ Optional. Maximum retry limit if the deployment fails. Default is 3.
 Optional. Do not throw an exception if it failed. Still returns the error message though
 
 .EXAMPLE
-New-DeploymentWithParameterFile -templateFilePath 'C:/KeyVault/deploy.json' -parameterFilePath 'C:/KeyVault/.test/parameters.json' -location 'WestEurope' -resourceGroupName 'aLegendaryRg'
+New-TemplateDeploymentInner -templateFilePath 'C:/KeyVault/deploy.json' -parameterFilePath 'C:/KeyVault/.test/parameters.json' -location 'WestEurope' -resourceGroupName 'aLegendaryRg'
 
 Deploy the deploy.json of the KeyVault module with the parameter file 'parameters.json' using the resource group 'aLegendaryRg' in location 'WestEurope'
 
 .EXAMPLE
-New-DeploymentWithParameterFile -templateFilePath 'C:/ResourceGroup/deploy.json' -location 'WestEurope'
+New-TemplateDeploymentInner -templateFilePath 'C:/KeyVault/deploy.bicep' -location 'WestEurope' -resourceGroupName 'aLegendaryRg'
+
+Deploy the deploy.bicep of the KeyVault module using the resource group 'aLegendaryRg' in location 'WestEurope'
+
+.EXAMPLE
+New-TemplateDeploymentInner -templateFilePath 'C:/ResourceGroup/deploy.json' -location 'WestEurope'
 
 Deploy the deploy.json of the ResourceGroup module without a parameter file in location 'WestEurope'
 #>
-function New-DeploymentWithParameterFile {
+function New-TemplateDeploymentInner {
 
     [CmdletBinding(SupportsShouldProcess = $true)]
     param (
@@ -374,7 +379,7 @@ Deploy the deploy.bicep of the KeyVault module with the parameter file 'paramete
 .EXAMPLE
 New-TemplateDeployment -templateFilePath 'C:/ResourceGroup/deploy.bicep' -location 'WestEurope'
 
-Deploy the deploy.json of the ResourceGroup module in location 'WestEurope'
+Deploy the deploy.bicep of the ResourceGroup module in location 'WestEurope' without a parameter file
 
 .EXAMPLE
 New-TemplateDeployment -templateFilePath 'C:/ResourceGroup/deploy.json' -parameterFilePath 'C:/ResourceGroup/.test/parameters.json' -location 'WestEurope'
@@ -445,18 +450,18 @@ function New-TemplateDeployment {
                 $deploymentResult = [System.Collections.ArrayList]@()
                 foreach ($path in $parameterFilePath) {
                     if ($PSCmdlet.ShouldProcess("Deployment for parameter file [$parameterFilePath]", 'Trigger')) {
-                        $deploymentResult += New-DeploymentWithParameterFile @deploymentInputObject -parameterFilePath $path
+                        $deploymentResult += New-TemplateDeploymentInner @deploymentInputObject -parameterFilePath $path
                     }
                 }
                 return $deploymentResult
             } else {
                 if ($PSCmdlet.ShouldProcess("Deployment for single parameter file [$parameterFilePath]", 'Trigger')) {
-                    return New-DeploymentWithParameterFile @deploymentInputObject -parameterFilePath $parameterFilePath
+                    return New-TemplateDeploymentInner @deploymentInputObject -parameterFilePath $parameterFilePath
                 }
             }
         } else {
             if ($PSCmdlet.ShouldProcess('Deployment without parameter file', 'Trigger')) {
-                return New-DeploymentWithParameterFile @deploymentInputObject
+                return New-TemplateDeploymentInner @deploymentInputObject
             }
         }
     }

diff --git a/utilities/pipelines/resourceRemoval/Initialize-DeploymentRemoval.ps1 b/utilities/pipelines/resourceRemoval/Initialize-DeploymentRemoval.ps1
@@ -18,9 +18,9 @@ Optional. The name of the resource group the deployment was happening in. Releva
 Optional. The ID of the management group to fetch deployments from. Relevant for management-group level deployments.
 
 .EXAMPLE
-Initialize-DeploymentRemoval -DeploymentName 'virtualWans-20211204T1812029146Z' -TemplateFilePath "$home/ResourceModules/modules/Microsoft.Network/virtualWans/deploy.bicep" -resourceGroupName 'test-virtualWan-parameters.json-rg'
+Initialize-DeploymentRemoval -DeploymentName 'virtualWans-20211204T1812029146Z' -TemplateFilePath "$home/ResourceModules/modules/Microsoft.Network/virtualWans/deploy.bicep" -resourceGroupName 'test-virtualWan-rg'
 
-Remove the deployment 'virtualWans-20211204T1812029146Z' from resource group 'test-virtualWan-parameters.json-rg' that was executed using template in path "$home/ResourceModules/modules/Microsoft.Network/virtualWans/deploy.bicep"
+Remove the deployment 'virtualWans-20211204T1812029146Z' from resource group 'test-virtualWan-rg' that was executed using template in path "$home/ResourceModules/modules/Microsoft.Network/virtualWans/deploy.bicep"
 #>
 function Initialize-DeploymentRemoval {
 

diff --git a/utilities/pipelines/resourceRemoval/helper/Get-ResourceIdsAsFormattedObjectList.ps1 b/utilities/pipelines/resourceRemoval/helper/Get-ResourceIdsAsFormattedObjectList.ps1
@@ -9,10 +9,10 @@ Format the provide resource IDs into objects of resourceID, name & type
 Optional. The resource IDs to process
 
 .EXAMPLE
-Get-ResourceIdsAsFormattedObjectList -ResourceIds @('/subscriptions/<subscriptionID>/resourceGroups/test-analysisServices-parameters.json-rg/providers/Microsoft.Storage/storageAccounts/adpsxxazsaaspar01')
+Get-ResourceIdsAsFormattedObjectList -ResourceIds @('/subscriptions/<subscriptionID>/resourceGroups/test-analysisServices-rg/providers/Microsoft.Storage/storageAccounts/adpsxxazsaaspar01')
 
 Returns an object @{
-    resourceId = '/subscriptions/<subscriptionID>/resourceGroups/test-analysisServices-parameters.json-rg/providers/Microsoft.Storage/storageAccounts/adpsxxazsaaspar01'
+    resourceId = '/subscriptions/<subscriptionID>/resourceGroups/test-analysisServices-rg/providers/Microsoft.Storage/storageAccounts/adpsxxazsaaspar01'
     type       = 'Microsoft.Storage/storageAccounts'
     name       = 'adpsxxazsaaspar01'
 }

diff --git a/utilities/pipelines/staticValidation/module.tests.ps1 b/utilities/pipelines/staticValidation/module.tests.ps1
@@ -117,7 +117,7 @@ Describe 'File/folder tests' -Tag Modules {
             }
         }
 
-        It '[<moduleFolderName>] folder should contain one or more *parameters.json files' -TestCases $folderTestCases {
+        It '[<moduleFolderName>] folder should contain one or more test files' -TestCases $folderTestCases {
 
             param(
                 [string] $moduleFolderName,
@@ -141,7 +141,7 @@ Describe 'File/folder tests' -Tag Modules {
             }
         }
 
-        It '[<moduleFolderName>] *parameters.json files in the .test folder should be valid json' -TestCases $testFolderFilesTestCases {
+        It '[<moduleFolderName>] JSON test files in the .test folder should be valid json' -TestCases $testFolderFilesTestCases {
 
             param(
                 [string] $moduleFolderName,
@@ -150,7 +150,7 @@ Describe 'File/folder tests' -Tag Modules {
             if ((Split-Path $testFilePath -Extension) -eq '.json') {
                 { (Get-Content $testFilePath) | ConvertFrom-Json } | Should -Not -Throw
             } else {
-                Set-ItResult -Skipped -Because 'the module has no JSON parameter file.'
+                Set-ItResult -Skipped -Because 'the module has no JSON test files.'
             }
         }
     }

diff --git a/utilities/tools/Test-ModuleLocally.ps1 b/utilities/tools/Test-ModuleLocally.ps1
@@ -55,6 +55,29 @@ Run a Test-Az*Deployment using a specific parameter-template combination with th
 
 .EXAMPLE
 
+$TestModuleLocallyInput = @{
+    TemplateFilePath           = 'C:\Microsoft.Network\routeTables\deploy.bicep'
+    ModuleTestFilePath          = 'C:\Microsoft.Network\routeTables\.test\common\deploy.test.bicep'
+    PesterTest                 = $false
+    DeploymentTest             = $false
+    ValidationTest             = $true
+    ValidateOrDeployParameters = @{
+        Location          = 'westeurope'
+        ResourceGroupName = 'validation-rg'
+        SubscriptionId    = '00000000-0000-0000-0000-000000000000'
+        ManagementGroupId = '00000000-0000-0000-0000-000000000000'
+        RemoveDeployment  = $false
+    }
+    AdditionalTokens           = @{
+        deploymentSpId = '00000000-0000-0000-0000-000000000000'
+    }
+}
+Test-ModuleLocally @TestModuleLocallyInput -Verbose
+
+Run a Test-Az*Deployment using a test file with the provided tokens
+
+.EXAMPLE
+
 $TestModuleLocallyInput = @{
     TemplateFilePath           = 'C:\Microsoft.Network\routeTables\deploy.bicep'
     PesterTest                 = $true