Rollback Az.Resources #2970 (#2974)

docs/CHANGELOG-v1.md

@@ -33,6 +33,9 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
   - Cosmos DB:
     - Verify that Cosmos DB accounts have continuous backup configured by @BenjaminEngeset.
       [#2954](https://github.com/Azure/PSRule.Rules.Azure/issues/2954)
+- Bug fixes:
+  - Rollback Az.Resources to v6.7.0.
+    [#2970](https://github.com/Azure/PSRule.Rules.Azure/issues/2970)
 
 ## v1.38.0-B0068 (pre-release)
 

docs/concepts/policy-as-rules.md

@@ -52,13 +52,40 @@ Key points:
 - This command has no required parameters, and by default will export all assignments from you current Azure subscription.
   You can change the current Azure subscription by using `Set-AzContext`.
 
+!!! Bug
+    Currently a known incompatibility exists with 7.x of `Az.Resources` which introduced a breaking change.
+    Please use `Az.Resources` >= v6.7.0 and < v7.0.0.
+    For more information see [Issues with Az.Resources](../troubleshooting.md#issues-with-azresources)
+
+For example:
+
+```powershell title="PowerShell"
+# Install and import required modules.
+Install-Module Az.Resources -RequiredVersion '6.7.0' -Force -Scope CurrentUser
+Import-Module Az.Resources -RequiredVersion '6.7.0'
+Import-Module PSRule.Rules.Azure
+
+# Connect to Azure
+Connect-AzAccount
+Set-AzContext -Subscription '<subscriptionId>'
+
+# Export assignments
+Export-AzPolicyAssignmentData
+```
+
 ### Convert assignments to rules
 
 Run `Export-AzPolicyAssignmentRuleData` to convert assignments to rules.
 To run this command an `-AssignmentFile` parameter with the path to the assignment JSON file generated in the previous step.
 
 After the command completes a new file `*.Rule.jsonc` should be generated containing generated rules.
 
+For example:
+
+```powershell title="PowerShell"
+Export-AzPolicyAssignmentRuleData -AssignmentFile '.\<subscriptionId>.assignment.json'
+```
+
 ## Customizing the generated rules
 
 PSRule for Azure allows you to:

docs/install.md

@@ -158,7 +158,7 @@ PowerShell modules:
     In most cases these modules will be pre-installed on the CI worker.
     For private CI workers, consider pre-installing these modules in a previous step.
 
-  [3]: troubleshooting.md#an-earlier-version-of-azaccounts-is-imported
+  [3]: troubleshooting.md#issues-with-azresources
 
 ### Installing PowerShell
 

docs/troubleshooting.md

@@ -169,50 +169,51 @@ This doesn't affect the workings of the parameter file or deployment.
 The reason for the warning is that the `metadata` property has not been added to the parameter file JSON schema.
 However, the top level `metadata` property is ignored by Azure Resource Manager when deploying a template.
 
-## A warning is reported for Az.Resources
+## Issues with Az.Resources
 
-When running PSRule or importing `PSRule.Rules.Azure` on the command-line you see a message similar to the following:
+The PowerShell module `Az.Resources` and `Az.Accounts` is currently used when exporting data from Azure.
+These modules are use when:
+
+- Exporting resources for in-flight analysis.
+- Exporting policy assignments for policy as rules.
+
+These modules are not required if you only want to execute rules.
+
+### Suppression of Az.Resources warning
+
+If you only intend to execute rules you can suppress the following warning message.
 
 !!! Message
 
     To use PSRule for Azure export cmdlets please install Az.Resources.
 
-This warning flags that when running `Export-*` cmdlets for PSRule for Azure, the `Az.Resources` module is required.
-If you intend to call these cmdlets, first install the `Az.Resources` module.
-Otherwise this warning message can be ignored.
-
+This message can be ignored if you are not exporting data from Azure.
 To suppress the warning configure the `PSRULE_AZURE_RESOURCE_MODULE_NOWARN` environment variable to `true`.
 For more details see [Configuring exports](setup/configuring-exports.md#psrule_azure_resource_module_nowarn).
 
-## An earlier version of Az.Accounts is imported
+### Installing Az.Resources
+
+If you plan on exporting data from Azure, you must install the `Az.Resources` module.
 
-When running PSRule for Azure in Azure DevOps within the `AzurePowerShell@5` task,
-you may see the following error.
+Some versions of `Az.Resources` are known to be incompatible with PSRule for Azure.
+As a result, we recommend installing and importing v6.7.0 to address these issues.
+A known incompatibility currently exists with v7.1.0 ([#2970](https://github.com/Azure/PSRule.Rules.Azure/issues/2970)).
+By default, PowerShell will attempt to install or use a newer version already installed which may return an error.
 
 !!! Message
 
-    This module requires Az.Accounts version 2.8.0. An earlier version of
-    Az.Accounts is imported in the current PowerShell session. Please open a new
-    session before importing this module. This error could indicate that multiple
-    incompatible versions of the Azure PowerShell cmdlets are installed on your
-    system. Please see https://aka.ms/azps-version-error for troubleshooting
-    information.
+    ExpandPolicyAssignment: The property 'Properties' cannot be found on this object. Verify that the property exists.
 
-This error is raised by a chained dependency failure importing a newer version of `Az.Accounts`.
-To avoid this issue attempt to install the exact versions of `Az.Resources`.
-In the `AzurePowerShell@5` task before installing PSRule.
+To install a specific version use:
 
 ```powershell title="PowerShell"
-Install-Module Az.Resources -RequiredVersion '7.1.0' -Force -Scope CurrentUser
+Install-Module Az.Resources -RequiredVersion '6.7.0' -Force -Scope CurrentUser
 ```
 
-From PSRule for Azure v1.16.0, `Az.Accounts` and `Az.Resources` are no longer installed as dependencies.
-When using export commands from PSRule, you may need to install these modules.
-
-To install these modules, use the following PowerShell command:
+To import a specific version prior to using PSRule:
 
 ```powershell title="PowerShell"
-Install-Module Az.Resources -Force -Scope CurrentUser
+Import-Module Az.Resources -RequiredVersion '6.7.0'
 ```
 
 ## Could not load file or assembly YamlDotNet

modules.json

@@ -6,7 +6,7 @@
   },
   "devDependencies": {
     "Az.Resources": {
-      "version": "7.1.0"
+      "version": "6.7.0"
     },
     "Pester": {
       "version": "5.6.0"

src/PSRule.Rules.Azure/PSRule.Rules.Azure.psm1

@@ -5,9 +5,9 @@
 # PSRule.Rules.Azure module
 #
 
-$m = Import-Module 'Az.Resources' -MinimumVersion 7.1.0 -Global -ErrorAction SilentlyContinue -PassThru;
+$m = Import-Module 'Az.Resources' -MinimumVersion 6.7.0 -MaximumVersion 6.99.99 -Global -ErrorAction SilentlyContinue -PassThru;
 if ($Null -eq $m -and $Env:PSRULE_AZURE_RESOURCE_MODULE_NOWARN -ne 'true') {
-    Write-Warning -Message "To use PSRule for Azure export cmdlets please install Az.Resources >= 7.1.0. To suppress this warning set the environment variable 'PSRULE_AZURE_RESOURCE_MODULE_NOWARN' to 'true'.";
+    Write-Warning -Message "To use PSRule for Azure export cmdlets please install Az.Resources >= 6.7.0 and < 7.0.0. To suppress this warning set the environment variable 'PSRULE_AZURE_RESOURCE_MODULE_NOWARN' to 'true'.";
 }
 
 Set-StrictMode -Version latest;