Configure impact analysis

Impact analysis is a Continuous Delivery for Puppet Enterprise (PE) tool that shows you the potential impact that new Puppet code can have on your PE-managed infrastructure, without actually merging the new code. When you add impact analysis to a control/module repo's pipeline, Continuous Delivery for PE automatically generates a report on every proposed code change to that repo.

Configuration process and preparation

To configure impact analysis, you must set the destination server for impact analysis tasks, install the puppetlabs-cd4pe module, and make a classification update.

Set the impact analysis destination

When you integrate a new Puppet Enterprise (PE) instance with Continuous Delivery for PE, impact analysis tasks are automatically configured to run on the primary server. In many cases, it's better to change the impact analysis task destination to a different server, such as a compiler or load balancer, to preserve the primary server's compile capacity.

Before you begin
Determine a place in your PE infrastructure to direct impact analysis tasks:
  • Best: A load balancer managing a pool of compilers.
  • Good: An individual compiler dedicated to impact analysis tasks.
  • For small installations only: The PE primary server.
    Note: The primary server is the default configuration for running impact analysis tasks, but it is best suited to PE installations with limited node counts using the standard installation architecture. Impact analysis tasks can easily overrun the primary server's limited compile capacity in a larger distributed architecture.

If you choose to run impact analysis tasks on the primary server, skip to Install modules.

To run impact analysis tasks on a load balancer or compiler:
  1. In the Continuous Delivery for PE web UI, navigate to Settings > Puppet Enterprise and locate the PE instance you are configuring.
  2. Click Edit credentials and expand the Impact analysis credentials section of the page.
  3. In the Puppet Server service field, enter the hostname of the compiler or load balancer at :8140 (for example, loadbalancer.example.com:8140).
  4. Optional: Set the environments path and adjust the maximum number of catalogs that Continuous Delivery for PE is able to simultaneously compile, as explained in Optional impact analysis settings.
  5. Click Save Changes.
What to do next
Next, Install modules.

Optional impact analysis settings

To adjust these optional settings, navigate to your Puppet Enterprise (PE) instance credentials in the Settings area and expand the Impact analysis credentials section.

Environments path

CAUTION: Before setting the environments path in your impact analysis credentials, read this section and decide if it is necessary.
Adding the environments path for your PE instance to your impact analysis credentials allows Continuous Delivery for PE to perform exact file matching. This can improve the performance of impact analysis tasks in some cases. However, whether you can use the environments path depends on your PE instance configuration.
  • Add the environments path if your Puppet environments path is a single path at a known location, such as /etc/puppetlabs/code/environments.
  • DO NOT add the environments path if your PE instance uses lockless code deploys to write code to versioned directories. The environments path setting is not compatible with lockless code deploys.

Concurrent catalog compilations

This setting sets the maximum number of catalog compilations Continuous Delivery for PE is permitted to perform simultaneously. By default, Continuous Delivery for PE performs up to 10 concurrent catalog compilations.

Tune this number to fit the needs and limitations of your installation. A lower number preserves processing capacity, while a higher number reduces the time Continuous Delivery for PE spends completing each impact analysis task.

Install modules

Impact analysis requires you to install the puppetlabs-cd4pe module and its dependent modules.

The puppetlabs-cd4pe module requires six dependent modules and a module to manage job hardware. The following table lists the required modules, required versions for each module, and links to the Forge page for each module.
Module Required version
puppetlabs-cd4pe 3.1.0 or later in the 3.x series
puppetlabs-stdlib 4.19.0 or later
puppetlabs-puppet_authorization 0.5.0 or later
puppetlabs-hocon 0.9.3 or later
puppetlabs-concat 2.1.0 or later
puppetlabs-apt 4.4.1 or later
puppetlabs-translate 1.1.0 or later
puppetlabs-cd4pe_jobs Minimum: 1.4.0 or later

1.6.0 or later is required to use secrets with jobs

  1. Add the required modules to the Puppetfile for each environment against which your compilers compile catalogs.
    A sample Puppetfile entry:
    mod 'puppetlabs-cd4pe', '3.2.1'
    # Requirements for cd4pe
    mod 'puppetlabs-stdlib', '8.1.0'
    mod 'puppetlabs-puppet_authorization', '0.5.1'
    mod 'puppetlabs-hocon', '1.1.0'
    mod 'puppetlabs-concat', '7.1.1'
    mod 'puppetlabs-apt', '8.3.0'
    mod 'puppetlabs-translate', '2.2.0'
    mod 'puppetlabs-cd4pe_jobs', '1.6.0'
  2. If you configured Continuous Delivery for PE to automatically deploy code changes to the relevant environments, Continuous Delivery for PE deploys the updated code for you. If you have not configured automatic code deployments, run puppet code deploy <ENVIRONMENT> to deploy the updated code to the relevant environments.
What to do next
Next, Update classification.

Update classification

Once puppetlabs-cdpe and its dependencies are deployed, you must update classification of your nodes.

  1. In the PE console, click Node groups (or Classification in PE versions prior to 2019.8.1) and open the PE Infrastructure group.
  2. Select the PE Master group and click Classes (or Configuration in PE versions prior to 2019.8.1).
  3. In the Add new class field, select cd4pe::impact_analysis and click Add class, then commit your change.
    If you don't find cd4pe::impact_analysis in the class list, click Refresh to update class definitions.
  4. Run Puppet on the nodes in the PE Master group.
    Important: This Puppet run restarts the pe-puppetserver service.
  5. Optional: Set the maximum number of concurrent node catalog compiles allowed for each workspace. By default, 10 concurrent catalog compilations are allowed.
    Adjust this setting to manage the catalog compilation load placed on a PE instance by Continuous Delivery for PE impact analysis report generation.
    1. In the Continuous Delivery for PE web UI, click Settings.
    2. Click Puppet Enterprise,locate the PE instance you've configured to use impact analysis, and click Edit credentials.
    3. Locate the Impact analysis credentials section. In the Max concurrent catalog compiles field, set the number of catalog compilations that are allowed to run simultaneously on this PE instance.
    4. Click Save changes.
What to do next
To get started using impact analysis, see Analyzing the impact of code changes.