Merge pull request #164 from michaeltlombardi/gh-150/main/known-limit…

…ation-module-install

(GH-150) Add known installation limitations to readme

CHANGELOG.md

@@ -12,12 +12,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ability to set generated modules fixtures to something other than the latest released version of `puppetlabs-pwshlib` on the Forge ([#93](https://github.com/puppetlabs/Puppet.Dsc/issues/93))
 - A check to `New-PuppetDscModule` which validates that PSRemoting is enabled and errors clearly if not in order to prevent unexpected execution failures later in the process ([#133](https://github.com/puppetlabs/Puppet.Dsc/issues/133))
 - Long file path support information to the requirements section of autogenerated READMEs ([#149](https://github.com/puppetlabs/Puppet.Dsc/issues/149))
+- Notes on installation limitations to generated README files to clarify minitar limitations for `r10k` and serverless Puppet users ([#150](https://github.com/puppetlabs/Puppet.Dsc/issues/150))
 
 ### Fixed
 
 - Ensure that the auto-generated readme of a Puppetized module contains both the PowerShell and Puppet module names ([#153](https://github.com/puppetlabs/Puppet.Dsc/issues/153))
 - Make all `Update-PuppetModuleReadme` parameters except `PuppetModuleName` mandatory and do not accept null or empty values ([#153](https://github.com/puppetlabs/Puppet.Dsc/issues/153))
-- Make the  `PowerShellModuleName` and `PuppetModuleName` parameters in `Get-Readmecontent` mandatory and do not accept null or empty values for any parameters ([#153](https://github.com/puppetlabs/Puppet.Dsc/issues/153))
+- Make the `PowerShellModuleName` and `PuppetModuleName` parameters in `Get-Readmecontent` mandatory and do not accept null or empty values for any parameters ([#153](https://github.com/puppetlabs/Puppet.Dsc/issues/153))
 
 ## [0.5.0] - 2021-2-10
 

src/internal/functions/Get-ReadmeContent.ps1

@@ -52,6 +52,8 @@ function Get-ReadmeContent {
     $NarrativeDocumentation       = 'https://puppetlabs.github.io/iac/news/roadmap/2020/03/30/dsc-announcement.html'
     $TroubleshootingDocumentation = 'https://github.com/puppetlabs/Puppet.Dsc#troubleshooting'
     $MicrosoftLongPathSupportDocs = 'https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell#enable-long-paths-in-windows-10-version-1607-and-later'
+    $PuppetModuleInstallIssue     = 'https://tickets.puppetlabs.com/browse/PUP-10924'
+    $r10kInstallationIssue        = 'https://github.com/puppetlabs/r10k/issues/1117'
   }
 
   Process {
@@ -234,6 +236,27 @@ For specific information on troubleshooting a generated module, check the [troub
 
 Currently, because of the way Puppet caches files on agents, use of the legacy [``puppetlabs-dsc``]($LegacyDscForgePage) module is **not** compatible with this or any auto-generated DSC module.
 Inclusion of both will lead to pluginsync conflicts.
+
+### Module Installation
+
+If you're using this module with Puppet Enterprise and Code Manager, everything should "just work" - no errors or issues acquiring and deploying this or any Puppetized DSC module to nodes.
+
+Unfortunately, due a bug in minitar which prevents it from unpacking archives with long file paths, both [``r10k``]($r10kInstallationIssue) and [serverless Puppet (via ``puppet module install``)]($PuppetModuleInstallIssue) methods of installing modules with long path names will fail.
+In short, minitar is unable to unpack modules that contain long file paths (though it can create them).
+
+As a workaround, you can retrieve DSC modules from the forge via PowerShell and 7zip:
+
+``````powershell
+`$ModuleAuthor = 'dsc'
+`$ModuleName = 'xremotedesktopsessionhost'
+`$ModuleVersion = '2.0.0-0-1'
+`$ArchiveFileName = "`$ModuleAuthor-`$ModuleName-`$ModuleVersion.tar.gz"
+`$DownloadUri = "https://forge.puppet.com/v3/files/`$ArchiveFileName"
+# Download the module tar.gz to the current directory
+Invoke-WebRequest -Uri `$DownloadUri -OutFile ./`$ArchiveFileName
+# Use 7zip to extract the module to the current directory
+& 7z x `$ArchiveFileName -so | & 7z x -aoa -si -ttar
+``````
 "@
   }