Project

General

Profile

Upgrading from Puppet 3 to 4 » History » Version 5

Dominic Cleal, 05/26/2016 09:36 AM
legacy auth off

1 1 Dominic Cleal
h1. Upgrading from Puppet 3 to 4
2
3
+_This wiki page is a work in progress for the release of Foreman 1.12 and is currently incomplete._+
4
5
This wiki page is a rough guide on how to upgrade from Puppet 3 to Puppet 4 when using Foreman. It doesn't replace Puppet's own documentation - you need to take both into account, and it's not for the faint-hearted.
6
7
Remember, Puppet is a separate piece of software to Foreman. Foreman integrates with Puppet in only a few places (e.g. reports, ENC and smart proxy class imports) but the Foreman installer may have set it up for you initially. Most of the work is changing the Puppet installation and then updating paths and configs in Foreman to suit.
8
9
If you're unfamiliar with how Puppet works, then you should consider setting up a new installation and migrating hosts instead.
10
11
h2. Planning
12
13
Ensure you are running Foreman 1.12 or higher, previous versions are not compatible with Puppet 4, while 1.12 is compatible with both 3 and 4, so carry out that upgrade first. See "Upgrading to Foreman 1.12":http://theforeman.org/manuals/1.12/index.html#3.6Upgrade for more information.
14
15
*Start with "Puppet 3.x to 4.x: Get upgrade-ready":https://docs.puppet.com/puppet/latest/reference/upgrade_major_pre.html* - it has many excellent points, including:
16
17
* As with any upgrade, the smaller the step, the easier it will be. Ensure you've already upgraded to the latest 3.x release and fixed any deprecations from the release notes before moving to 4. This will save time later.
18
* Ensure your Puppet modules are going to be compatible with Puppet 4's new ("future") parser
19
* Plan to upgrade your masters before your agents, because the master can serve older agents, but not the other way around.
20
* Back up everything, especially SSL keys and certificates.
21 2 Dominic Cleal
* Ensure you have enough RAM, Puppet Server defaults to requiring at _least_ 2GB
22 1 Dominic Cleal
23
The guide will assume you're using regular 'puppet' packages either from your OS (or EPEL) or from Puppet Labs repositories. Puppet 4 packages are All-In-One (AIO) packages and work quite differently, introducing lots of new paths for config files and binaries. More information on these at:
24
25
* "Welcome to Puppet Collections":https://puppet.com/blog/welcome-to-puppet-collections
26
* "About Puppet collections and packages":https://docs.puppet.com/puppet/latest/reference/puppet_collections.html
27 2 Dominic Cleal
28
h2. Upgrading
29
30
h3. Install new PC1 packages
31
32
# Configure the new PC1 repositories with the "Using Puppet Collections":https://docs.puppet.com/guides/puppetlabs_package_repositories.html#using-puppet-collections instructions.
33
# On EL, run @yum remove puppet-server@ to prevent later conflicts.
34
# Install the @puppetserver@ package, which should replace @facter@, @puppet@ and @puppet-server@ with @puppetserver@ and @puppet-agent@
35
36
h3. Move configs and files to new structure
37
38
This section is based on "Puppet 3.x to 4.x: Upgrade Puppet Server":https://docs.puppet.com/puppet/latest/reference/upgrade_major_server.html which goes into far more detail.
39
40
# Move or copy any environments from @/etc/puppet/environments@ to @/etc/puppetlabs/code/environments@
41
# Move or copy all SSL keys and certificates from @/var/lib/puppet/ssl@ to @/etc/puppetlabs/puppet/ssl@
42
# Remove the Puppet master VirtualHost from Apache at @/etc/httpd/conf.d/25-puppet.conf@ (EL) or @a2dissite 25-puppet@ (Debian/Ubuntu)
43
# Remove 8140 from the Apache ports in @/etc/httpd/conf/ports.conf@ or @/etc/apache2/ports.conf@
44
# Update SSL paths in @/etc/httpd/conf.d/05-foreman-ssl.conf@ or @/etc/apache2/sites-available/05-foreman-ssl.conf@, changing @/var/lib/puppet/ssl@ to @/etc/puppetlabs/puppet/ssl@
45
# Restart httpd/apache2 to free up the port
46
47 3 Dominic Cleal
Config files:
48 2 Dominic Cleal
49
# @mv /etc/puppet/autosign.conf /etc/puppetlabs/puppet/@
50
# @cp /etc/puppet/puppet.conf /etc/puppetlabs/puppet/puppet.conf@ and change:
51
#* in the 'main' section:
52
#*# @vardir = /opt/puppetlabs/puppet/cache@
53
#*# @logdir = /var/log/puppetlabs/puppet@
54
#*# @rundir = /var/run/puppetlabs@
55 1 Dominic Cleal
#*# @ssldir = /etc/puppetlabs/puppet/ssl@
56
#*# @environmentpath = /etc/puppetlabs/code@
57 2 Dominic Cleal
#*# @basemodulepath = /etc/puppetlabs/code/environments/common:/etc/puppetlabs/code/modules:/opt/puppetlabs/puppet/modules@
58 3 Dominic Cleal
#* in the 'agent' section:
59
#*# remove @configtimeout@
60 2 Dominic Cleal
#* in the 'master' section:
61 1 Dominic Cleal
#*# @autosign = /etc/puppetlabs/puppet/autosign.conf { mode = 0644 }@
62
#*# @external_nodes = /etc/puppetlabs/puppet/node.rb@
63
#*# @ssldir = /etc/puppetlabs/puppet/ssl@
64 3 Dominic Cleal
# edit @/etc/puppetlabs/puppetserver/conf.d/puppetserver.conf@
65
## change @master-var-dir@ to @/opt/puppetlabs/puppet/cache@
66 5 Dominic Cleal
## uncomment/set @use-legacy-auth-conf: false@ 
67 3 Dominic Cleal
68 4 Dominic Cleal
If using a smart proxy to import classes, edit @/etc/puppetlabs/puppetserver/conf.d/auth.conf@, search for @/puppet/v3/environments@ and add a new section below it:
69
70
<pre>
71
        {
72
            match-request: {
73
                path: "/puppet/v3/resource_type"
74
                type: path
75
                method: [get, post]
76
            }
77
            allow: "*"
78
            sort-order: 500
79
            name: "puppetlabs resource type"
80
        },
