зеркало из https://github.com/microsoft/PSRule.git
Added module packaging docs (#371)
This commit is contained in:
Родитель
6c97b7c5b8
Коммит
4ebb695349
|
@ -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.
|
Загрузка…
Ссылка в новой задаче