diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index ee2190bf8d..91f266b7e1 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -25,6 +25,7 @@ If you're unfamiliar with Infrastructure as Code, or wonder how you can use the - [Register Azure DevOps pipelines script](./UtilitiesRegisterAzureDevOpsPipeline) - [Set Module ReadMe script](./UtilitiesSetModuleReadMe) - [Get formatted RBAC roles script](./UtilitiesGetFormattedRBACRoleList) + - [GitHub readMe module table update script](./UtilitiesSetGitHubReadMeModuleTable.md) - [Pipelines](./Pipelines) - [Design](./PipelinesDesign) - [Parameter File Tokens](./ParameterFileTokens) diff --git a/docs/wiki/UtilitiesConvertToARMTemplate.md b/docs/wiki/UtilitiesConvertToARMTemplate.md index 211f67286d..f04a0d754e 100644 --- a/docs/wiki/UtilitiesConvertToARMTemplate.md +++ b/docs/wiki/UtilitiesConvertToARMTemplate.md @@ -11,7 +11,6 @@ This page documents the conversion utility and how to use it. - [Location](#location) - [How it works](#what-it-does) - [How to use it](#how-to-use-it) - - [Examples](#examples) --- # Location diff --git a/docs/wiki/UtilitiesGetFormattedRBACRoleList.md b/docs/wiki/UtilitiesGetFormattedRBACRoleList.md index d1875117d0..0e0e1d679e 100644 --- a/docs/wiki/UtilitiesGetFormattedRBACRoleList.md +++ b/docs/wiki/UtilitiesGetFormattedRBACRoleList.md @@ -9,7 +9,6 @@ Use this script to format a given raw 'Roles' table from Azure to the format req - [Location](#location) - [How it works](#what-it-does) - [How to use it](#how-to-use-it) - - [Examples](#examples) --- # Location diff --git a/docs/wiki/UtilitiesRegisterAzureDevOpsPipeline.md b/docs/wiki/UtilitiesRegisterAzureDevOpsPipeline.md index 56b3be9820..daf7e74fd2 100644 --- a/docs/wiki/UtilitiesRegisterAzureDevOpsPipeline.md +++ b/docs/wiki/UtilitiesRegisterAzureDevOpsPipeline.md @@ -9,7 +9,6 @@ Use this script to automatically register all specified Azure DevOps pipelines i - [Location](#location) - [How it works](#what-it-does) - [How to use it](#how-to-use-it) - - [Examples](#examples) --- # Location diff --git a/docs/wiki/UtilitiesSetGitHubReadMeModuleTable.md b/docs/wiki/UtilitiesSetGitHubReadMeModuleTable.md new file mode 100644 index 0000000000..341b812d94 --- /dev/null +++ b/docs/wiki/UtilitiesSetGitHubReadMeModuleTable.md @@ -0,0 +1,29 @@ +# GitHub ReadMe Module Table Update Script + +Use this script to update a given ReadMe's module table in its 'Available Resource Modules' section. +In the platform's pipeline `platform.updateReadMe.yml`, this script is invoked each time anything in the `arm` path changes to keep the table in sync. It updates both the root ReadMe (`/readme.md`) and `arm` folder ReadMe (`/arm/readme.md`) with a different set of required columns + +--- + +### _Navigation_ + +- [Location](#location) +- [How it works](#what-it-does) +- [How to use it](#how-to-use-it) + +--- +# Location + +You can find the script under `/utilities/tools/Set-GitHubReadMeModuleTable.ps1` + +# How it works + +1. The script loads the current content of the given readMe file (the one provided via the parameter `FilePath`) +1. It then generates a new table based on an either specified or default set of intended columns (for example a `name` column, and or `status` column) +1. It replaces the original content in section `Available Resource Modules` with the new table +1. If not invoked with a `-WhatIf` the script will eventually overwrite the original file with the new content + +# How to use it + +For details on how to use the function please refer to the script's local documentation. +> **Note:** The script must be loaded before the function can be invoked diff --git a/docs/wiki/UtilitiesSetModuleReadMe.md b/docs/wiki/UtilitiesSetModuleReadMe.md index b0fba849fd..5dd05c041d 100644 --- a/docs/wiki/UtilitiesSetModuleReadMe.md +++ b/docs/wiki/UtilitiesSetModuleReadMe.md @@ -12,7 +12,6 @@ For further information about the parameter usage blocks, please refer to the [s - [How it works](#what-it-does) - [Special case: 'Parameter Usage' section](#special-case-parameter-usage-section) - [How to use it](#how-to-use-it) - - [Examples](#examples) --- # Location diff --git a/docs/wiki/UtilitiesTestModuleLocally.md b/docs/wiki/UtilitiesTestModuleLocally.md new file mode 100644 index 0000000000..7fc200b269 --- /dev/null +++ b/docs/wiki/UtilitiesTestModuleLocally.md @@ -0,0 +1,37 @@ +# Test Module locally Script + +Use this script to test a module locally. You can use it to run only the pester tests, a deployment validation (dryRun) or run a the actual deployment. For the later cases this is important as the script will handles any placeholder tokens in the used parameter file for you. + +--- + +### _Navigation_ + +- [Location](#location) +- [How it works](#what-it-does) +- [How to use it](#how-to-use-it) + +--- +# Location + +You can find the script under `/utilities/tools/Test-ModuleLocally.ps1` + +# How it works + +If the switch for pester tests (`-PesterTest`) was provided the script will +1. Invoke the global module test for the provided template file path and run all tests for it + +If the switch for either the validation test (`-ValidationTest`) or deployment test (`-DeploymentTest`) was provided alongside a hashtable for the token replacement (`-ValidateOrDeployParameters`), the script will +1. Search all parameter files for the given module template +1. Craft a dictionary to replace all tokens in these parameter files with actual values. This dictionary will consist + - of the subscriptionID & managementGroupID of the provided `ValidateOrDeployParameters` object, + - add all key-value pairs of the `-AdditionalTokens` object to it, + - and optionally also add all key-value pairs specified in the `settings.json`'s `parameterFileTokens` object if the `-SkipParameterFileTokens` parameter was not set +1. It replaces all tokens in the parameter files as per the object created in the previous step +1. If the `-ValidationTest` parameter was set, it runs a deployment validation using the `Test-TemplateWithParameterFile` script +1. If the `-DeploymentTest` parameter was set, it runs a deployment using the `New-ModuleDeployment` script (with no retries). By default it uses the standard `parameters.json` parameter file. However, if the switch `-DeployAllModuleParameterFiles` was set, it runs the deployment for all parameter files in the module's `.parameters` folder +1. As a final step it rolls the parameter files back to their original state if either the `-ValidationTest` or `-DeploymentTest` parameters were provided. + +# How to use it + +For details on how to use the function please refer to the script's local documentation. +> **Note:** The script must be loaded before the function can be invoked diff --git a/utilities/tools/Test-ModuleLocally.ps1 b/utilities/tools/Test-ModuleLocally.ps1 index 58482d651f..80f4ab52a0 100644 --- a/utilities/tools/Test-ModuleLocally.ps1 +++ b/utilities/tools/Test-ModuleLocally.ps1 @@ -25,8 +25,8 @@ Optional. A Switch Parameter that triggers the Validation of the Module Only wit .PARAMETER DeployAllModuleParameterFiles Optional. A Boolean Parameter that enables directory based search for parameter files and deploys all of them. If not true, it will only deploy the 'parameters.json' file. Default is false. -.PARAMETER GetParameterFileTokens -Optional. A Boolean Parameter that enables the search for local custom parameter file tokens. Default is true. +.PARAMETER SkipParameterFileTokens +Optional. A Switch Parameter that enables you to skip the search for local custom parameter file tokens. .PARAMETER AdditionalTokens Optional. A Hashtable Parameter that contains custom tokens to be replaced in the paramter files for deployment @@ -102,7 +102,7 @@ function Test-ModuleLocally { [bool]$DeployAllModuleParameterFiles = $false, [parameter(Mandatory = $false)] - [bool]$GetParameterFileTokens = $true, + [switch]$SkipParameterFileTokens, [parameter(Mandatory = $false)] [psobject]$AdditionalTokens @@ -122,7 +122,6 @@ function Test-ModuleLocally { if ($PesterTest) { Write-Verbose "Pester Testing Module: $ModuleName" try { - Import-Module Pester Invoke-Pester -Configuration @{ Run = @{ Container = New-PesterContainer -Path (Join-Path $PSScriptRoot '../..' 'arm/.global/global.module.tests.ps1') -Data @{ @@ -156,7 +155,7 @@ function Test-ModuleLocally { ) | ForEach-Object { [PSCustomObject]$PSItem } # Look for Local Custom Parameter File Tokens (Source Control) - if ($GetParameterFileTokens) { + if (-not $SkipParameterFileTokens) { # Get Settings JSON File $Settings = Get-Content -Path (Join-Path $PSScriptRoot '../..' 'settings.json') | ConvertFrom-Json # Get Custom Parameter File Tokens (Local)