81
</pre> 
82
83 3 Dominic Cleal
Update ENC files:
84
85
# @cp /etc/puppet/foreman.yaml /etc/puppetlabs/puppet/foreman.yaml@ and change:
86
## replace @/var/lib/puppet/ssl@ with @/etc/puppetlabs/puppet/ssl@
87
## @:puppetdir: /opt/puppetlabs/puppet/cache@
88
# @mv /etc/puppet/node.rb /etc/puppetlabs/puppet/@
89
90
Update Foreman settings:
91
92
# edit @/etc/foreman/settings.yaml@ and change @:puppetssldir: /etc/puppetlabs/puppet/ssl@
93 4 Dominic Cleal
# change @websockets_*@ settings to use @/etc/puppetlabs/puppet/ssl@ and also @ssl_*@ if specified
94 3 Dominic Cleal
# restart Foreman by running @touch ~foreman/tmp/restart.txt@
95 4 Dominic Cleal
# check in _Administer > Settings > Auth_ in the Foreman UI that SSL certificate, private key and CA file all use @/etc/puppetlabs/puppet/ssl@, else change them
96 3 Dominic Cleal
97
Update smart proxy settings:
98
99
# edit @/etc/foreman-proxy/settings.d/puppet.yml@ and set @:puppet_version@ to the version of Puppet currently installed, e.g. 4.5.0
100
#* look up the version of puppet-agent (@rpm -q puppet-agent@ or @dpkg -l puppet-agent@) and check "Release contents":https://docs.puppet.com/puppet/4.5/reference/about_agent.html
101
# edit @/etc/foreman-proxy/settings.d/puppet_proxy_puppet_api.yml@ and change @/var/lib/puppet/ssl@ to @/etc/puppetlabs/puppet/ssl@
102
# edit @/etc/foreman-proxy/settings.yml@ and change @/var/lib/puppet/ssl@ to @/etc/puppetlabs/puppet/ssl@
103
# restart foreman-proxy
104
105
h2. Further reading
106
107
* "Puppet reference manual":https://docs.puppet.com/puppet/latest/reference/index.html
108
* "Puppet Server documentation":https://docs.puppet.com/puppetserver/latest/
109
* "Puppet Server vs Apache/Passenger Puppet master":https://docs.puppet.com/puppetserver/latest/puppetserver_vs_passenger.html
110
* "Where did everything go in Puppet 4.x?":https://docs.puppet.com/puppet/latest/reference/whered_it_go.html
111
* "puppet-agent: What is it, and what's in it?":https://docs.puppet.com/puppet/4.5/reference/about_agent.html