Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Upgrading Puppet

Red Hat Satellite 6.3 uses Puppet 3 by default, but you can also upgrade to Puppet 4. Satellite 6.4 will support only Puppet 5. The migration path for Puppet 5 supports only Puppet 4 to Puppet 5 migrations. Therefore if you are using a version of Puppet prior to version 4, you must upgrade to Puppet 4 prior to upgrading to Satellite 6.4. Satellite 6.3 includes an upgrade path to Puppet 4, and Red Hat recommends you do it now to prepare for your next upgrade. This chapter describes the process of upgrading to Puppet 4.

3.1. Upgrade Path
Copy link

Before upgrading to Puppet 4, you must first review your Puppet modules, and make changes, to ensure they are compatible with Puppet 4 before upgrading Puppet. For example, if the client has blank configuration values after running the Puppet agent, updating Puppet modules is indicated.

Red Hat Satellite and Capsules do not have to be upgraded to Puppet 4 at the same time. You have the flexibility to upgrade Capsules depending on your progress with testing and upgrading Puppet modules. An alternative is to install new Capsules and move hosts to them after testing. You can use Satellite web UI, the Hammer CLI, or the bootstrap script to move hosts from a Puppet 3 Capsule to a Puppet 4 Capsule.

Cloning an existing Capsule to use for final testing of upgraded Puppet modules is also recommended. Cloning an existing Capsule can take a long time depending on the size of the repositories.

You must install the Puppet 4 agent on the hosts for full functionally, but hosts must not be upgraded to Puppet 4 agent before their Capsule is upgraded to Puppet 4. For more information about installing Puppet agent, see Installing the Puppet Agent.

Using Parameters to Determine Puppet Versions

You can configure Satellite to install the Puppet 4 agent instead of the Puppet 3 agent during host provisioning. The Kickstart template file has the parameter enable-puppet4; if set to true, the provisioning template installs the Puppet 4 agent and configures puppet.conf in the /etc/puppetlabs/puppet/ directory. If the parameter is not defined, Puppet 3 agent is installed.

To enforce Puppet 4 for hosts, create a parameter at the host group level with name enable-puppet4 and set its value to true.

  1. In the web UI, navigate to Configure > Host Groups and select the name of the host group you want to configure.
  2. Click the Parameters tab, and in the Host Group Parameters area, click Add Parameter.
  3. In the Name field, enter enable-puppet4 and in the Value field, enter true.
  4. Click Submit to save the changes.

3.2. Testing Puppet Modules
Copy link

Use the following guidelines to test your Puppet modules before you begin upgrading:

  1. Test Puppet modules first on a workstation, separate from Satellite.
  2. Check the command syntax using the puppet parser validate command.
  3. Configure the Satellite Capsules running Puppet 3 to use the future parser and test again. To enable this feature, run the Satellite installer with the option --puppet-server-parser future.

The future parser in Puppet 3.8 enables functionality identical to the Puppet language used in Puppet 4.0. After enabling it, check the logs in /var/log/puppet/ for errors. If you find errors, correct them and test again. See the Puppet 3.8 Reference Manual for information on the future parser.

3.3. Performing the Upgrade
Copy link

Use this section to upgrade a Satellite or Capsule to Puppet 4. For a new installation, see the Red Hat Satellite Installation Guide.

Before You Begin

  • Ensure you complete the upgrade to Satellite 6.3.
  • Review your Puppet modules and upgrade where required to Puppet 4.
  • Ensure all hosts connected to the system that you want to upgrade have the latest Puppet 3 agent and not version 4. You must not upgrade hosts to Puppet 4 agent before their Capsule. The Satellite tools repository supplies the Puppet package. See Section 2.7.2, “Upgrading Satellite Clients” for more information.
  • Create a backup or a snapshot of your system. For more information, see Backing Up and Restoring Satellite Server and Capsule Server in Administering Red Hat Satellite.

Upgrading Satellite or Capsule To Puppet 4

  1. Enable the Puppet 4 repository:

    1. On a Satellite: 

      # subscription-manager repos \
--enable=rhel-7-server-satellite-6.3-puppet4-rpms
      Copy to Clipboard Toggle word wrap

    2. On a Capsule: 

      # subscription-manager repos \
