From 6bf19434726962c6b08641bd77d0b7b69370616c Mon Sep 17 00:00:00 2001 From: Michael T Lombardi Date: Tue, 1 Jun 2021 09:44:25 -0500 Subject: [PATCH] (GH-64) Add docs for customizing private modules This commit adds initial documentation for Puppetizing PowerShell modules with DSC Resources not found on the public gallery. It also updates the .gitignore to correctly manage about* docs. --- .gitignore | 4 ++-- docs/about_Puppetizing_Custom_Modules.md | 26 ++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 2 deletions(-) create mode 100644 docs/about_Puppetizing_Custom_Modules.md diff --git a/.gitignore b/.gitignore index 6d6c2753..acf21100 100644 --- a/.gitignore +++ b/.gitignore @@ -3,5 +3,5 @@ import .vagrant/ *Results.xml Puppet.Dsc/ -docs/ -!docs/about* +docs/* +!docs/about_* diff --git a/docs/about_Puppetizing_Custom_Modules.md b/docs/about_Puppetizing_Custom_Modules.md new file mode 100644 index 00000000..55c6cf64 --- /dev/null +++ b/docs/about_Puppetizing_Custom_Modules.md @@ -0,0 +1,26 @@ +# Puppetizing Custom Modules + +## about_Puppetizing_Custom_Modules + +# SHORT DESCRIPTION + +Explanation of when & how to use `puppet.dsc` to convert private/internal PowerShell modules into Puppet modules. + +# LONG DESCRIPTION + +Sometimes you may want to puppetize a PowerShell module with DSC Resources which is _not_ published to the [Public PowerShell Gallery](https://www.powershellgallery.com/) - for any reason, but often because the resources include business-specific logic. + +Luckily, `Puppet.Dsc` makes no distinction between PowerShell modules with DSC Resources which are public and private; you just need to tell it _where_ to find the modules to Puppetize. + +The `New-PuppetDscModule` function is able to transparently use any valid PSRepository feed to retrieve PowerShell modules with DSC Resources: + +```powershell +# To puppetize from an alternate PSRepository feed +# Make sure to replace 'MyRepository' with your repository name +New-PuppetDscModule -PowerShellModuleName PowerShellGet -PowerShellModuleVersion 2.2.3 -Repository MyRepository +``` + +If you don't already have a private PSRepository feed, you can [add one](https://docs.microsoft.com/en-us/powershell/scripting/gallery/how-to/working-with-local-psrepositories?view=powershell-7.1) via the Microsoft docs. +You can even [register a PSRepository for a local or shared folder](https://docs.microsoft.com/en-us/powershell/scripting/gallery/how-to/working-with-local-psrepositories?view=powershell-7.1#registering-a-local-repository)! + +Once you have the repository added, you need to remember to specify the `Repository` parameter when calling `New-PuppetDscModule` - otherwise it will default to the [Public PowerShell Gallery](https://www.powershellgallery.com/).