[Utilities] Improve API version tests through the AzureAPICrawler PowerShell module

.azuredevops/pipelineTemplates/jobs.validateModulePester.yml

@@ -163,12 +163,18 @@ jobs:
             # --------------------- #
             # Invoke Pester test(s) #
             # --------------------- #
+            $testContainerData = @{
+              moduleFolderPaths              = $moduleFolderPaths
+              tokenConfiguration             = $tokenConfiguration
+              allowPreviewVersionsInAPITests = [System.Convert]::ToBoolean('$(ALLOWPREVIEWVERSIONSINAPITESTS)')
+            }
+
+            Write-Verbose 'Invoke test with' -Verbose
+            Write-Verbose ($testContainerData | ConvertTo-Json | Out-String) -Verbose
+
             Invoke-Pester -Configuration @{
               Run        = @{
-                  Container = New-PesterContainer -Path (Join-Path $repoRootPath $moduleTestFilePath) -Data @{
-                  moduleFolderPaths  = $moduleFolderPaths
-                  tokenConfiguration = $tokenConfiguration
-                }
+                  Container = New-PesterContainer -Path (Join-Path $repoRootPath $moduleTestFilePath) -Data $testContainerData
               }
               TestResult = @{
                 TestSuiteName = 'Module Tests'

.azuredevops/platformPipelines/platform.apiSpecs.yml

@@ -0,0 +1,62 @@
+name: '.Platform - Update API Specs file'
+
+pr: none
+
+schedules:
+- cron: "0 12 * * 0"
+  displayName: Weekly Sunday Update
+  branches:
+    include:
+    - main
+
+variables:
+  - template: '../../settings.yml'
+  - name: pipelinePrincipalGitUserName
+    value: 'CARMLPipelinePrincipal'
+  - name: pipelinePrincipalGitUserEmail
+    value: 'CARML@noreply.github.com'
+
+jobs:
+  - job: Update_API_Specs_file
+    pool:
+      ${{ if ne(variables.vmImage, '') }}:
+        vmImage: ${{ variables.vmImage }}
+      ${{ if ne(variables.poolName, '') }}:
+        name: ${{ variables.poolName }}
+    steps:
+      - checkout: self
+        persistCredentials: true
+
+      - task: PowerShell@2
+        displayName: 'Update file'
+        inputs:
+          targetType: inline
+          pwsh: true
+          script: |
+            # Load used functions
+            . (Join-Path '$(System.DefaultWorkingDirectory)' 'utilities' 'tools' 'platform' 'Set-ApiSpecsFile.ps1')
+
+            $functionInput = @{
+              SpecsFilePath  = Join-Path '$(System.DefaultWorkingDirectory)' 'utilities' 'src' 'apiSpecsList.json'
+              IncludePreview = $true
+            }
+
+            Write-Verbose "Invoke task with" -Verbose
+            Write-Verbose ($functionInput | ConvertTo-Json | Out-String) -Verbose
+
+            Set-ApiSpecsFile @functionInput -Verbose
+
+      - task: PowerShell@2
+        displayName: 'Push changes'
+        inputs:
+          targetType: inline
+          pwsh: true
+          script: |
+            git config --global user.email '$(pipelinePrincipalGitUserEmail)'
+            git config --global user.name '$(pipelinePrincipalGitUserName)'
+
+            git add .
+            git status
+            git commit -m 'Push updated API Specs file'
+            git pull $(Build.Repository.Uri) HEAD:$(Build.SourceBranch)
+            git push $(Build.Repository.Uri) HEAD:$(Build.SourceBranch)

.github/actions/templates/setEnvironmentVariables/action.yml

@@ -75,6 +75,6 @@ runs:
         Write-Verbose ($functionInput | ConvertTo-Json | Out-String) -Verbose
 
         # Convert YAML Variable File to Environment Variables
-        Add-YamlListToFile @functionInput -Verbose
+        Add-YamlListToFile @functionInput
 
         Write-Output '::endgroup::'

.github/actions/templates/validateModulePester/action.yml

@@ -123,12 +123,18 @@ runs:
         # --------------------- #
         # Invoke Pester test(s) #
         # --------------------- #
+        $testContainerData = @{
+          moduleFolderPaths              = $moduleFolderPaths
+          tokenConfiguration             = $tokenConfiguration
+          allowPreviewVersionsInAPITests = [System.Convert]::ToBoolean('${{ env.allowPreviewVersionsInAPITests }}')
+        }
+
+        Write-Verbose 'Invoke test with' -Verbose
+        Write-Verbose ($testContainerData | ConvertTo-Json | Out-String) -Verbose
+
         Invoke-Pester -Configuration @{
           Run        = @{
-              Container = New-PesterContainer -Path (Join-Path $repoRootPath $moduleTestFilePath) -Data @{
-              moduleFolderPaths  = $moduleFolderPaths
-              tokenConfiguration = $tokenConfiguration
-            }
+            Container = New-PesterContainer -Path (Join-Path $repoRootPath $moduleTestFilePath) -Data $testContainerData
           }
           TestResult = @{
             TestSuiteName = 'Module Tests'

.github/workflows/platform.apiSpecs.yml

@@ -0,0 +1,48 @@
+name: '.Platform: Update API Specs file'
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 12 * * 0' # Weekly Sunday Update
+
+env:
+  pipelinePrincipalGitUserName: 'CARMLPipelinePrincipal'
+  pipelinePrincipalGitUserEmail: 'CARML@noreply.github.com'
+
+jobs:
+  job_update_api_specs_file:
+    runs-on: ubuntu-20.04
+    name: 'Update file'
+    steps:
+      - name: 'Checkout'
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          token: '${{ secrets.PLATFORM_REPO_UPDATE_PAT }}' # Sets general GIT credentials up
+      - name: 'Update file'
+        shell: pwsh
+        run: |
+          # Load used functions
+          . (Join-Path $env:GITHUB_WORKSPACE 'utilities' 'tools' 'platform' 'Set-ApiSpecsFile.ps1')
+
+          $functionInput = @{
+            SpecsFilePath  = Join-Path $env:GITHUB_WORKSPACE 'utilities' 'src' 'apiSpecsList.json'
+            IncludePreview = $true
+          }
+
+          Write-Verbose "Invoke task with" -Verbose
+          Write-Verbose ($functionInput | ConvertTo-Json | Out-String) -Verbose
+
+          Set-ApiSpecsFile @functionInput -Verbose
+
+      - name: 'Push changes'
+        shell: pwsh
+        run: |
+          git config --global user.email '${{ env.pipelinePrincipalGitUserEmail }}'
+          git config --global user.name '${{ env.pipelinePrincipalGitUserName }}'
+
+          git pull
+          git status
+          git add .
+          git commit -m 'Push updated API Specs file'
+          git push

docs/wiki/The CI environment - Static validation.md

@@ -18,7 +18,7 @@ The following activities are performed by the [`utilities/pipelines/staticValida
 
 - **File & folder tests** validate that the module folder structure is set up in the intended way, e.g.:
   - readme.md file exists
-  - template file (either deploy.json or deploy.bicep) exists
+  - template file (either `deploy.json` or `deploy.bicep`) exists
   - compliance with file naming convention
 - **Deployment template tests** check the template's structure and elements for errors as well as consistency matters, e.g.:
   - template file (or the built bicep template) converts from JSON and has all expected properties
@@ -54,6 +54,14 @@ In particular, each resource's API version is compared with those currently avai
 
 This test also leverages the [`utilities/pipelines/staticValidation/module.tests.ps1`](https://github.com/Azure/ResourceModules/blob/main/utilities/pipelines/staticValidation/module.tests.ps1) script.
 
+To test the API versions, the test leverages the file `utilities/src/apiSpecsList.json` file as a reference for all API versions available for any used Provider Namespace & Resource Type.
+
+> **NOTE:** If this file does not exist, the API tests will be skipped.
+
+> **NOTE:** This functionality has a dependency on the [AzureAPICrawler](https://www.powershellgallery.com/packages/AzureAPICrawler) PowerShell module.
+
+The pipeline `platform.apiSpecs.yml` updates this file using the script `utilities/tools/platform/Set-ApiSpecsFile.ps1` and, once registered, runs on a weekly schedule. Upon execution, the script installs & imports the `AzureAPICrawler` module, fetches all available API versions for all Resource Types via the module and updates the JSON file according to the latest information.
+
 # Verify the static validation of your module locally
 
 This paragraph is intended for CARML contributors or more generally for those leveraging the CARML CI environment and having the need to update or add a new module to the library.

settings.yml

@@ -7,59 +7,65 @@ variables:
   # See: https://github.com/Azure/ResourceModules/wiki/The%20library%20-%20Module%20design#telemetry
   enableDefaultTelemetry: true
 
-  ######################################
-  # Local tokens settings
-  ######################################
+  ########################
+  ##   Token settings   ##
+  ########################
 
   # the 'localToken_' prefix will be removed from the key name when the pipelines run.
   # e.g. if you have a token in your parameter file as <<customKey>>, then the token defined in this file looks like "localToken_customKey": 'value'
   localToken_namePrefix: '' # A 3-5 character length unique string, included in the resources names (e.g. 'cntso'). Used for local module testing and pipelines.
 
-  ######################################
-  # global tokens settings
-  ######################################
-
   # this determines the starting prefix and ending suffix of the token in your file.
   tokenPrefix: '<<'
   tokenSuffix: '>>'
 
-  ######################################
-  # Agent settings
-  ######################################
+  ########################
+  ##   Agent settings   ##
+  ########################
 
   vmImage: 'ubuntu-latest' # Use this for Microsoft-hosted agents
   poolName: '' # Use this for self-hosted agents
 
-  ######################################
-  # Common folders and file paths
-  ######################################
+  #######################################
+  ##   Common folders and file paths   ##
+  #######################################
 
   moduleTestFilePath: 'utilities/pipelines/staticValidation/module.tests.ps1'
 
-  ######################################
-  # Validation deployment settings
-  ######################################
+  #############################
+  ##   Validation settings   ##
+  #############################
+
+  # Static validation #
+  # ----------------- #
+
+  allowPreviewVersionsInAPITests: true # When enabled, preview versions do not fail the API version tests in the `module.tests.ps1` file
+
+  # Deployment validation #
+  # --------------------- #
 
   location: 'West Europe' # The default location to test deploy resources to
 
-  ######################################
-  # Publish: Shared settings
-  ######################################
+  #############################
+  ##   Publishing settings   ##
+  #############################
+
+  # Shared settings #
+  # --------------- #
 
   publishLatest: true # [Only for Template-Specs & Bicep Registry] Publish an absolute latest version. Note: This version may include breaking changes and is not recommended for production environments
 
-  ######################################
-  # Publish: Template-Spec settings
-  ######################################
+  # Template-Spec settings #
+  # ---------------------- #
 
   templateSpecsDoPublish: true # Set to true, if you would like to publish module templates as template specs
   templateSpecsRGName: 'artifacts-rg' # The name of the resource group to publish to. If the resource group does not exist, it will be created.
   templateSpecsRGLocation: 'West Europe' # The location of the resource group to publish to
   templateSpecsDescription: components # The description to add to template specs published by this platform
 
-  ######################################
-  # Publish: Private Bicep Registry settings
-  ######################################
+  # ------------------------------- #
+  # Private Bicep Registry settings #
+  # ------------------------------- #
 
   bicepRegistryDoPublish: true # Set to true, if you would like to publish module templates to a bicep registry
   bicepRegistryName: adpsxxazacrx001 # The name of the bicep registry (ACR) to publish to. If it does not exist, it will be created.
@@ -70,33 +76,37 @@ variables:
   ################################################## Azure DevOps Only ######################################################
   ###########################################################################################################################
 
-  ######################################
-  # Connection settings
-  ######################################
+  #############################
+  ##   Connection settings   ##
+  #############################
 
   serviceConnection: 'CARML-CSU-Tenant-Connection'
 
-  ######################################
-  # Source
-  ######################################
+  ################
+  ##   Source   ##
+  ################
 
   vstsOrganizationURI: '$(System.CollectionUri)' # The URI of the TFS collection or Azure DevOps organization. For example: https://dev.azure.com/fabrikam/.
   vstsProject: '$(System.TeamProject)'
   modulesRepository: ResourceModules # The repository hosting the deployment code (i.e. 'Components'). MUST be provided as a variable with every pipeline
   pipelineFunctionsPath: 'utilities/pipelines'
 
-  ######################################
-  # Publish: Universal packages settings
-  ######################################
+
+  #############################
+  ##   Publishing settings   ##
+  #############################
+
+  # Universal packages settings #
+  # --------------------------- #
 
   artifactsFeedDoPublish: true # Set to true, if you would like to publish modules as Universal Packages (in Azure DevOps Artifacts)
   vstsFeedName: 'ResourceModules' # The name of the Azure DevOps universal packages feed to publish to
   vstsFeedProject: '$(System.TeamProject)' # The project that hosts the feed
   vstsFeedToken: $(System.AccessToken) # The token used to publish universal packages into the feed above
 
-  ######################################
-  # Azure PowerShell Version
-  ######################################
+  #################################
+  #   Azure PowerShell Version   ##
+  #################################
 
   # Should be set to 'latestVersion' unless there is an issue with the Az PowerShell modules.
   # If a specific version needs to be set azurePowerShellVersion should be changed to 'OtherVersion'.

utilities/pipelines/sharedScripts/Add-YamlListToFile.ps1

@@ -63,12 +63,14 @@ function Add-YamlListToFile {
 
         # Process List (Hashtable)
         $KeyValuePair = $InputFileContent | ConvertFrom-Yaml | Select-Object -ExpandProperty $ListName
-        Write-Verbose ('Found [{0}] Key-Value pairs in List [{1}]' -f $KeyValuePair.Count, $ListName) -Verbose
+        Write-Verbose ('Found [{0}] Key-Value pairs' -f $KeyValuePair.Count) -Verbose
+
         if (-not $KeyValuePair) {
             throw "No key-value pairs found in List: $ListName"
         }
         # Process key value pairs in the list
-        foreach ($Key in $KeyValuePair.Keys.split(' ')) {
+        foreach ($Key in ($KeyValuePair.Keys.split(' ') | Sort-Object)) {
+            Write-Verbose ('Setting environment variable [{0}] with value [{1}]' -f $Key, $KeyValuePair[$Key]) -Verbose
             Write-Output "$Key=$($KeyValuePair[$Key])" | Out-File -FilePath $OutputFilePath -Encoding utf-8 -Append
         }
     }