This commit is contained in:
Bernie White 2019-12-29 22:32:27 +10:00 коммит произвёл GitHub
Родитель 6c97b7c5b8
Коммит 4ebb695349
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
4 изменённых файлов: 281 добавлений и 7 удалений

Просмотреть файл

@ -186,6 +186,7 @@ For walk through examples of PSRule usage see:
- [Validate Azure resources tags](docs/scenarios/azure-tags/azure-tags.md)
- [Validate Kubernetes resources](docs/scenarios/kubernetes-resources/kubernetes-resources.md)
- [Using within continuous integration](docs/scenarios/validation-pipeline/validation-pipeline.md)
- [Packaging rules in a module](docs/scenarios/rule-module/rule-module.md)
- [Writing rule help](docs/scenarios/rule-docs/rule-docs.md)
## Language reference

Просмотреть файл

@ -16,7 +16,6 @@ When authoring rules in PowerShell, PSRule provides the following syntax feature
- Comment metadata.
- `Recommend` keyword.
- `Reason` keyword.
- `$LocalizedData` automatic variable.
These features are each describe in detail in the following sections.
@ -175,7 +174,7 @@ Some examples of annotations include; `severity`, `category`, `author`.
Annotations differ from tags in two key ways:
- Annotations are localized, and can have a different value for different languages. Tags are not.
- Annotations are localized, and can have a different value for different languages; tags are not.
- Tags are indexed and can be used to filter rules; annotations have no affect on rule filtering.
The following reserved annotation exists:
@ -195,7 +194,8 @@ The front matter start and end `---` are not required and can be removed if no a
The document title, indicated by a level one heading `#` is the display name of the rule.
The rule display name is shown when using `Get-PSRuleHelp` and is included in output.
Specify the display name on a single line, wrapping the display name across multiple lines is not supported.
Specify the display name on a single line.
Wrapping the display name across multiple lines is not supported.
For example:
@ -209,9 +209,9 @@ The synopsis section is indicated by the heading `## SYNOPSIS`.
Any text following the heading is interpreted by PSRule and included in output.
The synopsis is displayed when using `Get-PSRule` and `Get-PSRuleHelp` cmdlets.
The synopsis is intended to be a brief description of the rule, a single line.
The _synopsis_ is intended to be a brief description of the rule, over a single line.
A good synopsis should convey the purpose of the rule.
For a more verbose description can be included in the description section.
A more verbose description can be included in the _description_ section.
For example:
@ -227,7 +227,7 @@ The description section is indicated by the heading `## DESCRIPTION`.
Any text following the heading is interpreted by PSRule and included in output.
The description is displayed when using the `Get-PSRuleHelp` cmdlet.
The description is intended to be a verbose description of the rule.
The _description_ is intended to be a verbose description of the rule.
If your rule documentation needs to include background information include it here.
PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph.
@ -250,7 +250,7 @@ The recommendation section is indicated by the heading `## RECOMMENDATION`.
Any text following the heading is interpreted by PSRule and included in output.
The recommendation is displayed when using the `Invoke-PSRule` and `Get-PSRuleHelp` cmdlets.
The recommendation is intended to identify corrective actions that can be taken to address any failures.
The _recommendation_ is intended to identify corrective actions that can be taken to address any failures.
PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph.
Use a blank line to separate paragraphs.

Просмотреть файл

@ -0,0 +1,122 @@
# Copyright (c) Microsoft Corporation.
# Licensed under the MIT License.
#
# Module manifest for module 'Enterprise.Rules'
#
@{
# Script module or binary module file associated with this manifest.
# RootModule = ''
# Version number of this module.
ModuleVersion = '0.0.1'
# Supported PSEditions
# CompatiblePSEditions = @()
# ID used to uniquely identify this module
GUID = '6759ce38-4c5f-4f65-b990-0bfc359aac77'
# Author of this module
Author = 'Microsoft Corporation'
# Company or vendor of this module
CompanyName = 'Microsoft Corporation'
# Copyright statement for this module
Copyright = '(c) Microsoft Corporation. All rights reserved.'
# Description of the functionality provided by this module
# Description = ''
# Minimum version of the PowerShell engine required by this module
# PowerShellVersion = ''
# Name of the PowerShell host required by this module
# PowerShellHostName = ''
# Minimum version of the PowerShell host required by this module
# PowerShellHostVersion = ''
# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# DotNetFrameworkVersion = ''
# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# CLRVersion = ''
# Processor architecture (None, X86, Amd64) required by this module
# ProcessorArchitecture = ''
# Modules that must be imported into the global environment prior to importing this module
# RequiredModules = @()
# Assemblies that must be loaded prior to importing this module
# RequiredAssemblies = @()
# Script files (.ps1) that are run in the caller's environment prior to importing this module.
# ScriptsToProcess = @()
# Type files (.ps1xml) to be loaded when importing this module
# TypesToProcess = @()
# Format files (.ps1xml) to be loaded when importing this module
# FormatsToProcess = @()
# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
# NestedModules = @()
# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
FunctionsToExport = @()
# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
CmdletsToExport = @()
# Variables to export from this module
VariablesToExport = '*'
# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
AliasesToExport = @()
# DSC resources to export from this module
# DscResourcesToExport = @()
# List of all modules packaged with this module
# ModuleList = @()
# List of all files packaged with this module
# FileList = @()
# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
PrivateData = @{
PSData = @{
# Tags applied to this module. These help with module discovery in online galleries.
Tags = @('PSRule-rules')
# A URL to the license for this module.
# LicenseUri = ''
# A URL to the main website for this project.
# ProjectUri = ''
# A URL to an icon representing this module.
# IconUri = ''
# ReleaseNotes of this module
# ReleaseNotes = ''
} # End of PSData hashtable
PSRule = @{
Baseline = 'Enterprise.Default'
}
} # End of PrivateData hashtable
# HelpInfo URI of this module
# HelpInfoURI = ''
# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
# DefaultCommandPrefix = ''
}

