Prepare to upgrade the module

Before you upgrade the module, learn about the target release. Familiarize yourself with any updates that were implemented to comply with Center for Internet Security (CIS) Benchmarks or with Defense Information Systems Agency (DISA) Security Technical Implementation Guidelines (STIGs). Then, test the upgrade in a non-production environment and troubleshoot any issues.

  1. To learn about a new SCE release, review the Release notes for Linux, which document major updates, such as the introduction of additional operating systems, new or changed CIS Benchmarks, and new or changed STIG standards. You can also learn about defect fixes, minor changes, and known issues.
  2. Learn about the CIS Benchmark or STIG standard that you plan to enforce in the new release. Review the associated controls and configuration options:
    • For a list of supported CIS Benchmarks and STIG standards, see Prepare to install the module.
    • If you plan to enforce CIS Benchmarks, you can find a list of benchmarks and associated controls in the Reference on Puppet Forge. You can also download benchmark information from the CIS Benchmarks List. If you are using SCE with Security Compliance Management (formerly known as Puppet Comply), you can view details about the benchmarks in Security Compliance Management.
    • If you plan to enforce STIG controls, you can find a list of benchmarks and associated controls in the Reference on Puppet Forge. For more detailed information about STIG controls, go to the STIG Viewer. If SCE was updated to accommodate updates in a STIG standard, look for a list of changes in the Reference: Benchmarks and controls section on the documentation website.
  3. Identify a test environment. Many users follow the instructions in Environments. You can also use any alternative method that works for you.
    Testing is important because SCE can make hundreds of changes to a system, and many of those changes are critical to components. By testing and troubleshooting issues in advance, you can help to prevent issues later.
  4. In the test environment, upgrade the module. To help simplify the process, you can use a Puppetfile:
    1. Update the version in the module declaration. To upgrade the module to version 2.0.0 or later, replace cem_linux with sce_linux and specify the version, as shown in this example:
      Copy
      mod 'puppetlabs/sce_linux', '2.0.0'

      To upgrade the module to a version earlier than v2.0.0, specify the CEM declaration as shown in this example:

      Copy
      mod 'puppetlabs/cem_linux', '1.8.0'

    2. Commit the change to the appropriate branch or test environment.
    3. Deploy the change by using Code Manager or r10k. For instructions about using Code Manager and r10k, see Managing code with Code Manager.
  5. Verify that the module is successfully upgraded in the test environment.
  6. Determine whether the configuration must be updated. If so, make a list of the required updates. If you upgraded the module to v2.0.0 or later, you must replace any cem_linux references with sce_linux in the configuration of your test environment.

    If the relevant CIS Benchmark or STIG standard was updated in the release, the configuration typically requires additional updates because controls might have been added or removed, or their numbers or titles might have changed. For example, if your configuration uses a "normalized number" control ID ("c1_1_1" or similar), pay close attention to any controls whose number changed because you must update the corresponding control ID in your configuration. If the reference section indicates that the number for control "1.1.1" changed to "1.1.2," you must replace "c1_1_1" in your configuration with "c1_1_2."

    To find any documented control updates, see Reference: Benchmarks and controls.
  7. Implement any required configuration updates. This step is crucial to help prevent errors caused by misconfiguration.
    You can simplify configuration by using the Hiera key-value store as described in Getting started with Hiera. Take the following actions:
    1. Update the configuration of the test environment. For instructions, see Overview of configuration options.
    2. Ensure that the updates are deployed to the test environment. For example, if you are using Hiera and Code Manager, you must update the Hiera YAML files, commit the changes to the appropriate branch of your control repository, and trigger Code Manager.
  8. To detect and resolve any errors, take the following actions:
    1. Look for errors in Puppet runs in your test environment.
    2. If you detect errors, review and update your configuration. For help with configuration options, see the Reference.
    3. If the configuration is correct but errors persist, enable debug logging on the Puppet primary server and review the puppetserver.log file. For more information, see Puppet Server logging.
      In the logs, SCE log entries are prefixed with SCE. CEM log entries are prefixed with CEM or cem.
    4. Optionally, for additional insight into errors, enable tracing and debugging when you run the Puppet agent.
    5. If you are unable to resolve the errors, take one of the following actions:
  9. To plan the upgrade in the production environment, consider the following questions:
    • Should the upgrade occur in stages or on all nodes simultaneously?
    • What is the risk of the upgrade, and is further testing required to mitigate the risk?
    • In the rare event that the upgrade is not successful, what is the plan to roll back the changes, given the fact that SCE cannot revert changes automatically?
    For assistance with these questions, contact Puppet Support. Support engineers are prepared to assist you before, during, and after the upgrade.