Adding tests and documentation for conversion script

.github/workflows/platform.convertToArmTemplate.tests.yml

@@ -0,0 +1,50 @@
+name: '.Platform: Test - ConvertTo-ARMTemplate.ps1'
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'utilities/tools/ConvertTo-ARMTemplate.ps1'
+      - 'utilities/tools/tests/ConvertTo-ARMTemplate**'
+
+jobs:
+  job_test_convert:
+    runs-on: ubuntu-latest
+    name: 'Test with parameter'
+    strategy:
+      fail-fast: false
+      matrix:
+        tags: ['Default', 'ConvertChildren', 'Skip']
+    steps:
+      - name: 'Checkout'
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: 'Run Pester tests'
+        shell: pwsh
+        run: |
+          Invoke-Pester -Configuration @{
+            Run        = @{
+              Path = @(
+                Join-Path "$env:GITHUB_WORKSPACE" 'utilities' 'tools' 'tests' 'ConvertTo-ARMTemplate.Tests.ps1'
+              )
+            }
+            Filter     = @{
+              Tag = '${{ matrix.tags }}'
+            }
+            TestResult = @{
+              TestSuiteName = 'Conversion Tests'
+              OutputPath    = Join-Path "$env:GITHUB_WORKSPACE" 'utilities' 'tools' 'tests' 'conversion-testResults-${{ matrix.tags }}.xml'
+              OutputFormat  = 'JUnitXml'
+              Enabled       = $true
+            }
+            Output     = @{
+              Verbosity = 'Detailed'
+            }
+          }
+      - name: Publish Test Results
+        uses: EnricoMi/publish-unit-test-result-action@v1
+        if: always()
+        with:
+          files: 'utilities/tools/tests/conversion-testResults-${{ matrix.tags }}.xml'

docs/wiki/Home.md

@@ -20,6 +20,8 @@ If you're unfamiliar with Infrastructure as Code, or wonder how you can use the
 - [Testing](./Testing)
   - [Design](./TestingDesign)
   - [Usage](./TestingUsage)
+- [Utilities](./Utilities.md)
+  - [Bicep to ARM conversion script](./UtilitiesConversionScript.md)
 - [Pipelines](./Pipelines)
   - [Design](./PipelinesDesign)
   - [Usage](./PipelinesUsage)

docs/wiki/Utilities.md

@@ -0,0 +1,11 @@
+# Utilities
+
+This section and its sub-sections describe tools and utilities provided in this repository.
+
+---
+
+### _Navigation_
+
+- [Bicep to ARM conversion script](./UtilitiesConversionScript.md)
+
+---

docs/wiki/UtilitiesConversionScript.md

