Documentation updates (#2298)
This commit is contained in:
Bernie White
GitHub
Родитель
2441ba6815
Коммит
190d594c38
|
|
@ -33,6 +33,9 @@
|
|||
"editor.tabSize": 4,
|
||||
"editor.formatOnSave": false
|
||||
},
|
||||
"[html]": {
|
||||
"editor.formatOnSave": false
|
||||
},
|
||||
"files.associations": {
|
||||
"**/.azure-pipelines/*.yaml": "azure-pipelines",
|
||||
"**/.azure-pipelines/jobs/*.yaml": "azure-pipelines",
|
||||
|
|
|
|||
|
|
@ -243,6 +243,6 @@ Thank you for taking the time to contribute.
|
|||
[github-fork]: https://help.github.com/en/github/getting-started-with-github/fork-a-repo
|
||||
[github-pr]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests
|
||||
[github-pr-create]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork
|
||||
[build]: docs/install-instructions.md#building-from-source
|
||||
[build]: docs/install.md#building-from-source
|
||||
[vscode]: https://code.visualstudio.com/
|
||||
[issues]: https://github.com/Azure/PSRule.Rules.Azure/issues
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ PSRule for Azure uses the principles of the Azure Well-Architected Framework (WA
|
|||
- **Demonstrate** — how you can implement the change with examples.
|
||||
|
||||
If you want to write your own tests, you can do that too in your choice of YAML, JSON, or PowerShell.
|
||||
However with over 360 tests already built, you can identify and fix issues day one.
|
||||
However with over 390 tests already built, you can identify and fix issues day one.
|
||||
|
||||
## Introducing PSRule for Azure
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,14 @@
|
|||
@keyframes heart {
|
||||
0%, 40%, 80%, 100% {
|
||||
|
||||
0%,
|
||||
40%,
|
||||
80%,
|
||||
100% {
|
||||
transform: scale(1);
|
||||
}
|
||||
20%, 60% {
|
||||
|
||||
20%,
|
||||
60% {
|
||||
transform: scale(1.15);
|
||||
}
|
||||
}
|
||||
|
|
@ -22,20 +28,44 @@
|
|||
}
|
||||
|
||||
:root {
|
||||
--md-admonition-icon--experimental: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill-rule="evenodd" d="M8 8.807V3.5h-.563a.75.75 0 0 1 0-1.5h9.125a.75.75 0 0 1 0 1.5H16v5.307l5.125 9.301c.964 1.75-.302 3.892-2.299 3.892H5.174c-1.998 0-3.263-2.142-2.3-3.892L8 8.807zM14.5 3.5h-5V9a.75.75 0 0 1-.093.362L7.127 13.5h9.746l-2.28-4.138A.75.75 0 0 1 14.5 9V3.5zM4.189 18.832 6.3 15h11.4l2.111 3.832a1.125 1.125 0 0 1-.985 1.668H5.174a1.125 1.125 0 0 1-.985-1.668z"/></svg>')
|
||||
--md-admonition-icon--experimental: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill-rule="evenodd" d="M8 8.807V3.5h-.563a.75.75 0 0 1 0-1.5h9.125a.75.75 0 0 1 0 1.5H16v5.307l5.125 9.301c.964 1.75-.302 3.892-2.299 3.892H5.174c-1.998 0-3.263-2.142-2.3-3.892L8 8.807zM14.5 3.5h-5V9a.75.75 0 0 1-.093.362L7.127 13.5h9.746l-2.28-4.138A.75.75 0 0 1 14.5 9V3.5zM4.189 18.832 6.3 15h11.4l2.111 3.832a1.125 1.125 0 0 1-.985 1.668H5.174a1.125 1.125 0 0 1-.985-1.668z"/></svg>');
|
||||
--md-admonition-icon--learn: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M12.292 2.06v-.001l11.25 4.75a.749.749 0 0 1 0 1.382L19 10.108V15a.75.75 0 0 1-.11.391h-.001a2.84 2.84 0 0 1-.392.482c-.249.256-.625.58-1.163.896-1.08.638-2.776 1.23-5.334 1.23-.673 0-1.286-.041-1.846-.113a.75.75 0 0 1 .192-1.487c.492.063 1.042.1 1.654.1 2.317 0 3.746-.533 4.572-1.021.31-.178.596-.397.849-.65l.079-.085V10.74l-5.208 2.2a.75.75 0 0 1-.584 0L5.75 10.424v3.17c.502.129.96.391 1.327.758.579.578.923 1.41.923 2.428v4.5a.761.761 0 0 1-.345.634 2.157 2.157 0 0 1-.21.117 3.923 3.923 0 0 1-.52.213A6.121 6.121 0 0 1 5 22.532a6.092 6.092 0 0 1-1.925-.288 4.065 4.065 0 0 1-.52-.213 1.816 1.816 0 0 1-.22-.124.757.757 0 0 1-.335-.624v-4.5c0-1.02.344-1.85.923-2.43a2.904 2.904 0 0 1 1.327-.757V9.793L.458 8.19a.75.75 0 0 1 0-1.38l11.25-4.75a.75.75 0 0 1 .584 0ZM12 11.436 21.322 7.5 12 3.564 2.678 7.5ZM5 15c-.377 0-.745.141-1.017.413-.265.265-.483.7-.483 1.368v4.022c.299.105.797.228 1.5.228s1.201-.123 1.5-.228V16.78c0-.669-.218-1.103-.483-1.368A1.433 1.433 0 0 0 5 15Z"></path></svg>');
|
||||
}
|
||||
|
||||
/* experimental */
|
||||
.md-typeset .admonition.experimental,
|
||||
.md-typeset details.experimental {
|
||||
border-color: rgb(124, 77, 255)
|
||||
}
|
||||
.md-typeset .experimental > .admonition-title,
|
||||
.md-typeset .experimental > summary {
|
||||
background-color: rgba(124,77,255,.1);;
|
||||
|
||||
.md-typeset .experimental>.admonition-title,
|
||||
.md-typeset .experimental>summary {
|
||||
background-color: rgba(124, 77, 255, .1);
|
||||
border-color: rgb(124, 77, 255);
|
||||
}
|
||||
.md-typeset .experimental > .admonition-title::before,
|
||||
.md-typeset .experimental > summary::before {
|
||||
|
||||
.md-typeset .experimental>.admonition-title::before,
|
||||
.md-typeset .experimental>summary::before {
|
||||
background-color: rgb(124, 77, 255);
|
||||
-webkit-mask-image: var(--md-admonition-icon--experimental);
|
||||
mask-image: var(--md-admonition-icon--experimental);
|
||||
mask-image: var(--md-admonition-icon--experimental);
|
||||
}
|
||||
|
||||
/* learn */
|
||||
.md-typeset .admonition.learn,
|
||||
.md-typeset details.learn {
|
||||
border-color: rgb(0, 191, 165)
|
||||
}
|
||||
|
||||
.md-typeset .learn>.admonition-title,
|
||||
.md-typeset .learn>summary {
|
||||
background-color: rgba(0, 191, 165, .1);
|
||||
border-color: rgb(0, 191, 165)
|
||||
}
|
||||
|
||||
.md-typeset .learn>.admonition-title::before,
|
||||
.md-typeset .learn>summary::before {
|
||||
background-color: rgb(0, 191, 165);
|
||||
-webkit-mask-image: var(--md-admonition-icon--learn);
|
||||
mask-image: var(--md-admonition-icon--learn);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,129 @@
|
|||
---
|
||||
author: BernieWhite
|
||||
---
|
||||
|
||||
# Suppression and excluding rules
|
||||
|
||||
By default, PSRule will attempt to read and test all files.
|
||||
You can configure options to:
|
||||
|
||||
- Control which files PSRule tests.
|
||||
- Disable specific rules that don't apply to your environment.
|
||||
- Configure exceptions for special cases.
|
||||
|
||||
!!! Abstract
|
||||
This topic covers how you can configure PSRule to ignore files, specific rules, or rules for special cases.
|
||||
|
||||
## Excluding a rule
|
||||
|
||||
[:octicons-book-24: Docs][1]
|
||||
|
||||
You can **exclude** a rule to effectively _disable_ the rule.
|
||||
When excluded, a rule is not used to test any Azure resources.
|
||||
|
||||
To exclude a rule, set the `Rule.Exclude` option within the `ps-rule.yaml` file.
|
||||
|
||||
```yaml title="ps-rule.yaml"
|
||||
rule:
|
||||
exclude:
|
||||
# Ignore the following rules for all resources
|
||||
- Azure.VM.UseHybridUseBenefit
|
||||
- Azure.VM.Standalone
|
||||
```
|
||||
|
||||
[1]: https://aka.ms/ps-rule/options#ruleexclude
|
||||
|
||||
## Suppress a rule individually
|
||||
|
||||
[:octicons-book-24: Docs][2]
|
||||
|
||||
You can **suppress** a rule to effectively _skip_ or _ignore_ a rule for a specific case or exception.
|
||||
|
||||
To suppress a rule, set `Suppression` option within the `ps-rule.yaml` file.
|
||||
PSRule allows you to specify the name of the rule and the name of the resources that will be suppressed.
|
||||
|
||||
```yaml title="ps-rule.yaml"
|
||||
suppression:
|
||||
Azure.Storage.SoftDelete:
|
||||
# Ignore soft delete on the following non-production storage accounts
|
||||
- storagedeveus6jo36t
|
||||
- storagedeveus1df278
|
||||
```
|
||||
|
||||
!!! Tip
|
||||
Use comments within `ps-rule.yaml` to describe the reason why rules are excluded or suppressed.
|
||||
Meaningful comments help during peer review within a Pull Request (PR).
|
||||
Also consider including a date if the exclusions or suppressions are temporary.
|
||||
|
||||
[2]: https://aka.ms/ps-rule/options#suppression
|
||||
|
||||
## Suppressing common cases
|
||||
|
||||
[:octicons-book-24: Docs][3]
|
||||
|
||||
If you need to commonly suppress a rule for multiple resources you can use a Suppression Group.
|
||||
A Suppression Group allow you to define a condition for when a rule should be suppressed.
|
||||
|
||||
!!! Example
|
||||
For example, suppose you want to suppress the `Azure.Storage.SoftDelete` rule for Storage Accounts based on a tag.
|
||||
|
||||
A Suppression Group can be defined within a `.Rule.yaml` file within the `.ps-rule/` sub-directory.
|
||||
Create this directory in your repository or current working path if it doesn't already exist.
|
||||
|
||||
```yaml title=".ps-rule/Suppression.Rule.yaml"
|
||||
---
|
||||
# Synopsis: Ignore soft delete for development storage accounts
|
||||
apiVersion: github.com/microsoft/PSRule/v1
|
||||
kind: SuppressionGroup
|
||||
metadata:
|
||||
name: Local.IgnoreNonProdStorage
|
||||
spec:
|
||||
rule:
|
||||
- Azure.Storage.SoftDelete
|
||||
if:
|
||||
field: tags.env
|
||||
equals: dev
|
||||
```
|
||||
|
||||
!!! Learn
|
||||
To learn more, see [suppression groups][3] and [expressions][4].
|
||||
|
||||
[3]: https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_SuppressionGroups/
|
||||
[4]: https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Expressions/
|
||||
|
||||
## Ignoring files
|
||||
|
||||
[:octicons-book-24: Docs][5]
|
||||
|
||||
To exclude or ignore files from being processed, configure the [Input.PathIgnore][5] option.
|
||||
This option allows you to ignore files using a path spec.
|
||||
|
||||
To ignore files with common extensions, set the `Input.PathIgnore` option within the `ps-rule.yaml` file.
|
||||
|
||||
```yaml title="ps-rule.yaml"
|
||||
input:
|
||||
pathIgnore:
|
||||
# Exclude files with these extensions
|
||||
- '*.md'
|
||||
- '*.png'
|
||||
# Exclude specific configuration files
|
||||
- 'bicepconfig.json'
|
||||
```
|
||||
|
||||
To ignore all files with some exceptions, set the `Input.PathIgnore` option within the `ps-rule.yaml` file.
|
||||
|
||||
```yaml title="ps-rule.yaml"
|
||||
input:
|
||||
pathIgnore:
|
||||
# Exclude all files
|
||||
- '*'
|
||||
# Only process deploy.bicep files
|
||||
- '!**/deploy.bicep'
|
||||
```
|
||||
|
||||
!!! Tip
|
||||
Some common file exclusions are recommended for working with Azure Bicep source files.
|
||||
See [Configuring path exclusions][6] for details.
|
||||
|
||||
[5]: https://aka.ms/ps-rule/options#inputpathignore
|
||||
[6]: ../using-bicep.md#configuring-path-exclusions
|
||||
|
|
@ -324,85 +324,6 @@ configuration:
|
|||
|
||||
[2]: setup/configuring-expansion.md#bicep-source-expansion
|
||||
|
||||
### Ignoring rules
|
||||
|
||||
To prevent a rule executing you can either:
|
||||
|
||||
- **Exclude** — The rule is not executed for any resource.
|
||||
- **Suppress** — The rule is not executed for a specific resource by name.
|
||||
|
||||
To exclude a rule, set `Rule.Exclude` option within the `ps-rule.yaml` file.
|
||||
|
||||
[:octicons-book-24: Docs][3]
|
||||
|
||||
```yaml title="ps-rule.yaml"
|
||||
rule:
|
||||
exclude:
|
||||
# Ignore the following rules for all resources
|
||||
- Azure.VM.UseHybridUseBenefit
|
||||
- Azure.VM.Standalone
|
||||
```
|
||||
|
||||
To suppress a rule, set `Suppression` option within the `ps-rule.yaml` file.
|
||||
|
||||
[:octicons-book-24: Docs][4]
|
||||
|
||||
```yaml title="ps-rule.yaml"
|
||||
suppression:
|
||||
Azure.AKS.AuthorizedIPs:
|
||||
# Exclude the following externally managed AKS clusters
|
||||
- aks-cluster-prod-eus-001
|
||||
Azure.Storage.SoftDelete:
|
||||
# Exclude the following non-production storage accounts
|
||||
- storagedeveus6jo36t
|
||||
- storagedeveus1df278
|
||||
```
|
||||
|
||||
!!! tip
|
||||
Use comments within `ps-rule.yaml` to describe the reason why rules are excluded or suppressed.
|
||||
Meaningful comments help during peer review within a Pull Request (PR).
|
||||
Also consider including a date if the exclusions or suppressions are temporary.
|
||||
|
||||
[3]: https://aka.ms/ps-rule/options#ruleexclude
|
||||
[4]: https://aka.ms/ps-rule/options#suppression
|
||||
|
||||
### Ignoring files
|
||||
|
||||
[:octicons-book-24: Docs][10]
|
||||
|
||||
To exclude or ignore files from being processed, configure the [Input.PathIgnore][10] option.
|
||||
This option allows you to ignore files using a path spec.
|
||||
|
||||
To ignore files with common extensions, set the `Input.PathIgnore` option within the `ps-rule.yaml` file.
|
||||
|
||||
```yaml title="ps-rule.yaml"
|
||||
input:
|
||||
pathIgnore:
|
||||
# Exclude files with these extensions
|
||||
- '*.md'
|
||||
- '*.png'
|
||||
# Exclude specific configuration files
|
||||
- 'bicepconfig.json'
|
||||
```
|
||||
|
||||
To ignore all files with some exceptions, set the `Input.PathIgnore` option within the `ps-rule.yaml` file.
|
||||
|
||||
```yaml title="ps-rule.yaml"
|
||||
input:
|
||||
pathIgnore:
|
||||
# Exclude all files
|
||||
- '*'
|
||||
# Only process deploy.bicep files
|
||||
- '!**/deploy.bicep'
|
||||
```
|
||||
|
||||
!!! Tip
|
||||
Some common file exclusions are recommended for working with Azure Bicep source files.
|
||||
See [Configuring path exclusions][11] for details.
|
||||
|
||||
[10]: https://aka.ms/ps-rule/options#inputpathignore
|
||||
[11]: using-bicep.md#configuring-path-exclusions
|
||||
|
||||
### Advanced configuration
|
||||
|
||||
[:octicons-book-24: Docs][5]
|
||||
|
|
@ -411,3 +332,11 @@ PSRule for Azure comes with many configuration options.
|
|||
The setup section explains in detail how to configure each option.
|
||||
|
||||
[5]: setup/configuring-options.md
|
||||
|
||||
## Recommended content
|
||||
|
||||
- [Suppression and excluding rules][10]
|
||||
- [Using Bicep source][11]
|
||||
|
||||
[10]: concepts/suppression.md
|
||||
[11]: using-bicep.md
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ The exported state is processed later during analysis.
|
|||
- **What's not exported** — Resource data such as:
|
||||
- The contents of blobs stored on a storage account, or databases tables.
|
||||
|
||||
[1]: install-instructions.md#installing-locally
|
||||
[1]: install.md#installing-locally
|
||||
|
||||
## Export an Azure subscription
|
||||
|
||||
|
|
|
|||
|
|
@ -124,7 +124,7 @@ To start writing your own custom rules you can use YAML, JSON, or PowerShell.
|
|||
PowerShell experience is required for some scenarios.
|
||||
We have a walk through scenario [Enforcing custom tags][9] to get you started.
|
||||
|
||||
[7]: install-instructions.md
|
||||
[7]: install.md
|
||||
[8]: validating-locally.md
|
||||
[9]: customization/enforce-custom-tags.md
|
||||
|
||||
|
|
|
|||
|
|
@ -11,6 +11,11 @@ PSRule for Azure helps you quickly identify and fix issues to improve the qualit
|
|||
Tests include documentation with official documentation references and examples.
|
||||
Use the Azure Bicep or template examples to adapt your solution to recommendations.
|
||||
|
||||
!!! Note
|
||||
Start exploring the list of [rules included with PSRule for Azure][14].
|
||||
|
||||
[14]: en/rules/index.md
|
||||
|
||||
## Framework aligned
|
||||
|
||||
PSRule for Azure is aligned to the [Azure Well-Architected Framework (WAF)][2].
|
||||
|
|
@ -66,6 +71,12 @@ Pre-flight validation can be integrated into a continuous integration (CI) pipel
|
|||
- **Quality gates** — Implement quality gates between environments such as dev, test, and production.
|
||||
- **Monitor continuously** — Perform ongoing checks for configuration optimization opportunities.
|
||||
|
||||
!!! Learn
|
||||
You can learn more about Azure Bicep with the following links:
|
||||
|
||||
- [What is Bicep?](https://learn.microsoft.com/azure/azure-resource-manager/bicep/overview?tabs=bicep)
|
||||
- [Learn modules for Azure Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/learn-bicep)
|
||||
|
||||
## Cross-platform
|
||||
|
||||
PSRule for Azure uses modern PowerShell libraries at its core,
|
||||
|
|
@ -86,7 +97,7 @@ For installation options see [installation][8].
|
|||
[5]: https://marketplace.visualstudio.com/items?itemName=bewhite.ps-rule
|
||||
[6]: https://github.com/marketplace/actions/psrule
|
||||
[7]: https://marketplace.visualstudio.com/items?itemName=bewhite.psrule-vscode
|
||||
[8]: install-instructions.md
|
||||
[8]: install.md
|
||||
|
||||
*[ARM]: Azure Resource Manager
|
||||
*[WAF]: Well-Architected Framework
|
||||
|
|
|
|||
|
|
@ -2,16 +2,27 @@
|
|||
author: BernieWhite
|
||||
---
|
||||
|
||||
# Installation
|
||||
# How to install PSRule for Azure
|
||||
|
||||
PSRule for Azure supports running within continuous integration (CI) systems or locally.
|
||||
It is shipped as a PowerShell module which makes it easy to install and distribute updates.
|
||||
|
||||
Task | Options
|
||||
---- | ------
|
||||
Run tests within CI pipelines | With [GitHub Actions][8] _or_ [Azure Pipelines][9] _or_ [PowerShell][10]
|
||||
Run tests locally during development | With [Visual Studio Code][11] _and_ [PowerShell][10]
|
||||
Create custom tests for your organization | With [Visual Studio Code][11] _and_ [PowerShell][10]
|
||||
|
||||
!!! Tip
|
||||
PSRule for Azure provides native integration to popular CI systems such as GitHub Actions and Azure Pipelines.
|
||||
If you are using a different CI system you can use the local install to run on MacOS,
|
||||
Linux, and Windows worker nodes.
|
||||
|
||||
[8]: #with-github-actions
|
||||
[9]: #with-azure-pipelines
|
||||
[10]: #with-powershell
|
||||
[11]: #with-visual-studio-code
|
||||
|
||||
## With GitHub Actions
|
||||
|
||||
[:octicons-workflow-24: GitHub Action][1]
|
||||
|
|
@ -22,7 +33,7 @@ Install and use PSRule for Azure with GitHub Actions by referencing the `microso
|
|||
|
||||
Install the latest stable version of PSRule for Azure.
|
||||
|
||||
```yaml
|
||||
```yaml title="GitHub Actions"
|
||||
- name: Analyze Azure template files
|
||||
uses: microsoft/ps-rule@v2.9.0
|
||||
with:
|
||||
|
|
@ -32,8 +43,8 @@ Install and use PSRule for Azure with GitHub Actions by referencing the `microso
|
|||
=== "Pre-release"
|
||||
|
||||
Install the latest stable or pre-release version of PSRule for Azure.
|
||||
|
||||
```yaml
|
||||
|
||||
```yaml title="GitHub Actions"
|
||||
- name: Analyze Azure template files
|
||||
uses: microsoft/ps-rule@v2.9.0
|
||||
with:
|
||||
|
|
@ -43,7 +54,11 @@ Install and use PSRule for Azure with GitHub Actions by referencing the `microso
|
|||
|
||||
This will automatically install compatible versions of all dependencies.
|
||||
|
||||
!!! Note
|
||||
For additional examples on commonly configured parameters see [Creating your pipeline][12].
|
||||
|
||||
[1]: https://github.com/marketplace/actions/psrule
|
||||
[12]: creating-your-pipeline.md
|
||||
|
||||
## With Azure Pipelines
|
||||
|
||||
|
|
@ -56,7 +71,7 @@ Install the extension from the marketplace, then use the `ps-rule-assert` task i
|
|||
|
||||
Install the latest stable version of PSRule for Azure.
|
||||
|
||||
```yaml
|
||||
```yaml title="Azure Pipelines"
|
||||
- task: ps-rule-assert@2
|
||||
displayName: Analyze Azure template files
|
||||
inputs:
|
||||
|
|
@ -67,7 +82,7 @@ Install the extension from the marketplace, then use the `ps-rule-assert` task i
|
|||
|
||||
Install the latest stable or pre-release version of PSRule for Azure.
|
||||
|
||||
```yaml
|
||||
```yaml title="Azure Pipelines"
|
||||
- task: ps-rule-install@2
|
||||
displayName: Install PSRule for Azure (pre-release)
|
||||
inputs:
|
||||
|
|
@ -82,22 +97,51 @@ Install the extension from the marketplace, then use the `ps-rule-assert` task i
|
|||
|
||||
This will automatically install compatible versions of all dependencies.
|
||||
|
||||
!!! Note
|
||||
For additional examples on commonly configured parameters see [Creating your pipeline][12].
|
||||
|
||||
[2]: https://marketplace.visualstudio.com/items?itemName=bewhite.ps-rule
|
||||
|
||||
## Installing locally
|
||||
## With Visual Studio Code
|
||||
|
||||
[:octicons-download-24: Extension][5]
|
||||
|
||||
An extension for Visual Studio Code is available.
|
||||
The Visual Studio Code extension includes a built-in task to test locally and configuration schemas.
|
||||
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/microsoft/PSRule-vscode/main/docs/images/tasks-provider.png" alt="Built-in tasks shown in task list" />
|
||||
</p>
|
||||
|
||||
To learn about Visual Studio Code support see the [marketplace extension][5].
|
||||
|
||||
For best results, configure the `PSRule.Rules.Azure` module using `ps-rule.yaml` by setting `requires` and `include` options.
|
||||
|
||||
```yaml title="ps-rule.yaml"
|
||||
requires:
|
||||
PSRule.Rules.Azure: '>=1.27.0'
|
||||
|
||||
include:
|
||||
module:
|
||||
- PSRule.Rules.Azure
|
||||
```
|
||||
|
||||
!!! Note
|
||||
Currently the Visual Studio Code extension relies on PSRule for Azure installed by PowerShell.
|
||||
|
||||
[5]: https://marketplace.visualstudio.com/items?itemName=bewhite.psrule-vscode
|
||||
|
||||
## With PowerShell
|
||||
|
||||
PSRule for Azure can be installed locally from the PowerShell Gallery using PowerShell.
|
||||
You can also use this option to install on CI workers that are not natively supported.
|
||||
|
||||
### PreRequisites
|
||||
### Prerequisites
|
||||
|
||||
| Operating System | Tool | Overview | Installation Link |
|
||||
| ----- | ----- | ----- | --- |
|
||||
| Windows | Windows PowerShell | Support for version 5.1 with .NET Framework 4.7.2 or greater. | [link](https://dotnet.microsoft.com/download/dotnet-framework/net48) |
|
||||
| Windows, MacOS, Linux | PowerShell | Version 7.2 or greater is support. | [link](https://github.com/PowerShell/PowerShell#get-powershell) |
|
||||
| - | - | Multiple PowerShell modules are required (PlatyPS, Pester, PSScriptAnalyzer, PowerShellGet, PackageManagement, InvokeBuild, PSRule). | Installed when you run the `build.ps1` script |
|
||||
| - | .NET | .NET SDK v6 is required. | [link](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) |
|
||||
| - | Bicep CLI | PsRule depends on the Bicep CLI to decompile (expand) Bicep modules to ARM | [link](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install) |
|
||||
| Operating System | Tool | Installation Link |
|
||||
| ---------------- | ---- | ----------------- |
|
||||
| Windows | Windows PowerShell 5.1 with .NET Framework 4.7.2 or greater. | [link](https://dotnet.microsoft.com/download/dotnet-framework/net48) |
|
||||
| Windows, MacOS, Linux | PowerShell version 7.2.x or greater. | [link](https://github.com/PowerShell/PowerShell#get-powershell) |
|
||||
|
||||
To use PSRule for Azure, PSRule a separate PowerShell module must be installed.
|
||||
The required version will automatically be installed along-side PSRule for Azure.
|
||||
|
|
@ -196,7 +240,29 @@ To use a pre-release version of PSRule for Azure add the `-AllowPrerelease` swit
|
|||
Install-Module -Name PSRule.Rules.Azure -Repository PSGallery -Scope AllUsers -AllowPrerelease
|
||||
```
|
||||
|
||||
#### Development dependencies
|
||||
## Building from source
|
||||
|
||||
[:octicons-file-code-24: Source][6]
|
||||
|
||||
PSRule for Azure is provided as open source on GitHub.
|
||||
To build PSRule for Azure from source code:
|
||||
|
||||
1. Clone the GitHub [repository][6].
|
||||
2. Run `./build.ps1` from a PowerShell terminal in the cloned path.
|
||||
|
||||
This build script will compile the module and documentation then output the result into `out/modules/PSRule.Rules.Azure`.
|
||||
|
||||
[6]: https://github.com/Azure/PSRule.Rules.Azure.git
|
||||
|
||||
### Development dependencies
|
||||
|
||||
| Operating System | Tool | Overview | Installation Link |
|
||||
| ---------------- | ---- | -------- | ----------------- |
|
||||
| Windows | Windows PowerShell | Support for version 5.1 with .NET Framework 4.7.2 or greater. | [link](https://dotnet.microsoft.com/download/dotnet-framework/net48) |
|
||||
| Windows, MacOS, Linux | PowerShell | Version 7.2 or greater is support. | [link](https://github.com/PowerShell/PowerShell#get-powershell) |
|
||||
| - | - | Multiple PowerShell modules are required (PlatyPS, Pester, PSScriptAnalyzer, PowerShellGet, PackageManagement, InvokeBuild, PSRule). | Installed when you run the `build.ps1` script |
|
||||
| - | .NET | .NET SDK v6 is required. | [link](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) |
|
||||
| - | Bicep CLI | PSRule depends on the Bicep CLI to decompile (expand) Bicep modules to ARM | [link](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install) |
|
||||
|
||||
The following dependencies will be automatically installed if the required versions are not present:
|
||||
|
||||
|
|
@ -211,21 +277,7 @@ The following dependencies will be automatically installed if the required versi
|
|||
|
||||
These dependencies are only required for building and running tests for PSRule for Azure.
|
||||
|
||||
### Building from source
|
||||
|
||||
[:octicons-file-code-24: Source][6]
|
||||
|
||||
PSRule for Azure is provided as open source on GitHub.
|
||||
To build PSRule for Azure from source code:
|
||||
|
||||
1. Clone the GitHub [repository][6].
|
||||
2. Run `./build.ps1` from a PowerShell terminal in the cloned path.
|
||||
|
||||
This build script will compile the module and documentation then output the result into `out/modules/PSRule.Rules.Azure`.
|
||||
|
||||
[6]: https://github.com/Azure/PSRule.Rules.Azure.git
|
||||
|
||||
#### Troubleshooting
|
||||
### Troubleshooting
|
||||
|
||||
If the `./build.ps1` script fails, you can start troubleshooting this by:
|
||||
|
||||
|
|
@ -235,7 +287,7 @@ If the `./build.ps1` script fails, you can start troubleshooting this by:
|
|||
- Check if your .NET setup is connected to any Nuget repositories and if there's any connectivity or authentication issues.
|
||||
- Installation of some pre-reqs may require admin privileges.
|
||||
|
||||
### Limited access networks
|
||||
## Limited access networks
|
||||
|
||||
If you are on a network that does not permit Internet access to the PowerShell Gallery,
|
||||
download the required PowerShell modules on an alternative device that has access.
|
||||
|
|
@ -199,7 +199,7 @@ Once the results have been published to the Log Analytics workspace, they can be
|
|||
results against the `PSRule_CL` table (under Custom Logs). For more information on how to write Log
|
||||
Analytics querys, review the [Log Analytics tutortial][11].
|
||||
|
||||
[11]: https://docs.microsoft.com/azure/azure-monitor/logs/log-analytics-tutorial
|
||||
[11]: https://learn.microsoft.com/azure/azure-monitor/logs/log-analytics-tutorial
|
||||
|
||||
### Workbook
|
||||
|
||||
|
|
@ -209,5 +209,5 @@ A [sample Azure Monitor Workbook][13] is available in the PSRule for Azure GitHu
|
|||
This workbook can be imported directly into Azure Monitor and used as a foundation to build from.
|
||||
Review the [Workbook creation tutorial][12] for instructions on how to work with the sample Workbook.
|
||||
|
||||
[12]: https://docs.microsoft.com/azure/azure-monitor/visualize/workbooks-create-workbook
|
||||
[12]: https://learn.microsoft.com/azure/azure-monitor/visualize/workbooks-create-workbook
|
||||
[13]: https://github.com/Azure/PSRule.Rules.Azure/blob/main/docs/setup/workbook.json
|
||||
|
|
|
|||
|
|
@ -232,7 +232,11 @@ configuration:
|
|||
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
|
||||
[16]: https://learn.microsoft.com/azure/azure-resource-manager/bicep/parameter-files?tabs=Bicep
|
||||
|
||||
## Restoring modules from a private registry
|
||||
|
||||
|
|
@ -242,7 +246,7 @@ Storing modules in a private registry gives you a central location to reference
|
|||
To test Bicep deployments which uses modules stored in a private registry, these modules must be restored.
|
||||
The restore process automatically occurs when PSRule is run, however some additional steps are required to authenticate.
|
||||
|
||||
To prepare your registry for storing Bicep modules see [Create private registry for Bicep modules][13].
|
||||
To prepare your registry for storing Bicep modules see [Create private registry for Bicep modules][15].
|
||||
|
||||
To configure authentication for PSRule to a private registry:
|
||||
|
||||
|
|
@ -259,7 +263,7 @@ To configure your registry see [Make your container registry content publicly av
|
|||
You can configure PSRule to check for the minimum Bicep version.
|
||||
See [configuring minimum version][10] for information on how to enable this check.
|
||||
|
||||
[13]: https://learn.microsoft.com/azure/azure-resource-manager/bicep/private-module-registry
|
||||
[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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,75 +0,0 @@
|
|||
---
|
||||
author: BernieWhite
|
||||
---
|
||||
|
||||
# Validating locally
|
||||
|
||||
While preparing infrastructure code artifacts, Azure resources can be validated locally.
|
||||
PSRule for Azure can be installed locally on MacOS, Linux, and Windows for local validation.
|
||||
|
||||
!!! Tip
|
||||
If you haven't already, follow the instructions on [Installing locally][1] before continuing.
|
||||
If analyzing Azure resources from Bicep source files, complete [Setup Bicep][2].
|
||||
|
||||
[1]: install-instructions.md#installing-locally
|
||||
[2]: setup/setup-bicep.md
|
||||
|
||||
## With Visual Studio Code
|
||||
|
||||
[:octicons-download-24: Extension][3]
|
||||
|
||||
An extension for Visual Studio Code is available for an integrated experience using PSRule for Azure.
|
||||
The Visual Studio Code extension includes a built-in `PSRule: Run analysis` task.
|
||||
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/microsoft/PSRule-vscode/main/docs/images/tasks-provider.png" alt="Built-in tasks shown in task list" />
|
||||
</p>
|
||||
|
||||
To learn about tasks in Visual Studio Code see [Integrate with External Tools via Tasks][4].
|
||||
|
||||
To use PSRule for Azure with the built-in `PSRule: Run analysis` task, insert the following into `.vscode/tasks.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "PSRule",
|
||||
"problemMatcher": [
|
||||
"$PSRule"
|
||||
],
|
||||
"label": "PSRule: Run analysis",
|
||||
"modules": [
|
||||
"PSRule.Rules.Azure"
|
||||
],
|
||||
"presentation": {
|
||||
"clear": true,
|
||||
"panel": "dedicated"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
!!! Example
|
||||
A complete `.vscode/tasks.json` might look like the following:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "2.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"type": "PSRule",
|
||||
"problemMatcher": [
|
||||
"$PSRule"
|
||||
],
|
||||
"label": "PSRule: Run analysis",
|
||||
"modules": [
|
||||
"PSRule.Rules.Azure"
|
||||
],
|
||||
"presentation": {
|
||||
"clear": true,
|
||||
"panel": "dedicated"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
[3]: https://marketplace.visualstudio.com/items?itemName=bewhite.psrule-vscode
|
||||
[4]: https://code.visualstudio.com/docs/editor/tasks
|
||||
10
mkdocs.yml
10
mkdocs.yml
|
|
@ -45,7 +45,7 @@ nav:
|
|||
- About: about.md
|
||||
- Features: features.md
|
||||
- FAQ: faq.md
|
||||
- Installation: install-instructions.md
|
||||
- Install: install.md
|
||||
- Testing infrastructure code:
|
||||
- Expanding source files: expanding-source-files.md
|
||||
- Using templates: using-templates.md
|
||||
|
|
@ -55,7 +55,8 @@ nav:
|
|||
- Testing deployed resources:
|
||||
- Exporting rule data: export-rule-data.md
|
||||
- Analyzing resources: analyzing-resources.md
|
||||
- Validating locally: validating-locally.md
|
||||
- Concepts:
|
||||
- Suppression: concepts/suppression.md
|
||||
- Customization:
|
||||
- Storing custom rules: customization/storing-custom-rules.md
|
||||
- Enforcing custom tags: customization/enforce-custom-tags.md
|
||||
|
|
@ -128,14 +129,13 @@ plugins:
|
|||
- tags
|
||||
- redirects:
|
||||
redirect_maps:
|
||||
install-instructions.md: install.md
|
||||
validating-locally.md: install.md
|
||||
using-metadata.md: using-templates.md
|
||||
customization/index.md: customization/storing-custom-rules.md
|
||||
en/asb-v3.md: en/mcsb-v1.md
|
||||
|
||||
extra:
|
||||
version:
|
||||
provider: mike
|
||||
|
||||
social:
|
||||
- icon: fontawesome/brands/github
|
||||
link: https://github.com/Azure/PSRule.Rules.Azure/
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
<!-- Translations: English -->
|
||||
{% macro t(key) %}{{ {
|
||||
"toc": "In this article"
|
||||
}[key] }}{% endmacro %}
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
<!-- Determine title -->
|
||||
{% import "partials/lang_extras/" ~ config.theme.language ~ ".html" as lang_extras %}
|
||||
|
||||
{% set title = lang_extras.t("toc") or lang.t("toc") %}
|
||||
{% if config.mdx_configs.toc and config.mdx_configs.toc.title %}
|
||||
{% set title = config.mdx_configs.toc.title %}
|
||||
{% endif %}
|
||||
|
||||
<!-- Table of contents -->
|
||||
<nav class="md-nav md-nav--secondary" aria-label="{{ title }}">
|
||||
{% set toc = page.toc %}
|
||||
|
||||
<!--
|
||||
Check whether the content starts with a level 1 headline. If it does, the
|
||||
top-level anchor must be skipped, since it would be redundant to the link
|
||||
to the current page that is located just above the anchor. Therefore we
|
||||
directly continue with the children of the anchor.
|
||||
-->
|
||||
{% set first = toc | first %}
|
||||
{% if first and first.level == 1 %}
|
||||
{% set toc = first.children %}
|
||||
{% endif %}
|
||||
|
||||
<!-- Table of contents title and list -->
|
||||
{% if toc %}
|
||||
<label class="md-nav__title" for="__toc">
|
||||
<span class="md-nav__icon md-icon"></span>
|
||||
{{ title }}
|
||||
</label>
|
||||
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
||||
{% for toc_item in toc %}
|
||||
{% include "partials/toc-item.html" %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{% endif %}
|
||||
</nav>
|
||||
Загрузка…
Ссылка в новой задаче