The document outlines the upgrade process from Puppet Enterprise 3.8 to Puppet 4, emphasizing the benefits of the new features and language improvements. It provides a step-by-step guide for preparing and executing the upgrade, including the use of a preview box to identify migration issues and validate code compatibility. Key commands, workflow steps, and potential errors during the transition are also detailed to facilitate a smooth upgrade experience.

1. Getting to the Latest Puppet
1
Elizabeth Wittig Plumb
Senior Technical Account Manager
Nate McCurdy
Senior Professional Services Engineer

2. 2
The Breakdown
Why should I
upgrade?
What do I need?
Anything else I
should know?Walk me through this
– what do I do?

3. 3
Why Should I upgrade?

4. 4
Language
● Iteration!
● Type system
○ Class parameter validation
○ Future proof for additional
awesomeness
● Cleaner Puppet code
○ No more reliance on stdlib
functions
Other
● All-in-one agent packaging
● New features in Puppet
Enterprise
● Stability and scalability
… because Puppet 4 is AWESOME

5. Puppet Enterprise
3.8 is end-of-life
December 31
5

6. 6
Ch-Ch-Ch-Ch-Changes
Code Changes
We’ve got a new
compiler & new
language features
Directory Changes
The all-in-one agent
means we’ve moved
some things around
Classification
Changes
Do you use the
import( ) function?
Console Changes
Whoa! Look at all
those node groups!
https://docs.puppet.com/puppet/latest/reference/lang_updating_manifests.html

7. 7
in place upgrade < migration

8. 8
What do I need?

9. Preview Box, where you’ll make sure the
code is ready for the future
Puppet Enterprise latest, your agents
will aspire to be here
9
So here’s what you’ve gotta do:
Preview Box:
• Puppet Enterprise 3.8 Master
• Catalog Preview module installed
• r10k (or a copy of your code)
• parser = future
Puppet Enterprise
2016.4 Master
Puppet Agents

10. Fast Feedback Loop Doesn’t impact work
the agent is doing
Compare your catalogs in
Puppet 3 vs 4
Why guess?
A 3.8 master with the catalog preview module
https://forge.puppet.com/puppetlabs/catalog_preview
10
What’s a preview box?

11. 11
Catalog Preview identifies 2 types of issues
~$ puppet preview
--baseline-environment production
--preview-environment future_production
--migrate 3.8/4.0
--nodes nodes.txt
--view overview
Migration Issues
Differences
(conflicts)

12. 12
[root@pe-386-master ~]# /opt/puppet/bin/puppet preview
--baseline-environment production --preview-environment future_production
--migrate 3.8/4.0 --nodes /vagrant/nodes.txt --view overview
Stats
Total number of nodes: 10, 100.0%
Conflicting..........: 7, 70.0%
Compliant............: 0, 0.0%
Equal................: 0, 0.0%
Baseline Errors (by manifest)
Nodes..: agiledbtest2.example.com, monprod1.example.com
Issues.:
'Duplicate declaration: File[u01] is already declared in file
/etc/puppetlabs/puppet/environments/production/site/example/manifests/orac
le.pp:351; cannot redeclare (…snip…)
Preview Errors (by manifest)
/etc/puppetlabs/puppet/environments/future_production/site/examp
le/manifests/service-account.pp
Nodes..: pocdbtest1.example.com
Issues.:
ILLEGAL_DEFINTION_NAME: 'Unacceptable name. The name
'example::service-account' is unacceptable as the name of a Host Class
Definition' at line 1, column 1
Preview Errors (by issue)
ILLEGAL_DEFINTION_NAME (1)
/etc/puppetlabs/puppet/environments/future_production/site/examp
le/manifests/service-account.pp:1:1
Preview Warnings (by issue)
MIGRATE4_AMBIGUOUS_INTEGER (77)
/etc/puppetlabs/puppet/environments/future_production/manifests/compliance
.pp:90:15
MIGRATE4_EMPTY_STRING_TRUE (21)
/etc/puppetlabs/puppet/environments/future_production/site/example/manifes
ts/init.pp:[16:6,21:6,26:6]
Top ten nodes with most issues
node name errors warnings diffs
--------------------------- -------- -------- --------
agiledbtest2.example.com 1 0 0
monprod1.example.com 1 0 0
pocdbtest1.example.com 1 0 0
obiaappstage2.example.com 0 1 71
obiaapptest1.example.com 0 1 71
Summary
Diff
Overview

13. https://github.com/puppetlabs/prosvc-preview_report 13

