Since version 2.1, Puppet Server can serve configurations to both Puppet 4 and Puppet 3 agents. Once your Puppet 3 nodes work with a newer Puppet Server, start upgrading them to Puppet 4.
Backward compatibility is enabled by default, but you should ensure your Puppet code is ready for Puppet 4 before pointing old agents at a new Puppet server. You might also need to edit auth.conf
.
Before migrating Puppet 3 nodes to Puppet Server 2, do all of the following:
stringify_facts = false
on all nodes, and fix your code if necessary.parser = future
on your Puppet masters, and fix your code if necessary.auth.conf
rules for the new Puppet Server version.Follow the steps in the Puppet documentation to prepare your Puppet 3 deployment for a major version upgrade. This is especially important on your Puppet master, where you’ll want the newest version of the future parser.
auth.conf
Puppet 3 and 4 use different HTTPS URLs to fetch configurations. Puppet Server lets agents make requests at the old URLs, but internally it handles them as requests to the new endpoints. Any rules in auth.conf
that match Puppet 3-style URLs will have no effect.
This means you must:
Check any custom rules you’ve added to your auth.conf
file. (Don’t worry about default rules.)
If you don’t set jruby-puppet.use-legacy-auth-conf
or set jruby-puppet.use-legacy-auth-conf
in the puppetserver.conf
file to false
, you must reimplement your authorization rules in /etc/puppetlabs/puppetserver/conf.d/auth.conf
and use the configuration file’s new HOCON format. See the Puppet Server auth.conf
documentation for more information.
If you set jruby-puppet.use-legacy-auth-conf
to true
, implement your rules using the legacy format in /etc/puppetlabs/puppet/auth.conf
. See the Puppet auth.conf
documentation for more information on this file format. Support for this legacy format under Puppet Server is deprecated and will be removed in a future release.
path
to match Puppet 4 URLs.
/puppet/v3
to the beginning of most paths.certificate*
endpoints are not validated by auth.conf
rules when jruby-puppet.use-legacy-auth-conf
is set to true
. If you need to configure authorization for these endpoints, consider configuring this setting to false
or leave it unset. See the Puppet Server auth.conf
documentation for more information.auth.conf
file on your Puppet Server.For more information, see:
auth.conf
documentationauth.conf
documentationauth.conf
Rules for Puppet 3 and 4 AgentsThe examples in this section convert this Puppet 3 example auth.conf
rule so that it is compatible with Puppet 4:
# Puppet 3 auth.conf on the master
path ~ ^/catalog/([^/]+).uuid$
method find
allow /^$1\.uuid.*/
# Default rule, should follow the more specific rules
path ~ ^/catalog/([^/]+)$
method find
allow $1
To support both Puppet 3 and Puppet 4 agents when the use-legacy-auth-conf
parameter in the jruby-puppet
setting is false
or unset, modify the rules to follow the new HOCON auth.conf
format and place the new rules in /etc/puppetlabs/puppetserver/conf.d/auth.conf
:
authorization: {
version: 1
rules: [
...
{
# Puppet 3 & 4 compatible auth.conf with Puppet Server 2.2+
match-request: {
path: "^/puppet/v3/catalog/([^/]+).uuid$"
type: regex
method: [get, post]
}
allow: "/^$1|.uuid.*/"
sort-order: 200
name: "my catalog"
},
{
# Default rule, should follow the more specific rules
match-request: {
path: "^/puppet/v3/catalog/([^/]+)$"
type: regex
method: [get, post]
}
allow: "$1"
sort-order: 500
name: "puppetlabs catalog"
},
...
]
}
To support both Puppet 3 and Puppet 4 agents when the use-legacy-auth-conf
parameter in the jruby-puppet
setting is true
, modify the rules to specify the v3 endpoints while following the legacy auth.conf
format, and place the new rules in /etc/puppetlabs/puppet/auth.conf
:
# Puppet 3 & 4 compatible auth.conf with Puppet Server 2.1+
path ~ ^/puppet/v3/catalog/([^/]+).uuid$
method find
allow /^$1\.uuid.*/
# Default rule, should follow the more specific rules
path ~ ^/puppet/v3/catalog/([^/]+)$
method find
allow $1
Note: For more detailed
auth.conf
conversion examples, see Migrating to the HOCON auth.conf Format.
The legacy-routes-service
intercepts Puppet 3 HTTPS API requests, transforms the URLs and request headers into Puppet 4 compatible requests, and passes them to the Puppet master service.
There are some minor differences in headers between native Puppet 4 requests and modified Puppet 3 requests. Specifically:
X-Puppet-Version
header is absent in Puppet 3 requests. This should only matter if you use this header to configure a third-party reverse proxy like HAProxy or NGINX.The Accept:
request header is changed to match the content the Puppet 4 master service can provide. For example, Accept: raw
and Accept: s
are changed to Accept: binary
.
This header is used, albeit rarely, to configure reverse proxies.
content-type
for file bucket content requests is treated internally as application/octet-stream
, but the request and the response are treated as text/plain
for compatibility with Puppet 3.