From 149c0aa78f34c49dfd4cd1d997bb6283866acb00 Mon Sep 17 00:00:00 2001 From: Bernie White Date: Tue, 2 Jul 2024 01:02:34 +1000 Subject: [PATCH] Add suppression for import warning (#2962) --- .vscode/settings.json | 1 + docs/CHANGELOG-v1.md | 4 + docs/assets/stylesheets/extra.css | 20 +++ docs/faq.md | 2 + docs/setup/configuring-expansion.md | 4 +- docs/setup/configuring-exports.md | 135 ++++++++++++++++++ docs/setup/configuring-rules.md | 72 +--------- .../{configuring-options.md => index.md} | 12 +- docs/setup/setup-bicep.md | 42 ++++-- docs/troubleshooting.md | 33 +++-- mkdocs.yml | 10 +- .../PSRule.Rules.Azure.psm1 | 6 +- 12 files changed, 242 insertions(+), 99 deletions(-) create mode 100644 docs/setup/configuring-exports.md rename docs/setup/{configuring-options.md => index.md} (92%) diff --git a/.vscode/settings.json b/.vscode/settings.json index 0d73bcee6eb..214e1c8bc1f 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -78,6 +78,7 @@ "failover", "GREATEROREQUAL", "GREATEROREQUALS", + "hackathons", "Hashtable", "inheritdoc", "konnectivity", diff --git a/docs/CHANGELOG-v1.md b/docs/CHANGELOG-v1.md index 3b38d328f97..daa10cf2f97 100644 --- a/docs/CHANGELOG-v1.md +++ b/docs/CHANGELOG-v1.md @@ -44,6 +44,10 @@ What's changed since pre-release v1.38.0-B0034: [#2922](https://github.com/Azure/PSRule.Rules.Azure/issues/2922) - Fixed group by subscription casing when exporting in-flight resources by @BernieWhite. [#2957](https://github.com/Azure/PSRule.Rules.Azure/issues/2957) + - Fixed install Az.Resources warning by @BernieWhite. + [#2887](https://github.com/Azure/PSRule.Rules.Azure/issues/2887) + - Added new configuration option set by environment variable to suppress the warning. + - Set `PSRULE_AZURE_RESOURCE_MODULE_NOWARN` to `true` to suppress the warning. ## v1.38.0-B0034 (pre-release) diff --git a/docs/assets/stylesheets/extra.css b/docs/assets/stylesheets/extra.css index ce60b3675b1..669c51bff75 100644 --- a/docs/assets/stylesheets/extra.css +++ b/docs/assets/stylesheets/extra.css @@ -30,6 +30,7 @@ :root { --md-admonition-icon--experimental: url('data:image/svg+xml;charset=utf-8,'); --md-admonition-icon--learn: url('data:image/svg+xml;charset=utf-8,'); + --md-admonition-icon--message: url('data:image/svg+xml;charset=utf-8,'); } /* experimental */ @@ -70,6 +71,25 @@ mask-image: var(--md-admonition-icon--learn); } +/* message */ +.md-typeset .admonition.message, +.md-typeset details.message { + border-color: rgb(0, 184, 212) +} + +.md-typeset .message>.admonition-title, +.md-typeset .message>summary { + background-color: rgba(0, 184, 212, .1); + border-color: rgb(0, 184, 212); +} + +.md-typeset .message>.admonition-title::before, +.md-typeset .message>summary::before { + background-color: rgb(0, 184, 212); + -webkit-mask-image: var(--md-admonition-icon--message); + mask-image: var(--md-admonition-icon--message); +} + /* badges */ .badge { diff --git a/docs/faq.md b/docs/faq.md index f93025c8746..f39768ab268 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -16,10 +16,12 @@ For general FAQ see [PSRule - Frequently Asked Questions (FAQ)][ps-rule-faq], in !!! Note If you have a question that is not answered here, please [join or start a discussion][discussion]. + For common issues and workarounds, please see [troubleshooting][19]. [discussion]: https://github.com/Azure/PSRule.Rules.Azure/discussions [13]: https://microsoft.github.io/PSRule/v2/faq/#how-do-exclude-or-ignore-files-from-being-processed [14]: https://microsoft.github.io/PSRule/v2/faq/#how-do-i-disable-or-suppress-the-not-processed-warning + [19]: troubleshooting.md ## What is a rule? diff --git a/docs/setup/configuring-expansion.md b/docs/setup/configuring-expansion.md index d2f71ecc360..c8c5cc359b8 100644 --- a/docs/setup/configuring-expansion.md +++ b/docs/setup/configuring-expansion.md @@ -7,14 +7,14 @@ author: BernieWhite PSRule for Azure can automatically resolve Azure resource context at runtime from infrastructure code. This feature can be enabled by using the following configuration options. -## Configuration - !!! Tip Each of these configuration options are set within the `ps-rule.yaml` file. To learn how to set configuration options see [Configuring options][1]. [1]: configuring-options.md +## Available options + ### Parameter file expansion diff --git a/docs/setup/configuring-exports.md b/docs/setup/configuring-exports.md new file mode 100644 index 00000000000..9e44afd073b --- /dev/null +++ b/docs/setup/configuring-exports.md @@ -0,0 +1,135 @@ +--- +author: BernieWhite +--- + +# Configuring exports + +For in-flight analysis or when using policy as rules data may be exported from one or more subscriptions. +To configure the export process see the following configuration options. + +To use a configuration option, you **must** use the minimum version specified. +Earlier versions of PSRule for Azure will ignore the configuration option. + +## General + +### PSRULE_AZURE_RESOURCE_MODULE_NOWARN + + + +This configuration option suppresses a warning when the minimum version of `Az.Resources` module is not installed. +Unlike most options, this option can only set by environment variable. + +Syntax: + +```bash +PSRULE_AZURE_RESOURCE_MODULE_NOWARN: boolean +``` + +Default: + +```bash +PSRULE_AZURE_RESOURCE_MODULE_NOWARN: false +``` + +Example: + +=== "GitHub Actions" + + ```yaml + env: + PSRULE_AZURE_RESOURCE_MODULE_NOWARN: true + ``` + +=== "Azure Pipelines" + + ```yaml + variables: + - name: PSRULE_AZURE_RESOURCE_MODULE_NOWARN + value: true + ``` + +=== "PowerShell" + + ```powershell + $Env:PSRULE_AZURE_RESOURCE_MODULE_NOWARN = 'true' + ``` + +=== "Bash" + + ```bash + export PSRULE_AZURE_RESOURCE_MODULE_NOWARN=true + ``` + +## Policy as rules + +The following configuration options apply when using policy as rules. + +### AZURE_POLICY_IGNORE_LIST + + + +This configuration option configures a custom list policy definitions to ignore when exporting policy to rules. +In addition to the custom list, a built-in list of policies are ignored. +The built-in list can be found [here](https://github.com/Azure/PSRule.Rules.Azure/blob/main/data/policy-ignore.json). + +Configure this option to ignore policy definitions that: + +- Already have a rule defined. +- Are not relevant to testing Infrastructure as Code. + +Syntax: + +```yaml title="ps-rule.yaml" +configuration: + AZURE_POLICY_IGNORE_LIST: array +``` + +Default: + +```yaml title="ps-rule.yaml" +# YAML: The default AZURE_POLICY_IGNORE_LIST configuration option +configuration: + AZURE_POLICY_IGNORE_LIST: [] +``` + +Example: + +```yaml title="ps-rule.yaml" +# YAML: Add custom policy definitions to ignore +configuration: + AZURE_POLICY_IGNORE_LIST: + - '/providers/Microsoft.Authorization/policyDefinitions/1f314764-cb73-4fc9-b863-8eca98ac36e9' + - '/providers/Microsoft.Authorization/policyDefinitions/b54ed75b-3e1a-44ac-a333-05ba39b99ff0' +``` + +### AZURE_POLICY_RULE_PREFIX + + + +This configuration option sets the prefix for names of exported rules. +Configure this option to change the prefix, which defaults to `Azure`. + +This configuration option will be ignored when `-Prefix` is used with `Export-AzPolicyAssignmentRuleData`. + +Syntax: + +```yaml title="ps-rule.yaml" +configuration: + AZURE_POLICY_RULE_PREFIX: string +``` + +Default: + +```yaml title="ps-rule.yaml" +# YAML: The default AZURE_POLICY_RULE_PREFIX configuration option +configuration: + AZURE_POLICY_RULE_PREFIX: Azure +``` + +Example: + +```yaml title="ps-rule.yaml" +# YAML: Override the prefix of exported policy rules +configuration: + AZURE_POLICY_RULE_PREFIX: AzureCustomPrefix +``` diff --git a/docs/setup/configuring-rules.md b/docs/setup/configuring-rules.md index 8c1118acd83..5bcca978ada 100644 --- a/docs/setup/configuring-rules.md +++ b/docs/setup/configuring-rules.md @@ -14,7 +14,9 @@ Earlier versions of PSRule for Azure will ignore the configuration option. Each of these configuration options are set within the `ps-rule.yaml` file. To learn how to set configuration options see [Configuring options][1]. - [1]: configuring-options.md + [1]: index.md + +## Available options ### AZURE_AKS_CLUSTER_MINIMUM_SYSTEM_NODES @@ -605,74 +607,6 @@ configuration: - 'anotherLinuxOffer' ``` -### AZURE_POLICY_IGNORE_LIST - - - -This configuration option configures a custom list policy definitions to ignore when exporting policy to rules. -In addition to the custom list, a built-in list of policies are ignored. -The built-in list can be found [here](https://github.com/Azure/PSRule.Rules.Azure/blob/main/data/policy-ignore.json). - -Configure this option to ignore policy definitions that: - -- Already have a rule defined. -- Are not relevant to testing Infrastructure as Code. - -Syntax: - -```yaml title="ps-rule.yaml" -configuration: - AZURE_POLICY_IGNORE_LIST: array -``` - -Default: - -```yaml title="ps-rule.yaml" -# YAML: The default AZURE_POLICY_IGNORE_LIST configuration option -configuration: - AZURE_POLICY_IGNORE_LIST: [] -``` - -Example: - -```yaml title="ps-rule.yaml" -# YAML: Add a custom policy definition to ignore - AZURE_POLICY_IGNORE_LIST: - - '/providers/Microsoft.Authorization/policyDefinitions/1f314764-cb73-4fc9-b863-8eca98ac36e9' - - '/providers/Microsoft.Authorization/policyDefinitions/b54ed75b-3e1a-44ac-a333-05ba39b99ff0' -``` - -### AZURE_POLICY_RULE_PREFIX - - - -This configuration option sets the prefix for names of exported rules. -Configure this option to change the prefix, which defaults to `Azure`. - -This configuration option will be ignored when `-Prefix` is used with `Export-AzPolicyAssignmentRuleData`. - -Syntax: - -```yaml title="ps-rule.yaml" -configuration: - AZURE_POLICY_RULE_PREFIX: string -``` - -Default: - -```yaml title="ps-rule.yaml" -# YAML: The default AZURE_POLICY_RULE_PREFIX configuration option -configuration: - AZURE_POLICY_RULE_PREFIX: Azure -``` - -Example: - -```yaml title="ps-rule.yaml" -# YAML: Override the prefix of exported policy rules - AZURE_POLICY_RULE_PREFIX: AzureCustomPrefix -``` - ### AZURE_POLICY_WAIVER_MAX_EXPIRY diff --git a/docs/setup/configuring-options.md b/docs/setup/index.md similarity index 92% rename from docs/setup/configuring-options.md rename to docs/setup/index.md index 736a1daed51..6695e60d76e 100644 --- a/docs/setup/configuring-options.md +++ b/docs/setup/index.md @@ -8,9 +8,17 @@ PSRule for Azure comes with many configuration options. Additionally, the PSRule engine includes several options that apply to all rules. You can visit the [about_PSRule_Options][1] topic to read about general PSRule options. +!!! Abstract + This topic covers the basics of configuration options. + A list of configuration options is available for: + + - [Configuring rule defaults](configuring-rules.md) + - [Configuring expansion](configuring-expansion.md) + - [Configuring exports](configuring-exports.md) + [1]: https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Options/ -## Setting options +## Setting options in YAML Configuration options are set within the `ps-rule.yaml` file. PSRule will automatically find this file within the current working directory. @@ -49,7 +57,7 @@ Use comments to add context. AZURE_BICEP_CHECK_TOOL: true # Optionally, configure the minimum version of the Bicep CLI. - AZURE_BICEP_MINIMUM_VERSION: '0.16.2' + AZURE_BICEP_MINIMUM_VERSION: '0.28.1' # Configure the minimum AKS cluster version. AZURE_AKS_CLUSTER_MINIMUM_VERSION: '1.28.9' diff --git a/docs/setup/setup-bicep.md b/docs/setup/setup-bicep.md index 04eb2beb220..cdb48807975 100644 --- a/docs/setup/setup-bicep.md +++ b/docs/setup/setup-bicep.md @@ -76,27 +76,47 @@ This is explained in [Setup your Bicep development environment][3]. To enable this option, set the `PSRULE_AZURE_BICEP_USE_AZURE_CLI` environment variable to `true`. -!!! Example +Syntax: - ```bash title="Bash" - export PSRULE_AZURE_BICEP_USE_AZURE_CLI=true - ``` +```bash title="Environment variable" +PSRULE_AZURE_BICEP_USE_AZURE_CLI: boolean +``` - ```powershell title="PowerShell" - $Env:PSRULE_AZURE_BICEP_USE_AZURE_CLI = 'true' - ``` +Default: - ```yaml title="GitHub Actions" +```bash title="Environment variable" +PSRULE_AZURE_BICEP_USE_AZURE_CLI: false +``` + +Example: + +=== "GitHub Actions" + + ```yaml env: PSRULE_AZURE_BICEP_USE_AZURE_CLI: true ``` - ```yaml title="Azure Pipelines" +=== "Azure Pipelines" + + ```yaml variables: - name: PSRULE_AZURE_BICEP_USE_AZURE_CLI value: true ``` +=== "PowerShell" + + ```powershell + $Env:PSRULE_AZURE_BICEP_USE_AZURE_CLI = 'true' + ``` + +=== "Bash" + + ```bash + export PSRULE_AZURE_BICEP_USE_AZURE_CLI=true + ``` + [3]: https://learn.microsoft.com/azure/azure-resource-manager/bicep/install#azure-cli ### Additional arguments @@ -158,7 +178,7 @@ configuration: ### Checking Bicep version -:octicons-milestone-24: v1.25.0 + To use Bicep files with PSRule for Azure: @@ -183,7 +203,7 @@ configuration: ### Configuring minimum version -:octicons-milestone-24: v1.25.0 + The Azure Bicep CLI is updated regularly, with new features and bug fixes. You must use a version of the Bicep CLI that supports the features you are using. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 8710cd88bab..6ef0bbde19a 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -11,7 +11,7 @@ This article provides troubleshooting instructions for common errors. When expanding Bicep source files you may get an error including a _BCPnnn_ code similar to the following: -!!! Error +!!! Message Exception calling "GetResources" with "3" argument(s): "Bicep (0.14.46) compilation of '' failed with: Error BCP057: The name "storageAccountName" does not exist in the current context. @@ -68,7 +68,7 @@ If you are using a Bicep feature that is not supported by PSRule for Azure, plea When expanding Bicep source files you may get an error similar to the following: -!!! Error +!!! Message Bicep (0.4.1124) compilation of 'C:\temp\deploy.bicep' failed with: Bicep compilation hasn't completed within the timeout window. This can be caused by errors or warnings. Check the Bicep output by running bicep build and addressing any issues. @@ -149,7 +149,7 @@ There is a few common causes of this issue including: You may find while editing a `.json` parameter file the root `metadata` property is flagged with a warning. -!!! Warning +!!! Message The property 'metadata' is not allowed. @@ -169,12 +169,27 @@ 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 + +When running PSRule or importing `PSRule.Rules.Azure` on the command-line you see a message similar to the following: + +!!! 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. + +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 When running PSRule for Azure in Azure DevOps within the `AzurePowerShell@5` task, you may see the following error. -!!! 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 @@ -187,8 +202,8 @@ This error is raised by a chained dependency failure importing a newer version o To avoid this issue attempt to install the exact versions of `Az.Resources`. In the `AzurePowerShell@5` task before installing PSRule. -```powershell -Install-Module Az.Resources -RequiredVersion '5.6.0' -Force -Scope CurrentUser +```powershell title="PowerShell" +Install-Module Az.Resources -RequiredVersion '7.1.0' -Force -Scope CurrentUser ``` From PSRule for Azure v1.16.0, `Az.Accounts` and `Az.Resources` are no longer installed as dependencies. @@ -196,7 +211,7 @@ When using export commands from PSRule, you may need to install these modules. To install these modules, use the following PowerShell command: -```powershell +```powershell title="PowerShell" Install-Module Az.Resources -Force -Scope CurrentUser ``` @@ -212,13 +227,13 @@ To avoid this issue: To install the latest module version of PSRule use the following commands: -```powershell +```powershell title="PowerShell" Install-Module -Name PSRule.Rules.Azure -MinimumVersion 1.3.1 -Scope CurrentUser -Force; ``` For the PSRule GitHub Action, use **>=1.4.0**. -```yaml +```yaml title="GitHub Actions" - name: Run PSRule analysis uses: microsoft/ps-rule@v2.9.0 ``` diff --git a/mkdocs.yml b/mkdocs.yml index 224f31c757e..01a8454bbc4 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -87,9 +87,11 @@ nav: - Changes and versioning: versioning.md - Support: support.md - Setup: - - Configuring options: setup/configuring-options.md - - Configuring rule defaults: setup/configuring-rules.md - - Configuring expansion: setup/configuring-expansion.md + - Configuring options: + - Index: setup/index.md + - Configuring rule defaults: setup/configuring-rules.md + - Configuring expansion: setup/configuring-expansion.md + - Configuring exports: setup/configuring-exports.md - Setup Bicep: setup/setup-bicep.md - Setup Azure Monitor logs: setup/setup-azure-monitor-logs.md - Integrations: integrations.md @@ -135,6 +137,7 @@ plugins: enable_creation_date: true fallback_to_build_date: true - git-committers: + enabled: !ENV [GITHUB_ACTIONS, false] repository: Azure/PSRule.Rules.Azure branch: main - search @@ -147,6 +150,7 @@ plugins: using-metadata.md: using-templates.md customization/index.md: customization/storing-custom-rules.md en/asb-v3.md: en/mcsb-v1.md + setup/configuring-options.md: setup/index.md hooks: - docs/hooks/shortcodes.py diff --git a/src/PSRule.Rules.Azure/PSRule.Rules.Azure.psm1 b/src/PSRule.Rules.Azure/PSRule.Rules.Azure.psm1 index 2714ba97050..3afa226b339 100644 --- a/src/PSRule.Rules.Azure/PSRule.Rules.Azure.psm1 +++ b/src/PSRule.Rules.Azure/PSRule.Rules.Azure.psm1 @@ -5,9 +5,9 @@ # PSRule.Rules.Azure module # -$m = Import-Module 'Az.Resources' -MinimumVersion 6.5.1 -Global -ErrorAction SilentlyContinue -PassThru; -if ($Null -eq $m) { - Write-Warning -Message "To use PSRule for Azure export cmdlets please install Az.Resources."; +$m = Import-Module 'Az.Resources' -MinimumVersion 7.1.0 -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'."; } Set-StrictMode -Version latest;