Home

Awesome

PSRule for Azure Monitor

Log PSRule analysis results to Azure Monitor.

Open in vscode.dev

Support

This project uses GitHub Issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates.

If you have any problems with the PSRule engine, please check the project GitHub issues page instead.

Support for this project/ product is limited to the resources listed above.

Getting the module

This project requires the PSRule PowerShell module. For detail on installation and dependencies see install.

You can download and install these modules from the PowerShell Gallery.

ModuleDescriptionDownloads / instructions
PSRule.MonitorLog PSRule analysis results to Azure Monitor.latest / instructions

Getting started

Upload results with PSRule convention

A convention can be used to upload the results of a PSRule analysis to Azure Monitor. To use the convention:

For example:

include:
  module:
  - 'PSRule.Monitor'

convention:
  include:
  - 'Monitor.LogAnalytics.Import

When using the convention a Log Analytics workspace must be specified. This can be done by setting the following environment variables:

For example:

# PowerShell: Setting environment variable
$Env:PSRULE_CONFIGURATION_MONITOR_WORKSPACE_ID = '00000000-0000-0000-0000-000000000000'
$Env:PSRULE_CONFIGURATION_MONITOR_WORKSPACE_KEY = Get-Secret -Name 'WORKSPACE_KEY' -AsPlainText
# GitHub Actions: Setting environment variable with microsoft/ps-rule action
- name: Run PSRule analysis
  uses: microsoft/ps-rule@main
  env:
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_ID: 00000000-0000-0000-0000-000000000000
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_KEY: ${{ secrets.WORKSPACE_KEY }}
# Azure Pipelines: Setting environment variable with ps-rule-assert task
- task: ps-rule-assert@0
  displayName: Run PSRule analysis
  inputs:
    inputType: repository
  env:
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_ID: 00000000-0000-0000-0000-000000000000
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_KEY: $(WORKSPACE_KEY)

Upload results with PowerShell

To upload results from PSRule to Azure Monitor, use the Send-PSRuleMonitorRecord cmdlet. Results can by piped directly from Invoke-PSRule or stored and piped from a variable.

The Send-PSRuleMonitorRecord cmdlet requires a Log Analytics workspace to send data to. A workspace can be specified by using the -WorkspaceId and -SharedKey parameters.

For example:

$data | Invoke-PSRule | Send-PSRuleMonitorRecord -WorkspaceId <workspaceId> -SharedKey <primaryKey>;

The following example shows using analysis results from a pre-built module:

$results = Invoke-PSRule -InputPath .\*.json -Module 'PSRule.Rules.Azure';
$results | Send-PSRuleMonitorRecord -WorkspaceId <workspaceId> -SharedKey <primaryKey>;

Querying logs from Azure Monitor

By default, PSRule results are stored in the PSRule_CL table. The results can be queries from the Log Analytics workspace using Kusto.

The following query returns all rule records from the last hour that failed:

PSRule_CL
| where Outcome_s == "Fail" and TimeGenerated > ago(1h)

To query these results from PowerShell use:

Invoke-AzOperationalInsightsQuery -WorkspaceId <workspaceId> -Query 'PSRule_CL | where Outcome_s == "Fail" and TimeGenerated > ago(1h)'

Language reference

Commands

The following commands exist in the PSRule.Monitor module:

Changes and versioning

Modules in this repository will use the semantic versioning model to declare breaking changes from v1.0.0. Prior to v1.0.0, breaking changes may be introduced in minor (0.x.0) version increments. For a list of module changes please see the change log.

Pre-release module versions are created on major commits and can be installed from the PowerShell Gallery. Pre-release versions should be considered experimental. Modules and change log details for pre-releases will be removed as standard releases are made available.

Contributing

This project welcomes contributions and suggestions. If you are ready to contribute, please visit the contribution guide.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Maintainers

License

This project is licensed under the MIT License.