--enable=rhel-7-server-satellite-capsule-6.3-puppet4-rpms
      Copy to Clipboard Toggle word wrap

  2. Upgrade Puppet: 

    # satellite-installer --upgrade-puppet
    Copy to Clipboard Toggle word wrap

Before You Begin

  • Ensure the Puppet 4 repositories for your hosts are enabled in Satellite Server.
  • Ensure your hosts associated Content Views have been updated to include the Puppet 4 agent.

The Puppet repositories for upgrading a host are Red Hat release and platform dependent, and sometimes also architecture dependent.

  • The Puppet 4 repositories take the following form for desktop, server, and workstation: 

    rhel-X-platform-satellite-tools-6.3-puppet4-rpms
    Copy to Clipboard Toggle word wrap

    Where X is the major release version, and platform is desktop, server, or workstation.

  • The Puppet 4 repositories take the following form for alternative architectures: 

    rhel-X-for-architecture-satellite-tools-6.3-puppet4-rpms
    Copy to Clipboard Toggle word wrap

    Where X is the major release version, and architecture is for example arm, power, hpc-node, or system-z. Some repositories are for subscriptions with extended support. For example, Extended Update Support (EUS) is indicated by eus after the architecture.

    For more information about types of extended support, see the Red Hat Knowledgebase article Red Hat Enterprise Linux - Top Support Policies.

  1. On the content host, search for the Puppet 4 RPM repository: 

    # subscription-manager repos |grep puppet4
    Copy to Clipboard Toggle word wrap

  2. Enable the Puppet 4 repository suitable for the host, for example: 

    # subscription-manager repos \
--enable=rhel-7-server-satellite-tools-6.3-puppet4-rpms
    Copy to Clipboard Toggle word wrap

  3. Update all packages: 

    # yum update
    Copy to Clipboard Toggle word wrap

  4. Until Red Hat bug Bug 1517624 has been resolved, perform these additional steps: 

    # cp -rp /var/lib/puppet/ssl /etc/puppetlabs/puppet/
# cp /etc/puppet/puppet.conf.rpmsave /etc/puppetlabs/puppet/puppet.conf
# sed -i 's|/var/lib/puppet|/opt/puppetlabs/puppet/cache|' /etc/puppetlabs/puppet/puppet.conf
# sed -i 's|/var/log/puppet|/var/log/puppetlabs/puppet|' /etc/puppetlabs/puppet/puppet.conf
# sed -i 's|/var/run/puppet|/var/run/puppetlabs|' /etc/puppetlabs/puppet/puppet.conf
# sed -i 's|$vardir/ssl|/etc/puppetlabs/puppet/ssl|' /etc/puppetlabs/puppet/puppet.conf
    Copy to Clipboard Toggle word wrap

Post Upgrade Tasks

When you upgrade to Puppet 4, Puppet Server cannot function if the noexec bit is set on the temporary mount point that Java uses.

Complete the following steps to ensure that the puppetserver service can start correctly:

  1. Open the /etc/sysconfig/puppetserver file for editing: 

    # vi /etc/sysconfig/puppetserver
    Copy to Clipboard Toggle word wrap

  2. In the /etc/sysconfig/puppetserver file, change JAVA_ARGS="-Xms2G -Xmx2G -XX:MaxPermSize=256m" to the following: 

    JAVA_ARGS="-Xms2G -Xmx2G -XX:MaxPermSize=256m -Djava.io.tmpdir=/var/tmp"
    Copy to Clipboard Toggle word wrap

    You can set the variable /var/tmp to the directory you prefer.

  3. Open the /etc/foreman-installer/custom-hiera.yaml for editing: 

    # vi /etc/foreman-installer/custom-hiera.yaml
    Copy to Clipboard Toggle word wrap

  4. In the /etc/foreman-installer/custom-hiera.yaml file, add the following line to make your changes persistent across satellite-installer executions: 

    puppet::server_jvm_extra_args: '-XX:MaxPermSize=256m -Djava.io.tmpdir=/var/tmp'
    Copy to Clipboard Toggle word wrap

    You can set the variable /var/tmp to the directory you prefer.

  5. Restart the puppetserver service: 

    # systemctl restart puppetserver
    Copy to Clipboard Toggle word wrap

  6. Verify that the puppetserver service is running: 

    # systemctl status puppetserver
    Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red Hat