Skip to content

Latest commit

 

History

History
160 lines (116 loc) · 6.96 KB

troubleshooting.md

File metadata and controls

160 lines (116 loc) · 6.96 KB
Raw
author discussion
BernieWhite
false

Troubleshooting

This article provides troubleshooting instructions for common errors.

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

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.

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.

Install-Module Az.Resources -RequiredVersion '5.6.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:

Install-Module Az.Resources -Force -Scope CurrentUser

Bicep compilation timeout

When expanding Bicep source files you may get an error similar to the following:

!!! Error

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.

This error is raised when Bicep takes longer then the timeout to build a source file. The default timeout is 5 seconds.

You can take steps to reduce your code complexity and reduce the time a build takes by:

  • Removing unnecessary nested module calls.
  • Cache bicep modules restored from a registry in continuous integration (CI) pipelines.

To increase the timeout value, set the AZURE_BICEP_FILE_EXPANSION_TIMEOUT configuration option. See Bicep compilation timeout for details on how to configure this option.

No rules or no Azure resources are found

There is a few common causes of this issue including:

  • Check input format — PSRule for Azure must discover files to expand them.
    • When running PSRule for Azure using GitHub Actions or the Azure Pipelines extension:
      • Your pipeline must be set to inputType: repository, which is the default value.
      • PSRule for Azure will not work with inputType set to inputPath.
      • You may have set this parameter because you wanted to use the inputPath parameter. Setting the inputType is not a requirement for using the inputPath parameter. The inputPath parameter can be used independently.
    • When running PSRule for Azure from PowerShell:
      • Your command-line must use the -Format File parameter.
      • Your command-line must use the -InputPath or -f parameter followed by a file or directory path.
      • For example: Assert-PSRule -Module PSRule.Rules.Azure -Format File -f 'modules/'.
  • Check expansion is enabled — Expansion must be enabled to analyze Azure Infrastructure as Code. See using templates and using Bicep source for details on how to enable expansion.
  • Check parameter files are linked — Parameter files must be linked to ARM templates or Bicep source files. See using templates for details on how to link using metadata or naming convention.

!!! Note If your pipeline is still not finding any Azure resources, please join or start a discussion.

Custom rules are not running

There is a few common causes of this issue including:

  • Check rule path — By default, PSRule will look for rules in the .ps-rule/ directory. This directory is the root for your repository or the current working path by default. On case-sensitive file systems such as Linux, this directory name is case-sensitive. See Storing and naming rules for more information.
  • Check file name suffix — PSRule only looks for files with the .Rule.ps1, .Rule.yaml, or .Rule.jsonc suffix. On case-sensitive file systems such as Linux, this file siffix is case-sensitive. See Storing and naming rules for more information.
  • Check binding configuration — PSRule uses binding to work out which property to use for a resource type. To be able to use the -Type parameter or type properties in rules definitions, binding must be set. This is automatically configured for PSRule for Azure, however must be set in ps-rule.yaml for custom rules. See binding type for more information.
  • Check modules — PSRule for Azure is responsible for expanding Azure resources from Infrastructure as Code. Expansion occurs automatically in memory when enabled. For this to work, the module PSRule.Rules.Azure must be run with any custom rules. See using templates and using Bicep source for details on how to enable expansion.

!!! Tip You may be able to use git mv to change the case of a file if it is commited to the repository inorrectly.

Parameter file warns of metadata property

You may find while editing a .json parameter file the root metadata property is flagged with a warning.

!!! Warning

The property 'metadata' is not allowed.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "metadata": {
        "template": "./storage.template.json"
    },
    "parameters": {
    }
}

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.

Could not load file or assembly YamlDotNet

PSRule >=1.3.0 uses an updated version of the YamlDotNet library. The PSRule for Azure <1.3.1 uses an older version of this library which may conflict.

To avoid this issue:

  • Update to the latest version and use PSRule for Azure >=1.3.1 with PSRule >=1.3.0.
  • Alternatively, when using PSRule for Azure <1.3.1 use PSRule =1.2.0.

To install the latest module version of PSRule use the following commands:

Install-Module -Name PSRule.Rules.Azure -MinimumVersion 1.3.1 -Scope CurrentUser -Force;

For the PSRule GitHub Action, use >=1.4.0.

- name: Run PSRule analysis
  uses: Microsoft/[email protected]