Generate impact analysis reports

Impact analysis reports show you the potential impact and risk of proposed code changes, so you can decide how, and if, you want to handle those potential changes. You can generate reports on demand or add impact analysis tasks to your pipelines to generate impact analysis reports for every change submitted to your repos. Impact analysis reports are generated by diffing the deployment's current catalog against a newly-generated catalog for your specified deployment conditions.

Important: With impact analysis enabled, catalog compiles are generated every time impact analysis detects that a node could be impacted by a Puppet code change. These additional compiles increase the performance load placed on your PE primary server.
Restriction: Impact analysis fails if you include the $environment variable in your Puppet manifest. Instead, use Hiera and class parameters.

Impact analysis workflow

Impact analysis targets a specific environment (such as development) and a specific version of code, identified by a Git commit SHA. Using the designated environment and SHA, Continuous Delivery for PE does the following during an impact analysis run:
  1. Create a temporary branch in the control repo using the naming scheme <BRANCH>_cdpe_ia_<TIMESTAMP>. If analyzing a module repo, temporary branches are created in the module repo and in the control repo that is associated with the module repo. The temporary branch serves as temporary environment in which to deploy your new code and detect possible changes.
  2. Deploy code associated with the targeted commit SHA in the temporary branch.
  3. Calculate module version changes by comparing module deployment data from the target environment and the temporary environment.
  4. Calculate changes to Hiera parameters. If Hiera regex is configured, Continuous Delivery for PE uses the regex to locate Hiera files. Otherwise, it looks for changes in Hiera files ending with .yaml in the data or hieradata directories.
  5. Calculate impacted nodes:
    1. Query PuppetDB for nodes that contain resources where the file parameter matches one of the modified module versions or Hiera files. Module versions are queried as a file path to the module.
    2. Query PuppetDB for catalog input data matching modified Hiera parameters.
  6. Calculate impacted node resources:
    1. Query PuppetDB to get the current catalog for each impacted node.
    2. Use the code deployed to the temporary environment to compile a new catalog for each impacted node.
    3. For each impacted node, compare the new (temporary environment) catalog to the current (live environment) catalog.
    4. Build the impact analysis report based on the discovered differenced between the catalogs.
  7. Report the impacted nodes and resources.

Add impact analysis to a control repo pipeline

If you add an impact analysis task to your control repo pipeline, an impact analysis report is automatically generated each time the pipeline runs and your specified conditions are met.

Before you begin
  1. Configure impact analysis.
  2. Construct a pipeline for your module that includes at least one deployment.

Each pipeline can have unlimited impact analysis tasks, but each stage in a pipeline can have only one impact analysis task. Additionally, an impact analysis task cannot be in the same stage as a deployment task.

This section explains how to add an impact analysis step to a pipeline constructed in the web UI. If you manage your pipelines with code, go to .cd4pe.yaml file structure for guidance on adding impact analysis steps to your pipelines.

  1. In the Continuous Delivery for PE web UI, click Control repos, and click the name of the control repo you want to add impact analysis to.
  2. Select the pipeline you want to add the impact analysis step to. Make sure the pipeline has at least one deployment step, because impact analysis is calculated based on the pipeline's deployment conditions.
  3. Identify the stage you want to add the impact analysis step to. The stage must not contain a deployment step, and we recommend choosing a stage before any deployment stages or PR gates.
  4. In your chosen stage, click More actions , select Add item to stage, and select Impact analysis.
  5. Optional: Set the catalog compilation batch size. By default, Continuous Delivery for PE compiles 10 catalogs at a time when performing an impact analysis task.
    Tip: If your compilers are hitting capacity when performing an impact analysis, lower this number. However, lowering this number increases the impact analysis run time.
  6. Determine the environments you want to generate an impact analysis report for.
    • Run for all environments in the pipeline runs impact analysis on all environments used by all deployments in the pipeline.
    • Run for selected environments runs impact analysis on specific environments. Select the relevant environments from among those used by the pipeline's deployments.
  7. Click Add impact analysis.
Results
Impact analysis is now enabled for this control repo pipeline. An impact analysis report is generated each time the pipeline runs.

Add impact analysis to a module pipeline

If you add an impact analysis task to your module pipeline, an impact analysis report is automatically generated each time the pipeline runs and your specified conditions are met.

Before you begin
  1. Configure impact analysis.
  2. Construct a pipeline for your module that includes at least one deployment.

Each pipeline can have unlimited impact analysis tasks, but each stage in a pipeline can have only one impact analysis task. Additionally, an impact analysis task cannot be in the same stage as a deployment task.

This section explains how to add an impact analysis step to a pipeline constructed in the web UI. If you manage your pipelines with code, go to .cd4pe.yaml file structure for guidance on adding impact analysis steps to your pipelines.

  1. In the Continuous Delivery for PE web UI, click Modules, and click the name of the module you want to add impact analysis to.
  2. Select the pipeline you want to add the impact analysis step to. Make sure the pipeline has at least one deployment step, because impact analysis is calculated based on the pipeline's deployment conditions.
  3. Identify the stage you want to add the impact analysis step to. The stage must not contain a deployment step, and we recommend choosing a stage before any deployment stages or PR gates.
  4. In your chosen stage, click More actions , select Add item to stage, and select Impact analysis.
  5. Optional: Set the catalog compilation batch size. By default, Continuous Delivery for PE compiles 10 catalogs at a time when performing an impact analysis task.
    Tip: If your compilers are hitting capacity when performing an impact analysis, lower this number. However, lowering this number increases the impact analysis run time.
  6. Select the environments you want to generate an impact analysis report for.
  7. For each selected environment, choose the control repo where the code associated with that environment is stored.
  8. Click Add impact analysis.
Results
Impact analysis is now enabled for this module pipeline. An impact analysis report is generated each time the pipeline runs.

Generate an impact analysis report on demand

Without triggering a pipeline, you can generate an impact analysis report for any commit made to a control repo or module that Continuous Delivery for Puppet Enterprise (PE) monitors.

Before you begin
Configure impact analysis.
  1. In the Continuous Delivery for PE web UI, navigate to the control repo or module you want to generate an impact analysis report for.
  2. Click Manual actions and select New impact analysis.
  3. Select the branch where the code you want to analyze is located, and then select the commit containing the changes you want to analyze.
  4. Select the PE instance that manages the nodes you want to analyze, and select the specific node group.
    • For control repo impact analysis, select an environment prefix, if applicable.
    • For module impact analysis, select the control repo where the module's environment code is deployed.
  5. Set the number of node catalogs to compile concurrently. Lower numbers can have a lesser impact on performance but take longer to complete the impact analysis.
  6. Click Analyze, nnd wait while the report generates. It may take several minutes for large node groups.
  7. Once the analysis is complete, click View impact analysis to access the report.
    Tip: Click Export on the report page to get a CSV file containing the impact analysis report's data.