14. Common Migration Warnings
14
MIGRATE4_UC_BAREWORD_IS_TYPE
$pkg_name = $::osfamily ? {
Redhat => ‘httpd’,
Debian => ‘apache2’,
}
MIGRATE4_EQUALITY_TYPE_MISMATCH
'1' == 1 # 4x. false, 3x. true
'1' <= 1 # 4x. error, 3x. true
MIGRATE4_REVIEW_IN_EXPRESSION
$foo = undef
if $foo in [ ‘one’, ‘two’, ‘blue’ ]

15. MIGRATE4_EMPTY_STRING_TRUE
15

16. Differences: This could get messy
--excludes
</path/to/excludes.json>
--[no-]diff-array-value
Here are some handy flags to filter out info you don’t care about
16
--[no-]diff-string-numeric

17. Alright, walk me through this...
17

18. Directory Environments
18

19. Workflow Steps: Step 1
Get preview box and future infra stood up
19

20. Workflow Steps: Step 2
● Create future_production branch
● Enable the future parser
20
Manually
Control Repository

21. Workflow Steps: Step 3
Run “r10k deploy” on preview box
21
[root@pe-386-master]# r10k deploy environment -pv
[INFO] Deploying environment “production”
[INFO] Deploying environment “future_production”

22. Workflow Steps: Step 4
Generate first report.
● Run Puppet Preview
● Convert JSON to HTML
22
[root@pe-386-master]# puppet preview
--baseline-environment production
--preview-environment future_production
--migrate 3.8/4.0
--nodes nodes.txt
--view overview-json | tee ~/overview.json
[root@pe-386-master]# preview_report.rb
-f ~/overview.json
-w ~/preview_report.html

23. Workflow Steps: Step 5
Find an issue to fix.
Start with any catalog compilation
errors, then move to migration
warnings / differences
23
Baseline Errors (by manifest)
Nodes..: agiledbtest2.example.com
Issues.:
'Duplicate declaration: File[u01] is already
declared in file
/etc/puppetlabs/puppet/environments/production/
site/example/manifests/oracle.pp:351; cannot
redeclare

24. Workflow Steps: Step 6
Fix the issue.
For simple changes, modify code in
future_production
For more complex issues, create a
branch off of future_production for
that issue
24

25. Workflow Steps: Step 7
Deploy change to preview box, and run
the preview tool again.
Ensure that your issue has been fixed.
25
[root@pe-386-master]# r10k deploy environment -pv
[INFO] Deploying environment “production”
[INFO] Deploying environment “future_production”
[root@pe-386-master]# puppet preview
--baseline-environment production
--preview-environment future_production
--migrate 3.8/4.0
--nodes nodes.txt
--view overview-json | tee ~/fix_file_mode.json
[root@pe-386-master]# preview_report.rb
-f ~/fix_file_mode.json
-w ~/fix_file_mode.html

26. Workflow Steps: Step 8
Rinse and repeat
26

27. 27
NOISE
LEGIT
What?! I can’t hear you!

28. But… catalog_preview only solves part of
the problem
We’re only testing catalog compilation, not catalog application
28

29. 29

30. 30

31. We need to test
Catalog Application!
● On the new infrastructure!
● Migrate CA certs to new infrastructure
● puppet agent -t --noop
--server=new_infra
--environment=future_production
● Merge into production when everything’s
fixed
31

32. Anything else I should know?
32

33. All this is happening on your diff box, not on your prod systems
33
Don’t worry. Be happy.
Catalogs are being compiled using only facts and your code

34. There’s 2 ways to get facts on the preview box
Query PuppetDB directly Yaml facts cache
34
puppet master --configprint route_file

35. YAML Facts
If you have thousands of
nodes, start with a
representative cross
section.
35
[root@pe-386-master ~]# puppet master --configprint yamldir
/var/opt/lib/pe-puppet/yaml
[root@pe-386-master ~]# tree -C /var/opt/lib/pe-puppet/yaml
/var/opt/lib/pe-puppet/yaml
├── facts
│ ├── agileappprod1.example.com.yaml
│ ├── agileappprod2.example.com.yaml
│ ├── agileappstage1.example.com.yaml
│ ├── agileappstage2.example.com.yaml
(...)
puppet preview
--nodes roles.txt
https://github.com/natemccurdy/puppet-upgrade-workplace

36. Upgrade your agents with the
puppet_agent module and you’re done!
https://forge.puppet.com/puppetlabs/puppet_agent
36