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

2024-02-27 16:13:24 +10:00 · 2024-02-27 16:13:24 +10:00 · 98071228a1
--- a/docs/CHANGELOG-v1.md
+++ b/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)
--- a/docs/hooks/shortcodes.py
+++ b/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
--- a/docs/quickstarts/test-bicep-with-github.md
+++ b/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
-    #
+```yaml title="ps-rule.yaml"
+#
+# PSRule configuration
+#

-    # Please see the documentation for all configuration options:
-    # https://aka.ms/ps-rule-azure/options
+# 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'
+# 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
+# Automatically use rules for Azure.
+include:
+  module:
+  - PSRule.Rules.Azure # (2)

-    # Ignore all files except .bicepparam files.
-    input:
-      pathIgnore:
-      - '**'
-      - '!**/*.bicepparam'
+# Ignore all files except .bicepparam files.
+input:
+  pathIgnore:
+  - '**' # (3)
+  - '!**/*.bicepparam' # (4)
+```

-    # Enable expansion of Azure .bicepparam files.
-    configuration:
-      AZURE_BICEP_PARAMS_FILE_EXPANSION: true
-    ```
+<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/ps-rule@v2.9.0 # (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.
--- a/docs/setup/configuring-expansion.md
+++ b/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,7 +101,7 @@ 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:
@ -109,7 +109,7 @@ 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
--- a/docs/using-bicep.md
+++ b/docs/using-bicep.md
@ -193,7 +193,7 @@ 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.
@ -201,7 +201,7 @@ Using the Bicep parameter file format, allows you to get many of the benefits of
 For example:

 ```bicepparam
-using 'template.bicep'
+using 'main.bicep'

 param storageAccountName = 'bicepstorage001'
 param tags = {
@ -209,35 +209,16 @@ param tags = {
 }
 ```

-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].

--- a/src/PSRule.Rules.Azure/rules/Config.Rule.yaml
+++ b/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'
--- a/tests/Bicep/Bicep.Tests.ps1
+++ b/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;