Просмотреть файл

@ -0,0 +1,151 @@
# Packaging rules in modules
PSRule supports distribution of rules within modules.
Using a module, rules can be published and installed using standard PowerShell cmdlets.
You should consider packaging rules into a module to:
- Version rules. PowerShell modules support semantic versioning (semver).
- Reuse rules across projects, pipelines or teams.
- Publish rules to external consumers via the PowerShell Gallery.
This scenario covers the following:
- Creating a module manifest
- Including rules and baselines
- Including documentation
## Creating a module manifest
When creating a PowerShell module, a module manifest is an optional file that stores module metadata.
Module manifests use the `.psd1` file extension.
When packaging rules in a module, a module manifest is required for PSRule discover the module.
### Creating the manifest file
A module manifest can be created from PowerShell using the `New-ModuleManifest` cmdlet.
Additionally, Visual Studio Code and many other tools also include snippets for creating a module manifest.
For example:
```powershell
# Create a directory for the module
md ./Enterprise.Rules;
# Create the manifest
New-ModuleManifest -Path ./Enterprise.Rules/Enterprise.Rules.psd1 -Tags 'PSRule-rules';
```
The example above creates a module manifest for a module named _Enterprise.Rules_ tagged with `PSRule-rules`.
The use of the `PSRule-rules` tag is explained in the following section.
### Setting module tags
When PSRule cmdlets are used with the `-Module` parameter, PSRule discovers rule modules.
If the module is already imported, that module is used.
If the module is not imported, PSRule will import the highest version of the module automatically.
For a module to be discovered by PSRule, tag the module with `PSRule-rules`.
To tag modules, find the `Tags` section the `PSData` hashtable in the module manifest and add `PSRule-rules`.
An updated module manifest may look like this:
```powershell
# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
PrivateData = @{
PSData = @{
# Tags applied to this module. These help with module discovery in online galleries.
Tags = @('PSRule-rules')
}
}
```
### Setting a default baseline
Optionally, baselines can be included in rule modules.
If a baseline contains configuration or binding options then setting a default baseline is often desirable.
When a default baseline is set, PSRule will use the named baseline automatically when processing rules from that module.
This feature removes the need for users to specify it manually.
To set a default baseline, add a new property after the `PSData` hashtable ends called `PSRule`.
The `PSRule` property is a hashtable of configuration for PSRule.
Within the hashtable specify the `Baseline` property with the name of the baseline.
For example:
```powershell
# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
PrivateData = @{
PSData = @{
# Tags applied to this module. These help with module discovery in online galleries.
Tags = @('PSRule-rules')
}
PSRule = @{
Baseline = 'Enterprise.Default'
}
}
```
This examples set the default baseline to `Enterprise.Default`.
The default baseline must be included in file ending with `.Rule.yaml` within the module directory structure.
## Including rules and baselines
Rules and baselines can be included anywhere within the module directory structure.
Such as in the root directory of the module or in a nested sub-directory.
By convention, consider including rules and baselines within a `rules` sub-directory within the module.
For example:
- Enterprise.Rules/
- rules/
- NamingStandards.Rule.ps1
- ComplianceStandards.Rule.ps1
- Baseline.Rule.yaml
- Enterprise.Rules.psd1
### File names
For PSRule to find rules included in a module, rule file names must end with the `.Rule.ps1` suffix.
We recommend using the exact case `.Rule.ps1`.
This is because some file systems are case-sensitive.
For example, on Linux `NamingStandards.rule.ps1` would be ignored by PSRule.
Similarly, when including baselines within a module use the `.Rule.yaml` suffix.
## Including documentation
PSRule supports write and packaging rule modules with markdown documentation.
Markdown documentation is automatically interpreted by PSRule and included in output.
When including markdown, files are copied into a directory structure based on the target culture.
For example, store documentation targeted to the culture `en-US` in a directory named `en-US`.
Similarly, documentation for cultures such as `en-AU`, `en-GB` and `fr-FR` would be in separate directories.
If a directory for the exact culture `en-US` doesn't exist, PSRule will attempt to find the parent culture.
For example, documentation would be read from a directory named `en`.
When naming directories for their culture, use exact case.
This is because some file systems are case-sensitive.
For example on Linux `en-us` would not match.
For example:
- Enterprise.Rules/
- en/
- Metadata.Name.md
- en-US/
- Metadata.Name.md
- fr-FR/
- Metadata.Name.md
- rules/
- NamingStandards.Rule.ps1
- ComplianceStandards.Rule.ps1
- Baseline.Rule.yaml
- Enterprise.Rules.psd1
## More information
- [Enterprise.Rules.psd1](Enterprise.Rules/Enterprise.Rules.psd1) - An example module manifest.