Upgrading

New versions of Puppet Comply are released regularly. Upgrading to the current version helps you take advantage of the latest features, fixes, and improvements.

Important: The CIS-CAT Pro Assessor setup process is embedded in the comply module. If you are upgrading to the latest version of the CIS-CAT Pro Assessor, upgrade the comply module before you upgrade the Comply application. Note that you cannot run scans until you complete both of these upgrades.

Upgrade from Comply 1.0.4 to 2.11.0

Comply 2.11.0 automatically upgrades the CIS-CAT Pro Assessor to the latest version when upgrading Comply. However, by adjusting your configuration you can choose to stay on a previous version of the assessor.

The upgrade process involves generating certificates in Puppet Enterprise (PE) and setting up Mutual Transport Layer Security (MTLS) in Puppet Application Manager (PAM). MTLS enables a secure authenticated connection between your nodes and Comply.
Tips:
  • If you are upgrading Comply in an environment with thousands of nodes, see Guidelines for running scans at scale.
  • If you are upgrading Comply to a version that includes a new assessor, you can expedite the process of installing the assessor on all nodes. In the PAM Config tab, in the CIS-CAT Pro Assessor upgrade section, select the checkbox to automatically start two Puppet runs after an assessor upgrade. To help prevent performance issues, enable this option only in small to medium Puppet deployments. If you enable this option, you can verify that a PE job was run: In Comply, select Activity Feed > Assessor Upgrades and click the assessor version to see the PE job number.
  1. SSH into your PE primary server and generate the certificates: 
    puppetserver ca generate --certname <COMPLY-HOSTNAME>
    This command does the following:
    • Saves the private key to /etc/puppetlabs/puppet/ssl/private_keys/<COMPLY-HOSTNAME>.pem
    • Saves the certificate to /etc/puppetlabs/puppet/ssl/certs/<COMPLY-HOSTNAME>.pem
  2. Log in to PAM, click the Version history tab, and click Check for update.
  3. Click the Config tab and scroll down to Transport layer security (TLS) certificates to interact with PE.
  4. Upload the signed certificate public key, the private key files, and the CA certificate, with the following locations:
    • Paste the contents of /etc/puppetlabs/puppet/ssl/certs/<COMPLY-HOSTNAME>.pem to the TLS certificate field.
    • Paste the contents of /etc/puppetlabs/puppet/ssl/private_keys/<COMPLY-HOSTNAME>.pem to the TLS private key field.
    • Paste the contents of /etc/puppetlabs/puppet/ssl/ca/ca_crt.pem to the CA certificate field.
    Note: To host the assessor on your own supported cluster via NGINX ingress, select the Bring your own NGINX ingress checkbox and enter the FQDN in the PE TLS FQDN field — using the same FQDN that you used to generate the TLS certificates.
  5. Navigate to CIS-CAT Pro Assessor version and ensure that the correct version of the CIS-CAT Pro Assessor is selected.
  6. Click Save Config.
  7. Navigate to Puppet Enterprise (PE), and update the default value of the comply class scanner_source parameter to one of the following assessor distribution files:

    • If using the Puppet supported cluster: https://<COMPLY-HOSTNAME>:30303/assessor

    • If using NGINX Ingress: scanner_source to: https://<PE-TLS-FQDN>/assessor

    For more information, see Classify the nodes you want to scan in PE.

  8. Click Add to node group, and then commit the changes.
  9. Upgrade the comply module:
    1. Update your Puppetfile with the latest version of the comply module and its dependencies.
    2. To stay on a previous version of the CIS-CAT Pro Assessor, configure the module's scanner_version and scanner_source class parameters to the desired version of the assessor. The version configured must match the version selected in step 5. To upgrade to the latest version of the CIS-CAT Pro Assessor, remove those parameters and the module defaults to the latest version.
    3. CAUTION: Only the latest version of the CIS-CAT Pro Assessor has the latest security fixes. Customers on older versions of the CIS-CAT Pro Assessor might be vulnerable to security issues.

    4. Deploy code by running the puppet-code deploy --all command.
  10. Navigate back to PAM. After the pre-flight checks are successfully completed, click Go to updated version, and then click Deploy.
