Puppet Platform reference manual

For release notes on versions of Puppet Server prior to Puppet Server 5, see docs.puppet.com.

Puppet Server 5.0

Released June 27, 2017.

This is a major release of Puppet Server, and corresponds with the major release of Puppet 5.0, which also includes many changes and new features relevant to Puppet Server users.

Platform changes

Puppet Server 5.0 packages are available for RHEL 6 and 7, Debian 8 (Jessie), Ubuntu 16.04 (Xenial), and SLES 12 (SP1 or later only).

Puppet Server 5.0 is built with JDK 8, and therefore cannot run on a Java 7 runtime. Server 5.0 packages now depend exclusively upon the openjdk-8-jre-headless package. Because Ubuntu 12.04 (Precise) and 14.04 (Trusty), and versions of Debian prior to 8 (Jessie), do not distribute that package, we no longer provide Puppet Server packages for those operating systems.

For Debian 8, install the jessie-backports repository to add access to Java 8. For details, see Installing From Packages.

Upgrading from previous versions

Consult the Puppet 5.0 release notes for more information about important new features and breaking changes. Some especially relevant Puppet 5.0 changes are also noted below.

Deprecation: Puppet 5 no longer writes YAML node caches

As of Puppet 5.0, Puppet no longer writes node YAML files to its cache by default. This cache has been used in workflows where external tooling needs a list of nodes, but PuppetDB is now the preferred source of node information.

To retain the Puppet 4.x behavior, add the puppet.conf setting node_cache_terminus = write_only_yaml. Note that write_only_yaml is deprecated, and users are encouraged to migrate to PuppetDB in order to retrieve node information.

Deprecation/New Feature: Puppet 5 uses JSON serialization by default

Previous versions of Puppet exclusively used PSON, our vendored version of pure_json, for serializing communication between agents and masters. Testing showed that PSON serialization’s performance was significantly worse than using JSON, and JSON adds opportunities for easier and better interoperability with other tools and programming languages.

Puppet Server 5.0 now produces application/json responses when a Puppet 5.x agent requests them, and consumes application/json request bodies sent from Puppet 5.x agents.

Server 5.0 remains compatible with Puppet 3.x and 4.x agents that use PSON, and Puppet 5.x agents attempt to request and send text/pson only when communicating with masters that don’t support JSON communications, such as Puppet Server 2.7.x or earlier.

For details, consult the Puppet 5.0 documentation.

Security Fix: Default auth.conf rules clarify what’s allowed for file_ endpoints

Puppet Server 5.0 updates the default authorization rules in the auth.conf file to reflect that access to the “delete” HTTP method for all /puppet/v3/file_ endpoints cannot be granted, even if a rule in auth.conf would permit it. This access is always forbidden due to a hard-coded restriction in the Ruby Puppet endpoint code.

For clarity, the file_ endpoint rules are now separated into definitions per endpoint in order to reflect the valid methods that each endpoint supports, including file_bucket_file, file_content, and file_metadata.

Deprecation: Puppet Server 5 no longer runs on JDK 7

Deprecation: Legacy auth.conf settings are no longer enabled by default

By default, Puppet Server uses the HOCON-based auth.conf file introduced in Puppet Server 2.4. This uses the trapperkeeper-authorization methods of evaluating access to HTTP endpoints, instead of the legacy Puppet auth.conf file.

Puppet Server 5.0 completes this switch by changing the default value of the use-legacy-auth-conf setting in puppetserver.conf from true to false.

Deprecation: Removed resource_types API endpoints and resource_type CLI face

Puppet Server 5.0 removes the deprecated HTTP resource_type and resource_types API endpoints, and the resource_type Puppet CLI face. The /puppet/v3/environment_classes HTTP endpoint in Puppet Server replaces a subset of the resource_type functionality, including name and parameter metadata for classes.

New Feature: Performance metrics

Puppet Server 5.0 includes metrics support previously released in Puppet Enterprise, including Grafana and Graphite support, both PE-style and Jolokia-powered metrics API endpoints, and the developer dashboard.

New Feature: Optional support for JRuby 9k

Puppet Server 5.0 packages include the dependencies for both JRuby 1.7 (running Ruby language version 1.9.3) and JRuby 9k (running Ruby language version 2.3 or later). Puppet Server 5.0 uses JRuby 1.7 by default.

To instead run Puppet Server using JRuby 9k, see the “Configuring the JRuby Version” section of Puppet Server Configuration.

To facilitate this, the Puppet Server packages include both JRuby 1.7.27 and JRuby 9k, increasing package sizes by about 30 MB.

Deprecation: jruby-puppet.compat-version setting removed

Puppet Server 5.0 also updates JRuby v1.7 to v1.7.27, which in turn updates the jruby-openssl gem to v0.9.19 and bouncycastle libraries to v1.55. JRuby 1.7.27 breaks setting jruby-puppet.compat-version to 2.0 in puppetserver.conf, so Server 5.0 removes the jruby-puppet.compat-version setting and exits the puppetserver service with an error if you start the service with that setting.

