Configure impact analysis

Impact analysis is a Continuous Delivery for Puppet Enterprise (PE) tool that lets you see the potential impact that new Puppet code will have on your PE-managed infrastructure, even before the new code is merged. When you add impact analysis to a control repo's pipeline, Continuous Delivery for PE automatically generates a report on every proposed code change to that control repo.

Configuration process

In order to use 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 a new PE instance is integrated with Continuous Delivery for PE, by default impact analysis tasks are automatically configured to run on the primary server. In many cases, it's better to set 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 the best place in your PE infrastructure to direct impact analysis tasks:
  1. Best: A load balancer managing a pool of compilers.
  2. Good: An individual compiler dedicated to impact analysis tasks.
  3. For small installations only: The PE primary server.
    Note: While running impact analysis tasks on the primary server is the default configuration, it is best suited to PE installations with limited node counts using the standard installation architecture. Impact analysis tasks can easily overrun the limited compile capacity of a primary server in a larger distributed architecture.

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

To set impact analysis tasks to run 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 pencil icon 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,
  4. Optional: Set the environments path and adjust the maximum number of catalogs that Continuous Delivery for PE is able to simultaneously compile. For instructions for these settings, go to Optional impact analysis settings.
  5. Click Save Changes.

Optional impact analysis settings

Adjust these optional settings by navigating to your Puppet Enterprise instance credentials in the Settings area and expanding the Impact analysis credentials section.

Environments path

CAUTION: Only set the environment path in your impact analysis credentials if necessary and after reviewing this section.

Adding the environments path for your PE instance to your impact analysis credentials allows Continuous Delivery for PE to perform exact file matching, which can improve the performance of impact analysis tasks in some cases. However, whether or not to use the environment path depends on the way your PE instance is configured:

  • Add the environment path if your Puppet environment path is a single path at a known location (such as /etc/puppetlabs/code/environments).
  • DO NOT add the environment path if your PE instance uses lockless code deploys to write code to versioned directories. The environment path setting is not compatible with lockless code deploys.

Concurrent catalog compilations

Set 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 must be used with six dependent modules, plus a module to manage job hardware. The modules and their required versions are as follows:

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 1.4.0 or later
  1. Add the modules listed above 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.5.0'
  2. Deploy the updated code to the relevant environments by running puppet code deploy <ENVIRONMENT>.
    Remember: Continuous Delivery for PE performs this step for you if you've configured it to deploy code changes automatically to the relevant environments.

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 and locate the PE instance you've configured to use impact analysis. Click Edit credentials.
    3. Locate the Impact analysis credentials section of the window. 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.