Moved bicepparam file support to stable Azure#2682 (Azure#2692)

Author: BernieWhite

docs/CHANGELOG-v1.md

@@ -55,6 +55,10 @@ What's changed since v1.33.2:
       - Added a selector for classic profiles `Azure.FrontDoor.IsClassic`.
       - Updated rule set to `2024_03`.
 - General improvements:
+  - Moved `.bicepparam` file support to stable by @BernieWhite.
+    [#2682](https://github.com/Azure/PSRule.Rules.Azure/issues/2682)
+    - Bicep param files are now automatically expanded when found.
+    - To disable expansion, set the configuration option `AZURE_BICEP_PARAMS_FILE_EXPANSION` to `false`.
   - Documentation and metadata improvements by @BernieWhite.
     [#1772](https://github.com/Azure/PSRule.Rules.Azure/issues/1772)
     [#2570](https://github.com/Azure/PSRule.Rules.Azure/issues/2570)

docs/hooks/shortcodes.py

@@ -110,6 +110,9 @@ def _badge_for_configuration(text: str, page: Page, files: Files) -> str:
     if config_type == "rule":
         path = f"../../setup/configuring-rules.md#{config_value.lower()}"
 
+    if config_type == "expand":
+        path = f"../../setup/configuring-expansion.md#{config_value.lower()}"
+
     icon = "octicons-gear-24"
     href = path
     text = config_value

docs/quickstarts/test-bicep-with-github.md

@@ -114,33 +114,40 @@ Options in this file will automatically be detected by other PSRule commands and
 2. In the root of your repository, create a new file called `ps-rule.yaml`.
 3. Update the file with the following contents and save.
 
-    ```yaml title="ps-rule.yaml"
-    #
-    # PSRule configuration
-    #
-
-    # Please see the documentation for all configuration options:
-    # https://aka.ms/ps-rule-azure/options
-
-    # Require a minimum version of PSRule for Azure.
-    requires:
-      PSRule.Rules.Azure: '>=1.29.0'
-
-    # Automatically use rules for Azure.
-    include:
-      module:
-      - PSRule.Rules.Azure
-
-    # Ignore all files except .bicepparam files.
-    input:
-      pathIgnore:
-      - '**'
-      - '!**/*.bicepparam'
-
-    # Enable expansion of Azure .bicepparam files.
-    configuration:
-      AZURE_BICEP_PARAMS_FILE_EXPANSION: true
-    ```
+```yaml title="ps-rule.yaml"
+#
+# PSRule configuration
+#
+
+# Please see the documentation for all configuration options:
+# https://aka.ms/ps-rule-azure/options
+
+# Require a minimum version of PSRule for Azure.
+requires:
+  PSRule.Rules.Azure: '>=1.34.0' # (1)
+
+# Automatically use rules for Azure.
+include:
+  module:
+  - PSRule.Rules.Azure # (2)
+
+# Ignore all files except .bicepparam files.
+input:
+  pathIgnore:
+  - '**' # (3)
+  - '!**/*.bicepparam' # (4)
+```
+
+<div class="result" markdown>
+1.  Set the minimum required version of PSRule for Azure to use.
+    This does not install the required version, but will fail if the version is not available.
+    Across a team and CI/CD pipeline, this can help ensure a consistent version of PSRule is used.
+2.  Automatically use the rules in PSRule for Azure for each run.
+3.  Ignore all files by default.
+    PSRule will not try to analyze ignored files.
+4.  Add an exception for `.bicepparam` files.
+
+</div>
 
   [7]: https://code.visualstudio.com/docs/sourcecontrol/overview#_branches-and-tags
 
@@ -183,7 +190,7 @@ jobs:
     steps:
 
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Run PSRule analysis
       uses: microsoft/[email protected] # (1)
@@ -193,11 +200,13 @@ jobs:
 
 <div class="result" markdown>
 1.  Reference the PSRule action.
-    You can find the latest version of the action on the [GitHub Marketplace](https://github.com/marketplace/actions/psrule).
+    You can find the latest version of the action on the [GitHub Marketplace][14].
 2.  Automatically download and use PSRule for Azure during analysis.
 
 </div>
 
+  [14]: https://github.com/marketplace/actions/psrule
+
 ## Commit and push changes
 
 1. Commit and push the changes to your repository.

docs/setup/configuring-expansion.md

@@ -82,10 +82,10 @@ configuration:
 
 ### Bicep parameter expansion
 
-<!-- module:version v1.27.0 -->
+<!-- module:version v1.34.0 -->
 
 This configuration option determines if Azure Bicep parameter files (`.bicepparam`) are expanded.
-Currently while this is an experimental feature this is not enabled by default.
+By default, Bicep parameter files will be automatically expanded.
 
 Bicep files are expanded when PSRule cmdlets with the `-Format File` parameter are used.
 
@@ -101,15 +101,15 @@ Default:
 ```yaml title='ps-rule.yaml'
 # YAML: The default AZURE_BICEP_PARAMS_FILE_EXPANSION configuration option
 configuration:
-  AZURE_BICEP_PARAMS_FILE_EXPANSION: false
+  AZURE_BICEP_PARAMS_FILE_EXPANSION: true
 ```
 
 Example:
 
 ```yaml title='ps-rule.yaml'
 # YAML: Set the AZURE_BICEP_PARAMS_FILE_EXPANSION configuration option to enable expansion
 configuration:
-  AZURE_BICEP_PARAMS_FILE_EXPANSION: true
+  AZURE_BICEP_PARAMS_FILE_EXPANSION: false
 ```
 
 ### Bicep compilation timeout

docs/using-bicep.md

@@ -193,51 +193,32 @@ This option will discover Bicep files from parameter metadata.
 
 ### Using Bicep parameter files
 
-:octicons-beaker-24:{ .experimental } Experimental · :octicons-milestone-24: v1.27.0
+<!-- module:version v1.34.0 -->
 
 You can use `.bicepparam` files to reference your Bicep modules as a method for providing parameters.
 Using the Bicep parameter file format, allows you to get many of the benefits of the Bicep language.
 
 For example:
 
 ```bicepparam
-using 'template.bicep'
+using 'main.bicep'
 
 param storageAccountName = 'bicepstorage001'
 param tags = {
   env: 'test'
 }
 ```
 
-Presently, to use this feature you must:
-
-1. Enable the experimental feature in `bicepconfig.json`.
-2. Enable expansion of Bicep parameter files in `ps-rule.yaml`.
-
-For example:
-
-```json title="bicepconfig.json"
-{
-  "experimentalFeaturesEnabled": {
-    "paramsFiles": true
-  }
-}
-```
-
-```yaml title="ps-rule.yaml"
-configuration:
-  AZURE_BICEP_PARAMS_FILE_EXPANSION: true
-```
-
-!!! Experimental "Experimental - [Learn more][13]"
-    Bicep parameter files are a work in progress.
-    This feature will be transitioned to stable after the Bicep CLI support is finalized.
-
 !!! Learn
     To learn more about Bicep parameter files see [Create parameters files for Bicep deployment][16].
 
-  [13]: versioning.md#experimental-features
+!!! Note
+    To use Bicep parameter files you must use a minimum of Bicep CLI version **0.18.4**.
+    You can configure PSRule to check for the minimum Bicep version.
+    See [configuring minimum version][10] for information on how to enable this check.
+
   [16]: https://learn.microsoft.com/azure/azure-resource-manager/bicep/parameter-files?tabs=Bicep
+  [10]: setup/setup-bicep.md#configuring-minimum-version
 
 ## Restoring modules from a private registry
 
@@ -266,7 +247,6 @@ To configure your registry see [Make your container registry content publicly av
 
   [15]: https://learn.microsoft.com/azure/azure-resource-manager/bicep/private-module-registry
   [14]: https://learn.microsoft.com/azure/container-registry/anonymous-pull-access
-  [10]: setup/setup-bicep.md#configuring-minimum-version
 
 ### Configure `bicepconfig.json`
 
@@ -296,11 +276,11 @@ Use the following credential type based on your environment as the first value o
     The `bicepconfig.json` configures the Bicep CLI.
     You should commit this file into a repository along with your Bicep code.
 
-  [9]: https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview
+  [9]: https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview
 
 ### Granting access to a private registry
 
-To access a private registry use an Azure AD identity which has been granted permissions to pull Bicep modules.
+To access a private registry use an Entra ID identity which has been granted permissions to pull Bicep modules.
 When using `Environment` credential type, see [create a service principal that can access resources][11] to create the identity.
 If you are using the `ManagedIdentity` credential type, an identity is created for when you [configure the managed identity][9].
 

src/PSRule.Rules.Azure/rules/Config.Rule.yaml

@@ -33,7 +33,7 @@ spec:
     AZURE_BICEP_FILE_EXPANSION: false
 
     # Enable expansion from .bicepparam files.
-    AZURE_BICEP_PARAMS_FILE_EXPANSION: false
+    AZURE_BICEP_PARAMS_FILE_EXPANSION: true
 
     # Check for a minimum version of the Bicep CLI.
     AZURE_BICEP_MINIMUM_VERSION: '0.4.451'

tests/Bicep/Bicep.Tests.ps1

@@ -130,10 +130,7 @@ Describe 'Bicep' -Tag 'Bicep' {
             $sourceFile = Join-Path -Path $here -ChildPath 'template.bicepparam';
 
             # Expand source files
-            $option = @{
-                'Configuration.AZURE_BICEP_PARAMS_FILE_EXPANSION' = $True
-            }
-            $result = @(Invoke-PSRule @invokeParams -InputPath $sourceFile -Format File -Option $option);
+            $result = @(Invoke-PSRule @invokeParams -InputPath $sourceFile -Format File);
             $result.Length | Should -Be 1;
             $resource = $result | Where-Object { $_.TargetType -eq 'Microsoft.Storage/storageAccounts' };
             $resource | Should -Not -BeNullOrEmpty;