4.9.1. General Upgrade Instructions

SIMP uses the Puppet modules’ parameters as the system “API” (in terms of compatibility) and attempts to limit any API breaking changes to a minimum during a major release.

API breaking changes will have at least one minor release with deprecation warnings unless the change was to fix an actual bug in functionality.

A SIMP release version (e.g., “6.5.0-Alpha”) can be separated into three major numbers, in the format X.Y.Z:

  • X is the MAJOR release number, and indicates severe API-breaking changes.
    • Updates to packages in the simp-extras RPM do not constitute a severe API-breaking change.
  • Y is the MINOR release number, and indicates the addition of features or minor API-breaking changes either due to functionality bugs or after at least one MINOR release announcing the deprecation.
    • All API-breaking changes are kept to an absolute minimum and well documented in the release CHANGELOG.
  • Z is the PATCH release number, and indicates full backwards-compatibility changes, such as bug fixes and improvements.

This section describes both the general, recommended upgrade procedures for X, Y, or Z releases.

4.9.1.1. Incremental Upgrades

For Y and Z SIMP changes, you should feel comfortable dropping the changes directly into your test systems. The promotion cycle from test to production should be short and painless if you reference the version upgrade documentation.

Beginning with SIMP 6.4.0, SIMP-packaged Puppet module RPMs no longer install updates directly into the simp/ Puppet environment directory. You must upgrade your Puppet modules using the mechanism appropriate for your environment deployment scenario:

Important

Review any Version-Specific Upgrade Instructions prior to executing an Incremental Upgrade. There may be specific instructions regarding the upgrade process that you should follow.

4.9.1.1.1. Upgrading systems using the local deployment scenario

The following instructions are specific to the Local deployment scenario. They assume the Puppet environment you are updating is named test, and that you execute these steps as root:

  1. Update the YUM Repositories

    • Update the repositories using a SIMP ISO:

      If you have the latest SIMP ISO available to you and have installed the simp-utils package, update the YUM repositories by unpacking the ISO using unpack_dvd from that package:

      1. Copy the new SIMP ISO file to the SIMP master

      2. From the SIMP master (as root):

        # Unpack the new SIMP ISO's RPMs into yum repositories
        unpack_dvd </path/to/ISO>
        
    • For RPM-based installation, follow your site’s procedures to update your repositories.

  2. Install the RPMs

    # Make sure the puppet agent cron job does not run and pick up any
    # interim changes, including Puppet application RPM updates, until you
    # are ready for these changes.
    puppet agent --disable
    
    # Make sure yum picks up the new RPMs
    yum clean all; yum makecache
    
    # Apply updates to the local master
    yum update -y
    

    For SIMP 6.4 and later, this will also update the system-local, SIMP-managed Puppet module Git repositories.

  3. If you are upgrading from a version prior to SIMP 6.4 you can skip to the last step, Apply the changes by running puppet.

    ** The following steps only apply for upgrades from version 6.4 or later

    1. Generate the new Puppetfile.simp, a Puppetfile containing the latest versions of only SIMP-packaged Puppet modules:

      cd /etc/puppetlabs/code/environments/test
      simp puppetfile generate > Puppetfile.simp
      
    2. Verify the environment’s Puppetfile:

      Warning

      Any module not listed in the Puppetfile will be deleted from the target environment’s modules directory, when you use r10k to deploy the modules.

      Make sure the Puppetfile you will be deploying from includes the following:

      • A line that includes the Puppetfile.simp which should look like:

        instance_eval(File.read(File.join(__dir__,"Puppetfile.simp")))
        
      • A line for each of your own modules.

      See How To Generate a SIMP Puppetfile for more information on how to generate and clean up the Puppetfile if needed.

    3. Deploy the modules from the local Git repositories into the environment

      Use r10k to deploy the modules, making sure the umask and group are set correctly so that the puppetserver has access to the files.

        # Set the umask and Run r10k as the puppet group to make sure the modules
        # to make sure the permissions and ownership are correct on the modules
        ( umask 0027 && sg puppet -c '/usr/share/simp/bin/r10k puppetfile install \
        --puppetfile /etc/puppetlabs/code/environments/test/Puppetfile \
        --moduledir /etc/puppetlabs/code/environments/test/modules' )
      
      Use the --force option if you get warnings that local changes will get
      overwritten and you are sure you do not have changes that need saving.
      

    Tip

    Use simp --help for more information on the simp utility and alternate options provided for each command.

    ** This ends the steps that are only for 6.4 or later. The next steps apply to all systems.

  4. Update the generated types for the environment

    /usr/local/sbin/simp_generate_types -p /etc/puppetlabs/code/environments/test
    
  5. Re-enable Puppet and apply the changes

    puppet agent --enable
    puppet agent -t
    

4.9.1.1.2. Upgrading systems that use control repositories

If you manage your SIMP server using r10k or Code Manager and are not using the server-local, SIMP-managed Git module repositories, you will need to work with the upstream Git repositories as appropriate for your workflow. This is the same for all versions of SIMP.

For SIMP 6.4 and later, the instructions in Setting up a SIMP Environment in a Control Repository may be helpful.

4.9.1.2. Breaking Changes

If the X version number has changed then you should expect major breaking changes to the way SIMP works. Please carefully read the CHANGELOG and the SIMP User Guide and do not deploy these changes directly on top of your production environment.

If the Y version number has changed then there may either be deprecation notices or minor breaking changes to the way SIMP works. Please carefully read the CHANGELOG and the associated Version-Specific Upgrade Instructions.

Important

Upgrading SIMP does not require re-kicking your clients, even if some core services move to the new Puppet node. All software configurations can be updated in Puppet, as needed.

With the release of 6.4, SIMP RPM upgrades now have a “hands-off” approach to upgrades that allow users to easily preserve different combinations of module sets as required by their environment. That being said, the SIMP team does not test all combinations of modules and may have difficulty providing support for untested combinations.

For releases moving from version of SIMP earlier than 6.3 to versions 6.4+, see Migrating to a New Puppet Server for the simplest migration path. Also be sure to read the Version-Specific Upgrade Instructions for all of the intermediate versions.