For Ruby language 2.x support in Puppet Server, configure Puppet Server to use JRuby 9k instead of JRuby 1.7.27 as noted above.

New Feature: Logback logging for JRuby

Previous versions of Puppet Server logged JRuby errors to stderr, which Puppet Server wrote to either /var/log/puppetlabs/puppetserver/puppetserver-daemon.log, syslog, or journalctl (depending upon the OS). By default, JRuby also does not log debug messages.

To take advantage of the Logback logging infrastructure already in Puppet Server, JRuby now uses a custom slf4j logger that bridges logging from JRuby to Logback. As a result, Puppet Server now logs “info” and “error” messages from JRuby into /var/log/puppetlabs/puppetserver/puppetserver.log by default. To log debug-level JRuby messages, set the “level” attribute for the “jruby” element in /etc/puppetlabs/puppetserver/logback.xml file to “debug”.

New Feature: Profiling enabled by default

Puppet Server 5.0 enables profiling by default, matching the default behavior of Puppet Server in Puppet Enterprise.

New Feature: environment_modules endpoint can return all modules in all environments

Puppet Server 5.0 makes the environment query parameter of the puppet/v3/environment_modules endpoint optional. Also, to retrieve information about all modules in all environments at once, make a GET request of the puppet/v3/environment_modules endpoint without passing any parameters.

New Feature: Respect HTTP(S) proxy variables for puppetserver gem subcommand

In Puppet Server 5.0, the puppetserver gem command respects HTTP_PROXY, http_proxy, HTTPS_PROXY, https_proxy, NO_PROXY, and no_proxy environment variables, allowing puppetserver to install gems when behind a proxy defined by these environment variables.

Bug Fix: Add timeout to JRuby lock requests to avoid hanging the puppetserver service

In previous versions of Puppet Server, a request to lock all JRuby instances would stall indefinitely was made while a single instance in the JRuby pool stalled, effectively deadlocking the puppetserver service and requiring manual intervention to release the lock.

Puppet Server 5.0 resolves this by adding a timeout to the pool lock request. If that timeout expires, Puppet Server throws an exception instead of locking up indefinitely.

Bug Fix: Include Content-Type headers in static file content API responses

In previous versions of Puppet Server, responses to requests of the puppet/v3/static_file_content endpoint did not include a Content-Type header. As of Puppet Server 5.0, responses to successful requests include a application/octet-stream Content-Type header. Error responses from this endpoint include a text/plain Content-Type.

Bug Fix: Require which command for RPM package installation

Installing previous versions of Puppet Server via RPM packages could fail with a which: command not found error if which was not installed on the system.

Puppet Server 5.0 packages require /usr/bin/which, ensuring that it will be installed.

Bug Fix: Wait for puppetserver to stop before attempting to restart it via sysvinit

In previous versions of Puppet Server, attempting to restart the puppetserver service using its sysvinit script would always try to immediately restart the service, even if stopping the service failed. Also, in some cases the service might not terminate immediately when sent a kill signal (SIGKILL), which exacerbated the issue.

Puppet Server 5.0 resolves this by waiting for a grace period after sending a SIGKILL to the puppetserver service to ensure that it successfully exits, and attempts to restart the service only after the service is successfully stopped.

Bug Fix: Improved handling of CLI subcommands

In previous versions of Puppet Server, puppetserver CLI subcommands discarded exit codes, which could prevent errors from commands like puppetserver gem from being detected. In Puppet Server 5.0, these CLI commands now exit with the same return code as the Ruby command would have provided.

Also, subcommands previously did not account for errors raised when loading and validating the puppetserver configuration. An invalid configuration could crash the subcommand with an unhelpful error message unrelated to the actual configuration validation failure. Puppet Server 5.0 resolves this by propagating errors with an unexpected format to output without modification.

In previous versions of Puppet Server, puppetserver CLI subcommands used /dev/random for entropy. On systems with limited sources of entropy, such as virtual machines, these subcommands could rapidly drain the entropy pool, leading to slow performance as the pool gradually refilled. For instance, this could cause gem installation using the puppetserver gem subcommand to take much longer than expected.

Puppet Server 5.0 resolves this by instead using /dev/urandom for CLI subcommands.

Other changes

  • SERVER-1807: Puppet Server 5.0 embeds hocon gem version 1.2.5 in the default Puppet Server gem path, an upgrade from v1.1.3 used in Server v2.7.2.
  • SERVER-1671: Log only error output (stderr) to puppetserver.log for generate() function calls.
  • SERVER-715: Resolve intermittent 500 error status results and isExpired(puppet_environments.clj:27) logged errors on some HTTP API requests.
Back to top
The page rank or the 1 our of 5 rating a user has given the page.
The email address of the user submitting feedback.
The URL of the page being ranked/rated.