From 21266d4c45cad13165e43737dc42c7f6f4f8d544 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 13 Nov 2023 12:08:34 +0000 Subject: [PATCH] Release prep v2.0.0 --- CHANGELOG.md | 8 + docs/ConvertTo-PuppetResourceApi.md | 111 +++++++++ docs/Export-PuppetModule.md | 111 +++++++++ docs/Get-ForgeModuleInfo.md | 119 +++++++++ docs/Get-PowerShellDscModule.md | 79 ++++++ docs/Get-PuppetizedModuleName.md | 59 +++++ docs/Get-UnpuppetizedDscModuleVersion.md | 180 ++++++++++++++ docs/New-PuppetDscModule.md | 243 +++++++++++++++++++ docs/Publish-NewDscModuleVersion.md | 258 ++++++++++++++++++++ docs/Publish-PuppetModule.md | 274 +++++++++++++++++++++ docs/Update-ForgeDscModule.md | 296 +++++++++++++++++++++++ src/Puppet.Dsc/puppet.dsc.psd1 | 2 +- 12 files changed, 1739 insertions(+), 1 deletion(-) create mode 100644 docs/ConvertTo-PuppetResourceApi.md create mode 100644 docs/Export-PuppetModule.md create mode 100644 docs/Get-ForgeModuleInfo.md create mode 100644 docs/Get-PowerShellDscModule.md create mode 100644 docs/Get-PuppetizedModuleName.md create mode 100644 docs/Get-UnpuppetizedDscModuleVersion.md create mode 100644 docs/New-PuppetDscModule.md create mode 100644 docs/Publish-NewDscModuleVersion.md create mode 100644 docs/Publish-PuppetModule.md create mode 100644 docs/Update-ForgeDscModule.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5d60256c..1a18fd84 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org). +## [2.0.0](https://github.com/puppetlabs/Puppet.Dsc/tree/2.0.0) - 2023-11-13 + +[Full Changelog](https://github.com/puppetlabs/Puppet.Dsc/compare/1.0.6...2.0.0) + +### Changed +- (CAT-1454) - Add Puppet 8/Drop Puppet 6 [#273](https://github.com/puppetlabs/Puppet.Dsc/pull/273) ([jordanbreen28](https://github.com/jordanbreen28)) +- (CAT-1484) - Add ensurable property to resource [#269](https://github.com/puppetlabs/Puppet.Dsc/pull/269) ([jordanbreen28](https://github.com/jordanbreen28)) + ## [1.0.6](https://github.com/puppetlabs/Puppet.Dsc/tree/1.0.6) - 2023-08-25 [Full Changelog](https://github.com/puppetlabs/Puppet.Dsc/compare/1.0.5...1.0.6) diff --git a/docs/ConvertTo-PuppetResourceApi.md b/docs/ConvertTo-PuppetResourceApi.md new file mode 100644 index 00000000..243da3c6 --- /dev/null +++ b/docs/ConvertTo-PuppetResourceApi.md @@ -0,0 +1,111 @@ +--- +external help file: Puppet.Dsc-help.xml +Module Name: puppet.dsc +online version: +schema: 2.0.0 +--- + +# ConvertTo-PuppetResourceApi + +## SYNOPSIS +Collate the information about a DSC resource for building a Puppet resource_api type and provider + +## SYNTAX + +### ByObject (Default) +``` +ConvertTo-PuppetResourceApi [-DscResource ] [] +``` + +### ByProperty +``` +ConvertTo-PuppetResourceApi [-Name ] [-Module ] [] +``` + +## DESCRIPTION +This function takes a DSC resource and returns the representation of that resource for the Puppet +Resource API types and providers as a PowerShell object for further use. + +## EXAMPLES + +### EXAMPLE 1 +``` +Get-DscResource -Name PSRepository | ConvertTo-PuppetResourceApi -OutVariable Foo +``` + +Retrieve the representation of a Puppet Resource API type and provider from a DSC Resource object. + +### EXAMPLE 2 +``` +ConvertTo-PuppetResourceApi -Name PSRepository +``` + +Retrieve the representation of a Puppet Resource API type by searching for a DSC resource object via +Get-DscResource. +Will ONLY find the resource if it is in the PSModulePath. + +## PARAMETERS + +### -DscResource +The DscResourceInfo object to convert; can be passed via the pipeline, normally retrieved +via calling Get-DscResource. + +```yaml +Type: DscResourceInfo[] +Parameter Sets: ByObject +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Name +If not passing a full object, specify the name of the DSC Resource to retrieve and convert. + +```yaml +Type: String[] +Parameter Sets: ByProperty +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Module +If not passing a full object, specify the module name of the the DSC Resource to retrieve and convert. +Can be either a string or a hash containing the keys ModuleName and ModuleVersion. + +```yaml +Type: Object +Parameter Sets: ByProperty +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES +This function currently takes EITHER: + +1. +A DscResource Object, as passed by Get-DSCResource +2. +A combo of name/module to retrieve DSC Resources from + +## RELATED LINKS diff --git a/docs/Export-PuppetModule.md b/docs/Export-PuppetModule.md new file mode 100644 index 00000000..c3ff3af4 --- /dev/null +++ b/docs/Export-PuppetModule.md @@ -0,0 +1,111 @@ +--- +external help file: Puppet.Dsc-help.xml +Module Name: puppet.dsc +online version: +schema: 2.0.0 +--- + +# Export-PuppetModule + +## SYNOPSIS +Build a Puppet module with the PDK + +## SYNTAX + +``` +Export-PuppetModule [-PuppetModuleFolderPath] [[-ExportFolderPath] ] [-Force] [-PassThru] + [] +``` + +## DESCRIPTION +Build a Puppet module with the PDK as a .tar.gz + +## EXAMPLES + +### EXAMPLE 1 +``` +Export-PuppetModule -PuppetModuleFolderPath ./import/powershellget +``` + +This command will invoke the PDK to build the powershellget module in the +specified folder path. + +## PARAMETERS + +### -PuppetModuleFolderPath +The path to the folder where the Puppet module to build exists + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExportFolderPath +The path to the folder for the built module to be placed in. +If not specified, +builds in the pkg folder inside the PuppetModuleFolderPath. +If the specified +ExportFolderPath does not exist, the PDK will create it. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +Specify this switch to force a build of the module even if it already exists + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PassThru +Specify this switch to capture the output of the PDK build command and return it + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None. +## OUTPUTS + +### [Object[]] If the PassThru switch is specified, returns the output from the +### PDK execution, including any error records. +## NOTES + +## RELATED LINKS diff --git a/docs/Get-ForgeModuleInfo.md b/docs/Get-ForgeModuleInfo.md new file mode 100644 index 00000000..77f729ec --- /dev/null +++ b/docs/Get-ForgeModuleInfo.md @@ -0,0 +1,119 @@ +--- +external help file: Puppet.Dsc-help.xml +Module Name: puppet.dsc +online version: +schema: 2.0.0 +--- + +# Get-ForgeModuleInfo + +## SYNOPSIS +Search a Puppet forge for modules with DSC Resources + +## SYNTAX + +### ByNameSpace (Default) +``` +Get-ForgeModuleInfo -ForgeNameSpace [-ForgeSearchUri ] [-PaginationBump ] + [] +``` + +### ByName +``` +Get-ForgeModuleInfo -ForgeNameSpace -Name [-ForgeSearchUri ] [] +``` + +## DESCRIPTION +Search a Puppet forge for modules with DSC Resources, returning their name, +every release of that module, and the module's PowerShell metadata. + +## EXAMPLES + +### EXAMPLE 1 +``` +Get-ForgeModuleInfo -Name powershellget +``` + +Search the DSC namespace of the Puppet Forge for the powershellget module, +returning it (if it exists) with the list of releases and the metadata for +the PowerShell module it was built from. + +## PARAMETERS + +### -ForgeNameSpace +The namespace on the Forge to search for modules. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name +The name of the module to search for on the Forge. +If left unspecified, will +search the entire namespace for modules. + +```yaml +Type: String[] +Parameter Sets: ByName +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForgeSearchUri +The URI to the forge api for retrieving modules; by default, the public +Puppet forge (v3). + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: Https://forgeapi.puppet.com/v3/modules +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PaginationBump +If searching a namespace for modules, indicates the number of modules to return +in a single result set, continuing to search until no more modules are discovered. + +```yaml +Type: Int32 +Parameter Sets: ByNameSpace +Aliases: + +Required: False +Position: Named +Default value: 5 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None. +## OUTPUTS + +### [PSCustomObject[]] One or more objects with the name, releases, and the +### PowerShellModuleInfo properties. +## NOTES + +## RELATED LINKS diff --git a/docs/Get-PowerShellDscModule.md b/docs/Get-PowerShellDscModule.md new file mode 100644 index 00000000..90c24e23 --- /dev/null +++ b/docs/Get-PowerShellDscModule.md @@ -0,0 +1,79 @@ +--- +external help file: Puppet.Dsc-help.xml +Module Name: puppet.dsc +online version: +schema: 2.0.0 +--- + +# Get-PowerShellDscModule + +## SYNOPSIS +Retrieve one or more PowerShell modules with DSC Resources + +## SYNTAX + +``` +Get-PowerShellDscModule [[-Name] ] [[-Repository] ] [] +``` + +## DESCRIPTION +Retrieve one or more PowerShell modules with DSC Resources from a PowerShell repository, +returning their name and all released versions. + +## EXAMPLES + +### EXAMPLE 1 +``` +Get-PowerShellDscModule +``` + +Searches the PowerShell Gallery for every module with DSC Resources and returns every +released version of those modules. + +## PARAMETERS + +### -Name +The name of one or more modules to search for. +If not specified, returns all modules +with DSC Resources. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Repository +The PowerShell repository to search; defaults to the PowerShell Gallery + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: PSGallery +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None. +## OUTPUTS + +### [PSCustomObject[]] An object with the name of each discovered module and a Releases +### property for every version released to the repository. +## NOTES + +## RELATED LINKS diff --git a/docs/Get-PuppetizedModuleName.md b/docs/Get-PuppetizedModuleName.md new file mode 100644 index 00000000..a51d9dbc --- /dev/null +++ b/docs/Get-PuppetizedModuleName.md @@ -0,0 +1,59 @@ +--- +external help file: Puppet.Dsc-help.xml +Module Name: puppet.dsc +online version: +schema: 2.0.0 +--- + +# Get-PuppetizedModuleName + +## SYNOPSIS +Get a valid puppet module name from a PowerShell Module name + +## SYNTAX + +``` +Get-PuppetizedModuleName [[-Name] ] [] +``` + +## DESCRIPTION +Get a valid puppet module name from a PowerShell Module name + +## EXAMPLES + +### EXAMPLE 1 +``` +Get-PuppetizedModuleName -Name Azure.Something.Or.Other +``` + +This will return 'azure_something_or_other', which is a valid +Puppet module name. + +## PARAMETERS + +### -Name +The name of the PowerShell module you want to puppetize + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +### System.String +## NOTES + +## RELATED LINKS diff --git a/docs/Get-UnpuppetizedDscModuleVersion.md b/docs/Get-UnpuppetizedDscModuleVersion.md new file mode 100644 index 00000000..8f5974df --- /dev/null +++ b/docs/Get-UnpuppetizedDscModuleVersion.md @@ -0,0 +1,180 @@ +--- +external help file: Puppet.Dsc-help.xml +Module Name: puppet.dsc +online version: +schema: 2.0.0 +--- + +# Get-UnpuppetizedDscModuleVersion + +## SYNOPSIS +Search for versions of a PowerShell module not released to a Puppet feed + +## SYNTAX + +``` +Get-UnpuppetizedDscModuleVersion [-ForgeNameSpace] [[-Name] ] [[-MinimumVersion] ] + [-OnlyNewer] [[-Repository] ] [[-ForgeSearchUri] ] [] +``` + +## DESCRIPTION +Search a PowerShell repository and Puppet forge feed feed to discover any +versions of one or modules which have been released to the PowerShell +repository but not yet Puppetized and published to the Puppet Forge. +If +a module has not been Puppetized at all, returns *all* discovered versions +of that module from the PowerShell repository. + +## EXAMPLES + +### EXAMPLE 1 +``` +Get-UnpuppetizedDscModuleVersion -Name foo +``` + +This will look for all versions of the foo module published to the +PowerShell Gallery but not to the Puppet Forge in the 'dsc' namespace, +including versions older than any currently Puppetized. + +### EXAMPLE 2 +``` +Get-UnpuppetizedDscModuleVersion -Name foo -MinimumVersion 1.0 +``` + +This will look for all versions of the foo module published to the +PowerShell Gallery but not to the Puppet Forge in the 'dsc' namespace, +so long as they are newer than 1.0.0.0. + +### EXAMPLE 3 +``` +Get-UnpuppetizedDscModuleVersion -Name foo -OnlyNewer +``` + +This will look for all versions of the foo module published to the +PowerShell Gallery but not to the Puppet Forge in the 'dsc' namespace, +including only those versions newer than the latest published to the +Puppet Forge. + +### EXAMPLE 4 +``` +Get-UnpuppetizedDscModuleVersion -Name foo -Repository Internal -ForgeNameSpace my_company +``` + +This will look for all versions of the foo module published to the +'Internal' PowerShell repository but not to the Puppet Forge in the +'my_company' namespace, including versions older than any currently Puppetized. + +## PARAMETERS + +### -ForgeNameSpace +The namespace on the Forge to search for modules + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name +The name of one or more PowerShell modules to search for. +If no name is +specified, will compare all PowerShell modules with DSC Resources in the +specified Repository to the Forge to find unpuppetized module versions. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MinimumVersion +The minimum version to return; any released versions equal to or newer +than this which have been published to the PowerShell repository but not +the Puppet Forge will be returned. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OnlyNewer +Only return versions of the PowerShell module on the PowerShell repository +which are newer than the highest version release of the module in the +Puppet Forge. +Use to prevent building legacy versions if not needed. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Repository +The PowerShell repository to search; defaults to the PowerShell Gallery + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 4 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForgeSearchUri +The Puppet Forge API URI to search; defaults to the public Puppet Forge + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 5 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None. +## OUTPUTS + +### [PSCustomObject] Returns an object with the Name property for the name of +### the module and Versions as an array of the module versions which have not +### been Puppetized and published to the Puppet Forge yet. +## NOTES + +## RELATED LINKS diff --git a/docs/New-PuppetDscModule.md b/docs/New-PuppetDscModule.md new file mode 100644 index 00000000..0ab8da12 --- /dev/null +++ b/docs/New-PuppetDscModule.md @@ -0,0 +1,243 @@ +--- +external help file: Puppet.Dsc-help.xml +Module Name: puppet.dsc +online version: +schema: 2.0.0 +--- + +# New-PuppetDscModule + +## SYNOPSIS +Puppetize a PowerShell module with DSC resources + +## SYNTAX + +``` +New-PuppetDscModule [-PowerShellModuleName] [[-PowerShellModuleVersion] ] + [[-PuppetModuleName] ] [[-PuppetModuleAuthor] ] [[-PuppetModuleFixture] ] + [[-OutputDirectory] ] [-AllowPrerelease] [-PassThru] [[-Repository] ] + [[-PDKTemplateRef] ] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +This function builds a Puppet Module which wraps and calls PowerShell DSC resources +via the Puppet resource_api. +This module: + +- Includes a base resource_api provider which relies on ruby-pwsh and knows how to invoke DSC resources +- Includes a type for each DSC resource, pulling in the appropriate metadata including help, default value + and mandatory status, as well as whether or not it includes an embedded mof. +- Allows for the tracking of changes on a property-by-property basis while using DSC and Puppet together + +## EXAMPLES + +### EXAMPLE 1 +``` +New-PuppetDscModule -PowerShellModuleName PowerShellGet -PowerShellModuleVersion 2.2.3 -Repository PSGallery +``` + +This function will create a new Puppet module, powershellget, which vendors and puppetizes the PowerShellGet +PowerShell module at version 2.2.3 and its dependencies, exposing the DSC resources as Puppet resources. + +## PARAMETERS + +### -PowerShellModuleName +The name of the PowerShell module on the gallery which has DSC resources you want to Puppetize + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PowerShellModuleVersion +The version of the PowerShell module on the gallery which has DSC resources you want to Puppetize. +If left blank, will default to latest available. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PuppetModuleName +The name of the Puppet module for the wrapper; if not specified, will default to the downcased name of +the module to adhere to Puppet naming conventions. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PuppetModuleAuthor +The name of the Puppet module author; if not specified, will default to your PDK configuration's author. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 4 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PuppetModuleFixture +The fixture reference for the puppetlabs-pwshlib dependency, defined as a hash with the mandatory keys +\`Section\` ('forge_modules' or 'repositories') and \`Repo\` (the name of the module on the forge, like +'puppetlabs/pwshlib', or the git repo url) and the optional keys \`Ref\` (the version on the forge or the +git ref - tag or commit sha) and \`Branch\` (source code repository only, identifying the branch to be +pulled from). + +Defaults to retrieving the latest released version of pwshlib from the forge. + +```yaml +Type: Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: 5 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OutputDirectory +The folder in which to build the Puppet module. +Defaults to a folder called import in the current location. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 6 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -AllowPrerelease +Allows you to Puppetize a module marked as a prerelease. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PassThru +If specified, the function returns the path to the root folder of the Puppetized module on the filesystem. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Repository +Specifies a non-default PSRepository. +If left blank, will default to PSGallery. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 7 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PDKTemplateRef +Specifies the template git branch or tag to use when creating new moudles or classes. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 8 +Default value: 3.0.0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the function runs. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts for confirmation before creating the Puppet module + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/docs/Publish-NewDscModuleVersion.md b/docs/Publish-NewDscModuleVersion.md new file mode 100644 index 00000000..af2afed1 --- /dev/null +++ b/docs/Publish-NewDscModuleVersion.md @@ -0,0 +1,258 @@ +--- +external help file: Puppet.Dsc-help.xml +Module Name: puppet.dsc +online version: +schema: 2.0.0 +--- + +# Publish-NewDscModuleVersion + +## SYNOPSIS +Build and publish Puppetized DSC module versions not yet on the Forge + +## SYNTAX + +``` +Publish-NewDscModuleVersion [-ForgeNameSpace] [[-Name] ] [[-MinimumVersion] ] + [-OnlyNewer] [[-MaxBuildCount] ] [[-Repository] ] [[-ForgeApiUri] ] + [[-ForgeToken] ] [[-BuildFolderPath] ] [[-PackageFolderPath] ] [] +``` + +## DESCRIPTION +Build and publish Puppetized DSC module versions not yet on the Forge by +searching for Puppetizable PowerShell modules with DSC Resources in a +repository and then building and published each desired version. + +## EXAMPLES + +### EXAMPLE 1 +``` +Publish-NewDscModuleVersion -ForgeNameSpace foo +``` + +This will search the PowerShell Gallery for any and all modules with DSC +Resources and their releases, comparing this information to the Puppet +Forge; any version of any discovered module *not* published to the 'foo' +namespace on the Forge will be puppetized and published; for any module +which is not already on the Forge in this namespace, all discovered +versions will be Puppetized and published. + +### EXAMPLE 2 +``` +Publish-NewDscModuleVersion -ForgeNameSpace foo -Name 'bar', 'baz' +``` + +This will search the PowerShell Gallery for the bar and baz modules; any +version of these modules *not* published to the 'foo' namespace on the +Forge will be puppetized and published; if either module is not already +on the Forge in this namespace, all discovered versions for that module +will be Puppetized and published. + +### EXAMPLE 3 +``` +Publish-NewDscModuleVersion -ForgeNameSpace foo -OnlyNewer +``` + +This will search the PowerShell Gallery for any and all modules with DSC +Resources and their releases, comparing this information to the Puppet +Forge; any version of any discovered module *not* published to the 'foo' +namespace on the Forge *and* whose version is higher than the highest +version published to the Forge will be puppetized and published; for +any module which is not already on the Forge in this namespace, all +discovered versions will be Puppetized and published. + +### EXAMPLE 4 +``` +Publish-NewDscModuleVersion -ForgeNameSpace foo -MaxBuildCount 10 +``` + +This will search the PowerShell Gallery for any and all modules with DSC +Resources and their releases, comparing this information to the Puppet +Forge; any version of any discovered module *not* published to the 'foo' +namespace on the Forge will be puppetized and published, up to 10 total +releases; if there are more unreleased versions than the MaxBuildCount +specification of 10, they will not be built in this call. + +## PARAMETERS + +### -ForgeNameSpace +The namespace on the Forge to search for modules in and publish to. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name +The name of one or more PowerShell modules to search for new versions to +puppetize. +If no name is specified, will compare all PowerShell modules +with DSC Resources in the specified Repository to the Forge to find +unpuppetized module versions. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MinimumVersion +The minimum version to puppetize; any released versions equal to or newer +than this which have been published to the PowerShell repository but not +the Puppet Forge will be puppetized and published. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OnlyNewer +Only puppetize versions of the PowerShell module on the PowerShell repository +which are newer than the highest version release of the module in the +Puppet Forge. +Use to prevent building legacy versions if not needed. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MaxBuildCount +Only puppetize up to this many releases *total* across modules and versions. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: 4 +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Repository +The PowerShell repository to search; defaults to the PowerShell Gallery + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 5 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForgeApiUri +The Puppet Forge API URI to search and publish to; defaults to the public Puppet Forge + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 6 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForgeToken +The Forge API Token for the target account. +If not specified, will use +the FORGE_TOKEN environment variable. +Must pass a token either directly +or via the environment variable to successfully publish to the Forge. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 7 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -BuildFolderPath +The path, relative or absolute, to the folder in which to Puppetize the +module. +If not specified, will do so in a folder called import in the +current location. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 8 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PackageFolderPath +The path, relative or absolute, to the folder in which to build the +module. +If not specified, will build in the pkg folder inside the +BuildFolderPath. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 9 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None. +## OUTPUTS + +### None. +## NOTES + +## RELATED LINKS diff --git a/docs/Publish-PuppetModule.md b/docs/Publish-PuppetModule.md new file mode 100644 index 00000000..34d52e33 --- /dev/null +++ b/docs/Publish-PuppetModule.md @@ -0,0 +1,274 @@ +--- +external help file: Puppet.Dsc-help.xml +Module Name: puppet.dsc +online version: +schema: 2.0.0 +--- + +# Publish-PuppetModule + +## SYNOPSIS +Build and Publish Puppet Module + +## SYNTAX + +### Build (Default) +``` +Publish-PuppetModule -PuppetModuleFolderPath [-ExportFolderPath ] [-ForgeToken ] + [-ForgeUploadUrl ] [-Build] [-Publish] [-Force] [-WhatIf] [-Confirm] [] +``` + +### Publish +``` +Publish-PuppetModule -PuppetModuleFolderPath [-PackagedModulePath ] [-ForgeToken ] + [-ForgeUploadUrl ] [-Publish] [-Force] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +Generate package for the module and publish to the forge. + +## EXAMPLES + +### EXAMPLE 1 +``` +Publish-PuppetModule -Build -Publish -PuppetModuleFolderPath ./foo +``` + +This will attempt to build and then publish the Puppet module in ./foo +leveraging the forge token stored in the FORGE_TOKEN environment variable + +### EXAMPLE 2 +``` +Publish-PuppetModule -Build -PuppetModuleFolderPath ./foo +``` + +This will call Export-PuppetModule to build the module in ./foo + +### EXAMPLE 3 +``` +Publish-PuppetModule -Publish -PuppetModuleFolderPath ./foo +``` + +This will use the PDK to attempt to publish the version-matching packaged +Puppet module in ./foo/pkg leveraging the forge token stored in the +FORGE_TOKEN environment variable + +### EXAMPLE 4 +``` +Publish-PuppetModule -Publish -PuppetModuleFolderPath ./foo -Publish -PackagedModulePath ../pkg/myuser-foo-1.2.3-0-0.tar.gz +``` + +This will use the PDK to attempt to publish the specified packaged module, +leveraging the forge token stored in the FORGE_TOKEN environment variable + +### EXAMPLE 5 +``` +Publish-PuppetModule -Build -Publish -PuppetModuleFolderPath ./foo -ExportFolderPath C:\dsc +``` + +This will attempt to build the Puppet module found in ./foo to the C:\dsc +folder and then publish the built module from C:\dsc, leveraging the forge +token stored in the FORGE_TOKEN environment variable + +### EXAMPLE 6 +``` +Publish-PuppetModule -Build -Publish -PuppetModuleFolderPath ./foo -Force +``` + +This will attempt to build and then publish the Puppet module in ./foo +leveraging the forge token stored in the FORGE_TOKEN environment variable +and ignoring all prompts and warnings, rebuilding the module if needed. + +### EXAMPLE 7 +``` +Publish-PuppetModule -Publish -PuppetModuleFolderPath ./foo -ForgeToken FooBarBaz +``` + +This will use the PDK to attempt to publish the version-matching packaged +Puppet module in ./foo/pkg passing 'FooBarBaz' as the token for +authenticating to the forge. + +## PARAMETERS + +### -PuppetModuleFolderPath +The path, relative or absolute, to the Puppet module's root folder. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExportFolderPath +The path, relative or absolute, to the folder in which to build the +module. +If not specified, will build in the pkg folder inside the +PuppetModuleFolderPath + +```yaml +Type: String +Parameter Sets: Build +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PackagedModulePath +The path, relative or absolute, to an already built Puppet module to +publish to the forge. + +```yaml +Type: String +Parameter Sets: Publish +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForgeToken +The Forge API Token for the target account. +If not specified, will use +the FORGE_TOKEN environment variable. +Must pass a token either directly +or via the environment variable to successfully publish to the Forge. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: $env:FORGE_TOKEN +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForgeUploadUrl +The URL for the Forge Upload API. +Defaults to the public forge. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Build +Flag whether to build the package. + +```yaml +Type: SwitchParameter +Parameter Sets: Build +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Publish +Flag whether to publish the package. + +```yaml +Type: SwitchParameter +Parameter Sets: Build +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +```yaml +Type: SwitchParameter +Parameter Sets: Publish +Aliases: + +Required: True +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +Flag whether to skip all prompts when building/publishing the module. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS diff --git a/docs/Update-ForgeDscModule.md b/docs/Update-ForgeDscModule.md new file mode 100644 index 00000000..acebe3ef --- /dev/null +++ b/docs/Update-ForgeDscModule.md @@ -0,0 +1,296 @@ +--- +external help file: Puppet.Dsc-help.xml +Module Name: puppet.dsc +online version: +schema: 2.0.0 +--- + +# Update-ForgeDscModule + +## SYNOPSIS +Rebuild and publish Puppetized DSC modules + +## SYNTAX + +### ByNameSpace (Default) +``` +Update-ForgeDscModule -ForgeNameSpace [-ForgeApiUri ] [-ForgeToken ] + [-BuildFolderPath ] [-PackageFolderPath ] [-LatestMajorVersionOnly] + [-MaximumVersionCountToRebuild ] [-SleepAfterFailure ] [-WhatIf] [-Confirm] [] +``` + +### ByNameAndVersion +``` +Update-ForgeDscModule -ForgeNameSpace -Name -Version [-ForgeApiUri ] + [-ForgeToken ] [-BuildFolderPath ] [-PackageFolderPath ] [-WhatIf] [-Confirm] + [] +``` + +### ByName +``` +Update-ForgeDscModule -ForgeNameSpace -Name [-ForgeApiUri ] [-ForgeToken ] + [-BuildFolderPath ] [-PackageFolderPath ] [-LatestMajorVersionOnly] + [-MaximumVersionCountToRebuild ] [-SleepAfterFailure ] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +Rebuild and publish Puppetized DSC modules, bumping their Puppet build version by one. + +## EXAMPLES + +### EXAMPLE 1 +``` +Update-ForgeDscModule -ForgeNameSpace 'foo' +``` + +This will search for every Puppetized DSC module in the 'foo' namespace +of the public Puppet Forge and attempt to rebuild and publish (with an +incremented Puppet build version) each release. + +### EXAMPLE 2 +``` +Update-ForgeDscModule -ForgeNameSpace 'foo' -Name 'bar', 'baz' +``` + +This will search for the 'bar' and 'baz' Puppetized DSC modules in the +'foo' namespace of the public Puppet Forge and attempt to rebuild and +publish (with an incremented Puppet build version) each release of those +modules. + +### EXAMPLE 3 +``` +Update-ForgeDscModule -ForgeNameSpace 'foo' LatestMajorVersionOnly +``` + +This will search for every Puppetized DSC module in the 'foo' namespace +of the public Puppet Forge and attempt to rebuild and publish (with an +incremented Puppet build version) only releases from the latest major +version of each module; so if a module was released at 2.1.0.0, 2.0.0.0, +1.2.0.0, 1.1.0.0, and 1.0.0.0, only 2.1.0.0 and 2.0.0.0 would be rebuilt +and published. + +### EXAMPLE 4 +``` +Update-ForgeDscModule -ForgeNameSpace 'foo' MaximumVersionCountToRebuild 3 +``` + +This will search for every Puppetized DSC module in the 'foo' namespace +of the public Puppet Forge and attempt to rebuild and publish (with an +incremented Puppet build version) only releases from the latest major +version of each module; so if a module was released at 2.1.0.0, 2.0.0.0, +1.2.0.0, 1.1.0.0, and 1.0.0.0, only 2.1.0.0, 2.0.0.0, and 1.2.0.0 would be +rebuilt and published. + +## PARAMETERS + +### -ForgeNameSpace +The namespace on the Forge to search for modules + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name +The name of one or more Puppetized DSC modules to update. +If no name is +specified, will update all Puppetized DSC modules in the specified +Forge namespace. + +```yaml +Type: String[] +Parameter Sets: ByNameAndVersion, ByName +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Version +The specific version to update; if specified, can only be used with a +single Name; rebuild one version of one module and publish it. + +```yaml +Type: Version +Parameter Sets: ByNameAndVersion +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForgeApiUri +The Puppet Forge API URI to search and publish to; defaults to the public Puppet Forge + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForgeToken +The Forge API Token for the target account. +If not specified, will use +the FORGE_TOKEN environment variable. +Must pass a token either directly +or via the environment variable to successfully publish to the Forge. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -BuildFolderPath +The path, relative or absolute, to the folder in which to Puppetize the +module. +If not specified, will do so in a folder called import in the +current location. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PackageFolderPath +The path, relative or absolute, to the folder in which to build the +module. +If not specified, will build in the pkg folder inside the +BuildFolderPath. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LatestMajorVersionOnly +If specified, will only rebuild releases from the latest major version +for each module being updated. + +```yaml +Type: SwitchParameter +Parameter Sets: ByNameSpace, ByName +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MaximumVersionCountToRebuild +If specified, will only rebuild and publish up to this many releases. + +```yaml +Type: Int32 +Parameter Sets: ByNameSpace, ByName +Aliases: + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SleepAfterFailure +If specified, will wait the specified number of seconds after a failure +and before starting the next update attempt. +Useful in local debugging +and execution. + +```yaml +Type: Int32 +Parameter Sets: ByNameSpace, ByName +Aliases: + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None. +## OUTPUTS + +### None. +## NOTES + +## RELATED LINKS diff --git a/src/Puppet.Dsc/puppet.dsc.psd1 b/src/Puppet.Dsc/puppet.dsc.psd1 index fab53991..16cd3539 100644 --- a/src/Puppet.Dsc/puppet.dsc.psd1 +++ b/src/Puppet.Dsc/puppet.dsc.psd1 @@ -3,7 +3,7 @@ RootModule = 'Puppet.Dsc.psm1' # Version number of this module. - ModuleVersion = '1.0.6' + ModuleVersion = '2.0.0' # ID used to uniquely identify this module GUID = '37c6b5c1-2614-4ff5-bb9f-a610b7da3086'