@@ -0,0 +1,52 @@
+# Bicep to ARM conversion script
+
+At the time of writing bicep is still in a beta phase. For this reason, some people may want to wait for bicep's _General Availability_ and prefer to use ARM Templates for the time being.
+For these scenarios, the CARML library provides a script that uses the Bicep Toolkit translator/compiler to support the conversion of CARML Bicep modules to ARM templates.
+This page documents the conversion utility and how to use it.
+
+---
+
+### _Navigation_
+
+- [Location](#location)
+- [What it does](#what-it-does)
+- [How to use it](#how-to-use-it)
+  - [Examples](#examples)
+
+---
+# Location
+
+`You can find the script under /utilities/tools/ConvertTo-ARMTemplate.ps1`
+
+# What it does
+
+The script finds all 'deploy.bicep' files and tries to convert them to json-based ARM templates
+by using the following steps.
+1. Remove existing deploy.json files
+1. Convert bicep files to json
+1. Remove bicep metadata from json
+1. Remove bicep files and folders
+1. Update pipeline files - Replace .bicep with .json in pipeline files
+# How to use it
+
+The script can be called with the following parameters:
+
+| name | description |
+|-|-|
+| -Path | The path to the root of the repo. |
+| -ConvertChildren | Convert child resource modules to bicep. |
+| -SkipMetadataCleanup | Skip Cleanup of bicep metadata from json files |
+| -SkipBicepCleanUp | Skip removal of bicep files and folders |
+| -SkipPipelineUpdate | Skip replacing .bicep with .json in pipeline files |
+
+## Examples
+
+Converts top level bicep modules to json based ARM template, cleaning up all bicep files and folders and updating the workflow files to use the json files.
+```powershell
+. .\utilities\tools\ConvertTo-ARMTemplate.ps1
+```
+
+Only converts top level bicep modules to json based ARM template, keeping metadata in json, keeping all bicep files and folders, and not updating workflows.
+```powershell
+. .\utilities\tools\ConvertTo-ARMTemplate.ps1 -ConvertChildren -SkipMetadataCleanup -SkipBicepCleanUp -SkipWorkflowUpdate
+```

docs/wiki/_Sidebar.md

@@ -9,6 +9,7 @@
 - [Testing](./Testing)
   - [Design](./TestingDesign)
   - [Usage](./TestingUsage)
+- [Utilities](./Utilities.md)
 - [Pipelines](./Pipelines)
   - [Design](./PipelinesDesign)
     - [Parameter File Tokens](./ParameterFileTokens)

utilities/tools/ConvertTo-ARMTemplate.ps1

@@ -23,16 +23,16 @@ Optional. Skip Cleanup of Bicep metadata from json files
 .PARAMETER SkipBicepCleanUp
 Optional. Skip removal of bicep files and folders
 
-.PARAMETER SkipWorkflowUpdate
+.PARAMETER SkipPipelineUpdate
 Optional. Skip replacing .bicep with .json in workflow files
 
 .EXAMPLE
 . .\utilities\tools\ConvertTo-ARMTemplate.ps1
 
-Converts top level bicep modules to json based ARM template, cleaning up all bicep files and folders and updating the workflow files to use the json files.
+Converts top level bicep modules to json-based ARM template, cleaning up all bicep files and folders and updating the workflow files to use the json files.
 
 .EXAMPLE
-. .\utilities\tools\ConvertTo-ARMTemplate.ps1 -ConvertChildren -SkipMetadataCleanup -SkipBicepCleanUp -SkipWorkflowUpdate
+. .\utilities\tools\ConvertTo-ARMTemplate.ps1 -ConvertChildren -SkipMetadataCleanup -SkipBicepCleanUp -SkipPipelineUpdate
 
 Only converts top level bicep modules to json based ARM template, keeping metadata in json, keeping all bicep files and folders, and not updating workflows.
 
@@ -52,7 +52,7 @@ param (
     [switch] $SkipBicepCleanUp,
 
     [Parameter(Mandatory = $false)]
-    [switch] $SkipWorkflowUpdate
+    [switch] $SkipPipelineUpdate
 )
 
 $rootPath = Get-Item -Path $Path | Select-Object -ExpandProperty 'FullName'
@@ -80,8 +80,10 @@ Write-Verbose 'Convert bicep files to json'
 
 Write-Verbose "Convert bicep files to json - Processing [$($BicepFilesToConvert.count)] file(s)"
 if ($PSCmdlet.ShouldProcess("[$($BicepFilesToConvert.count)] deploy.bicep file(s) in path [$armFolderPath]", 'az bicep build')) {
-    $BicepFilesToConvert | ForEach-Object -ThrottleLimit $env:NUMBER_OF_PROCESSORS -Parallel {
-        Invoke-Expression -Command "az bicep build --file '$_'"
+    # parallelism is not supported on GitHub runners
+    #$BicepFilesToConvert | ForEach-Object -ThrottleLimit $env:NUMBER_OF_PROCESSORS -Parallel {
+    $BicepFilesToConvert | ForEach-Object {
+        az bicep build --file $_
     }
 }
 
@@ -94,8 +96,9 @@ if (-not $SkipMetadataCleanup) {
 
     Write-Verbose "Remove Bicep metadata from json - Processing [$($BicepFilesToConvert.count)] file(s)"
     if ($PSCmdlet.ShouldProcess("[$($BicepFilesToConvert.count)] deploy.bicep file(s) in path [$armFolderPath]", 'Set-Content')) {
-        $BicepFilesToConvert | ForEach-Object -ThrottleLimit $env:NUMBER_OF_PROCESSORS -Parallel {
-
+        # parallelism is not supported on GitHub runners
+        #$BicepFilesToConvert | ForEach-Object -ThrottleLimit $env:NUMBER_OF_PROCESSORS -Parallel {
+        $BicepFilesToConvert | ForEach-Object {
             function Remove-JSONMetadata {
                 <#
             .SYNOPSIS
@@ -164,21 +167,38 @@ if (-not $SkipBicepCleanUp) {
 }
 #endregion
 
-#region Update workflow files - Replace .bicep with .json in workflow files
-if (-not $SkipWorkflowUpdate) {
-    Write-Verbose 'Update workflow files'
+#region Update pipeline files - Replace .bicep with .json in workflow files
+if (-not $SkipPipelineUpdate) {
+    Write-Verbose 'Update pipeline files'
+
+    # GitHub workflow files
+    $ghWorkflowFolderPath = Join-Path -Path $rootPath -ChildPath '.github\workflows'
+    $ghWorkflowFilesToUpdate = Get-ChildItem -Path $ghWorkflowFolderPath -Filter 'ms.*.yml' -File -Force
+    Write-Verbose ('Update workflow files - Processing [{0}] file(s)' -f $ghWorkflowFilesToUpdate.count)
+    if ($PSCmdlet.ShouldProcess(('[{0}] ms.*.yml file(s) in path [{1}]' -f $ghWorkflowFilesToUpdate.Count, $ghWorkflowFolderPath), 'Set-Content')) {
+        # parallelism is not supported on GitHub runners
+        #$ghWorkflowFilesToUpdate | ForEach-Object -ThrottleLimit $env:NUMBER_OF_PROCESSORS -Parallel {
+        $ghWorkflowFilesToUpdate | ForEach-Object {
+            $content = $_ | Get-Content
+            $content = $content -replace 'templateFilePath:(.*).bicep', 'templateFilePath:$1.json'
+            $_ | Set-Content -Value $content
+        }
+    }
 
-    $workflowFolderPath = Join-Path -Path $rootPath -ChildPath '.github\workflows'
-    $workflowFilesToUpdate = Get-ChildItem -Path $workflowFolderPath -Filter 'ms.*.yml' -File -Force
-    Write-Verbose "Update workflow files - Processing [$($workflowFilesToUpdate.count)] file(s)"
-    if ($PSCmdlet.ShouldProcess("[$($workflowFilesToUpdate.count)] ms.*.yml file(s) in path [$armFolderPath]", 'Set-Content')) {
-        $workflowFilesToUpdate | ForEach-Object -ThrottleLimit $env:NUMBER_OF_PROCESSORS -Parallel {
+    # Azure DevOps Pipelines
+    $adoPipelineFolderPath = Join-Path -Path $rootPath -ChildPath '.azuredevops\modulePipelines'
+    $adoPipelineFilesToUpdate = Get-ChildItem -Path $adoPipelineFolderPath -Filter 'ms.*.yml' -File -Force
+    Write-Verbose ('Update Azure DevOps pipeline files - Processing [{0}] file(s)' -f $adoPipelineFilesToUpdate.count)
+    if ($PSCmdlet.ShouldProcess(('[{0}] ms.*.yml file(s) in path [{1}]' -f $adoPipelineFilesToUpdate.Count, $adoPipelineFolderPath), 'Set-Content')) {
+        # parallelism is not supported on GitHub runners
+        #$adoPipelineFilesToUpdate | ForEach-Object -ThrottleLimit $env:NUMBER_OF_PROCESSORS -Parallel {
+        $adoPipelineFilesToUpdate | ForEach-Object {
             $content = $_ | Get-Content
-            $content = $content.Replace('deploy.bicep', 'deploy.json')
+            $content = $content -replace 'templateFilePath:(.*).bicep', 'templateFilePath:$1.json'
             $_ | Set-Content -Value $content
         }
     }
 
-    Write-Verbose 'Update workflow files - Done'
+    Write-Verbose 'Update pipeline files - Done'
 }
 #endregion