What to do next
If the upgrade of an assessor on a node fails, the node is marked in red on the Inventory page. Failures may be due to network issues. If that is the case, Comply attempts to upgrade the node when connectivity returns. An hourly background task runs to check if nodes are upgraded. If a node is not upgraded and remains red on the Inventory page, run Puppet. If the upgrade continues to fail, see the Puppet agent logs for more information as described in Agent logs.

Upgrade from Comply 2.2.2 to 2.3.0

Comply 2.3.0 automatically upgrades the CIS-CAT assessor to the latest version every time you upgrade Comply.

Before you begin
Make sure you have generated certificates in Puppet Enterprise (PE) and set up Mutual Transport Layer Security (MTLS) in Puppet Application Manager (PAM). MTLS enables a secure authenticated connection between your nodes and Comply. For more information, see Configure Comply TLS certificates.
  1. If you want Comply to update the CIS-CAT Assessor automatically, select Automatically kick off PE jobs on assessor upgrade on the Config page in Puppet Application Manager.

    If you select this option, on upgrade Comply kicks off 2 PE agent runs: the first to download the new assessor, and the second update the facts in PE.

    Tip: Because this option starts PE jobs automatically on upgrading Comply, systems administrators, especially of larger implementation, may wish to consider leaving this option unchecked. Assessor upgrade then takes place automatically when the next two PE jobs are run.

    Comply requires the latest version of the assessor on the node in order to perform runs. A background task runs to check if nodes have been upgraded every 15 minutes if this option is selected and every hour if it is not selected. If a node does not upgrade and remains red on the Inventory page, run the Puppet agent. If the upgrade continues to fail, see the Puppet agent logs for more information.

  2. Click Save Config.
  3. If you have not already configured the comply class scanner_source parameter, you can do so at this point. Otherwise proceed to the next step. Navigate to Puppet Enterprise (PE), and update the default value of the comply class scanner_source parameter to one of the following assessor distribution files:

    • If using the Puppet supported cluster: https://<COMPLY-HOSTNAME>:30303/assessor

    • If using NGINX Ingress scanner_source: https://<PE-TLS-FQDN>/assessor

    For more information, see Classify the nodes you want to scan in PE.

    Click Add to node group, and then commit the changes.

  4. Upgrade the comply module.
    1. Update your Puppetfile with the latest version of the comply module and its dependencies.
    2. Deploy code by running the puppet-code deploy --all command.
    Warning: When upgrading the comply module, running the agent before Comply is updated may cause an error.
  5. Navigate back to Puppet Application Manager. After pre-flight checks have completed successfully, click Go to updated version, and then click Deploy.
    Note: If the upgrade of an assessor on a node fails, the node is marked in red on the Inventory page. Failures may be due to network issues. If that is the case, Comply attempts to upgrade the node once connectivity returns. An hourly background task runs to check if nodes have been upgraded or not. If a node does not upgrade and remains red on the Inventory page, run the Puppet agent. If the upgrade continues to fail, see the Puppet agent logs for more information.

Upgrade Comply in an online environment

Check for downloads and deploy updates from the Version history tab in the Puppet Application Manager (PAM) UI.

Before you begin
Upgrade the comply module.
  1. In the PAM UI, click Version history.
  2. Click Check for updates.
    Configure an automatic update check by clicking Configure automatic updates. You can check for updates hourly, every four hours, daily, weekly, or at a custom interval.
  3. If an update is available, PAM downloads it for you and performs preflight checks on your system to make sure your cluster meets system requirements for the new version. Review the outcome of these checks by clicking View preflight.
  4. When you're ready to upgrade to the new version of Comply, click Deploy.

Upgrade Comply in an offline environment

If your environment does not have direct access to the internet, follow the documented procedure to upgrade Comply to the latest version.

Before you begin
Upgrade the comply module.
  1. Navigate to the portal provided to you by Puppet in the licence email, for example, https://get.replicated.com/airgap/#/kots/comply/, and log in with the password.
  2. Select Embedded cluster and click Download airgap bundle.
  3. Log into Puppet Application Manager: 
    https://<PLATFORM-ADMIN-CONSOLE-ADDRESS>:8800
  4. Select Version history and upload the new version of the .airgap file that you downloaded in step 2.
  5. Click Deploy.