Upgrading PDK
Update to the latest version of PDK to get new features, improvements, and bug fixes.
Upgrade PDK using the same method you used to originally install it. See the PDK installation instructions for your platform for details. Then, update your modules to integrate any module template changes.
Note also that if you have added certificates for self-hosted git repositories to the pdk's cert.pem
(/opt/puppetlabs/pdk/ssl/cert.pem
on linux or C:\Program Files\Puppet Labs\DevelopmentKit\ssl\cert.pem
on windows), then you'll need to re-append these certificates after the pdk upgrade. For more information see the known issue Upgrading the pdk over-writes the pdk's cert.pem
.
Upgrading to PDK 3.0.0
Clear the local PDK cache
When PDK encounters a module with non standard dependencies (added by you or the module author), it will cache gems in your user profile.
On Linux systems the cache can be found in ~/.pdk/cache
and on Windows systems it can be
found in $ENV:USERPROFILE\AppData\Local\PDK\cache
.
Sometimes gems installed in the cache by older version of PDK can cause conflicts. For that reason we recommend clearing the cache before you install PDK 3.0.0.
On Linux/MacOS
rm -rf ~/.pdk/cache
On Windows
Remove-Item -Path $ENV:USERPROFILE\AppData\Local\PDK\cache -Recurse -Force
Remove older versions of PDK (optional)
To be extra sure that you will have a smooth upgrade, you can remove your existing PDK installation.
Given that PDK can be installed through a variety of different methods, please consult the documentation of the package provider for uninstallation steps.
Remove the legacy PowerShell module (Windows only)
Versions of PDK prior to 3.0.0 used a PowerShell module to execute the application. This has now been removed as we have transitioned to using a batch file as the entry point.
To avoid conflicts when running PDK you should ensure that the PowerShell module has been removed. Additionally, if you will need to close and restart any open PowerShell sessions.
If it hasn't, it can easily be removed with a few simple steps:
Check if your new install still references the module
From a new PowerShell session, run the following command:
Get-Command -name PDK
Check that the module has been removed from the $MODULEPATH
From a new PowerShell session run the following command:
Get-ChildItem -Path 'C:\Program Files\WindowsPowerShell\Modules\'
If the PuppetDevelopmentKit
module is listed in the output, it can safely be removed.
Update your modules
PDK 3.0.0 removes support for Puppet 6 and Ruby 2.5.9. Before upgrading you should ensure that your modules are compatible with later Puppet and Ruby releases.
Here are the versions of Puppet and Ruby that are included versions in PDK 3.0.0:
Puppet 8 and Ruby 3.2.2
Puppet 7 and Ruby 2.7.8
Once you are satisfied that your modules will support the versions listed above, you should ensure that your modules also have the changes from the latest PDK templates.
To do this, simply run pdk update
inside a module and follow the prompts.
Troubleshooting issues after upgrading
racc
errors with Ruby 2.7.8 and PDK 3.0.0
You may encounter the following error after upgrading to PDK 3.0.0
bolt was resolved to 3.23.1, which depends on
r10k was resolved to 3.15.4, which depends on
gettext-setup was resolved to 1.1.0, which depends on
gettext was resolved to 3.4.4, which depends on
racc
This happens because newer versions of racc are native gems and therefore require some compilation on installation.
At this time, PDK cannot support all Gems with native extensions.
Resolution
To resolve the issue you can either:
Run
pdk update
.Manually add the following requirement to your
.sync.yml
and runpdk update
.
optional:
":development":
- gem: racc
version: '~> 1.4.0'
condition: if Gem::Requirement.create(['>= 2.7.0', '< 3.0.0']).satisfied_by?(Gem::Version.new(RUBY_VERSION.dup))
github_changelog_enerator
errors with Ruby 2.7.8 and PDK 3.0.0
You may encounter the following error after upgrading to PDK 3.0.0
github_changelog_generator was resolved to 1.16.4, which depends on
async-http-faraday was resolved to 0.12.0, which depends on
async-http was resolved to 0.60.2, which depends on
async-io was resolved to 1.35.0, which depends on
async was resolved to 2.6.2, which depends on
io-event
Resolution
To resolve this issue you can either:
Remove github_changelog_generator from your
.sync.yml
and use another solution for changelog generation.Set the version requirement to 1.15.2 in your
sync.yml
.
After completing the step of your choice, you will need to run pdk update
to ensure that your
Gemfile is updated accordingly.