Built-in deployment policies

Deployment policies are prescriptive workflows for deploying Puppet code that are built into Continuous Delivery for Puppet Enterprise (PE).

When you set up a code deployment, you select the best deployment policy for your situation, and then Continuous Delivery for PE does all the Git heavy lifting to deploy your code to the correct nodes.

Deployment policies can't be triggered on their own. You specify which policy to use when you Deploy code manually or Deploy code automatically with a pipeline. When you set up a deployment, you also specify a repository, branch, commit, environment, or other parameters that determine where to deploy your code, which version of your code to deploy, and how and where the deployment policy operates.

Deployment policy comparison

Continuous Delivery for Puppet Enterprise (PE) has four built-in deployment policies, each with a different branching workflow. The following table compares the deployment policy options to help you select the best policy for your circumstances.

Deployment policy Description Use cases
Direct deployment policy Deploy code to one node group.
  • Small or trivial changes
  • Changes that you are confident aren't going to cause issues when deployed
  • Deploying a specific commit to one environment
Temporary branch policy Create a temporary environment and then deploy code to batches of nodes. You can monitor the outcome of each batch.
  • Fully-tested changes
  • Validating changes by deploying to a temporary test environment
  • Workflows that don't require extensive historical data logging
Eventual consistency policy Deploy new code and allow nodes to pick up the new code at their regular Puppet run intervals, rather than forcing the change through an immediate orchestrator job.
  • Fully-tested changes
  • Large PE installations that have regularly-scheduled Puppet runs
  • When running additional orchestrator jobs is undesirable
Feature branch deployment policy Deploy code from a feature branch to a dedicated feature branch environment.
Restriction: Only available for regex branch pipelines.
Custom deployment policies Use Bolt plans to create a unique policy. You have a special use case that isn't addressed by any of the built-in deployment policies.

Direct deployment policy

The direct deployment policy is the most basic of the four built-in deployment policies. Use this policy when you want to deploy a specific commit to a specific environment, and then use a Puppet run to deploy the change on only that specific environment.


An animation showing how the direct deployment policy deploys a specific commit into an environment, as described below.
When a deployment uses the direct deployment policy, Continuous Delivery for Puppet Enterprise (PE) performs the following actions:
  1. Synchronize code: Using Code Manager, Continuous Delivery for PE synchronizes your selected code change with your PE instance by running puppet-code deploy on Puppet Server.
  2. Create temporary environment node group: Continuous Delivery for PE creates a new environment node group as a child of the node group you selected when setting up the deployment. This new child node group inherits all the rules, configuration settings, and variables of its parent node group. A Puppet Query Language (PQL) query pins all nodes associated with the parent node group to the child node group.
    Note: This environment node group is temporary, and it is automatically deleted after the code deployment. It is unlikely you'll ever interact directly with this environment node group.
  3. Run Puppet: Continuous Delivery for PE uses the orchestrator to start a Puppet run on the nodes in the new environment node group. This Puppet run applies the new code to the nodes as quickly as Puppet Server's concurrency limits allow. You can monitor the Puppet run's progress on the deployment details page in the Continuous Delivery for PE web UI.
  4. Clean-up: After the Puppet run, Continuous Delivery for PE deletes the temporary environment node group and moves the HEAD of the target branch (in your source control repository) to the commit you chose to deploy.

Direct deployment policy parameters

You can use the following optional parameters to customize your direct deployment. In the web UI, you can set these parameters when configuring a pipeline or manual deployment that uses the direct deployment policy. For pipelines-as-code, you can add these parameters to the your .cd4pe.yaml file as part of a type: deployment step declaration.
Parameter Type Description Default value
max_node_failure Integer The maximum number of nodes that can fail before the deployment is stopped and reported as a failure. Empty (unlimited nodes can fail)
noop Boolean Indicates whether to perform the Puppet run in no-op mode. false
fail_if_no_nodes Boolean Indicates whether to stop the deployment and report a failure if the selected node group does not contain any nodes. false

Temporary branch policy

When a deployment uses the temporary branch policy, Continuous Delivery for Puppet Enterprise (PE) creates a temporary Git branch (that contains the Puppet code you want to deploy) and a temporary environment node group (that contains the nodes you want to deploy the code to). The new code is then deployed to the nodes in the temporary environment node group in batches. This allows you to monitor the outcome of each batch and be certain that your new code works with each node before deploying the changes to the actual environment.


An animation showing how a temporary branch policy deploys code into a temporary environment, then to the actual environment, as described below.
When a deployment uses the temporary branch policy, Continuous Delivery for PE performs these actions:
  1. Create a temporary branch: Based on the commit you selected, Continuous Delivery for PE creates a new, temporary branch named rolling_deployment_<ID> in your source control repository.
    Note: This branch is temporary, and it is automatically deleted after the code deployment. You'll probably never directly interact directly with temporary branches.
  2. Synchronize code: Using Code Manager, Continuous Delivery for PE synchronizes your code change with your PE instance by running puppet-code deploy on Puppet Server.
  3. Create a temporary environment node group: Continuous Delivery for PE creates a new, temporary environment node group as a child of the node group you selected when setting up the deployment. This new child node group inherits all the rules, configuration settings, and variables of its parent node group. A Puppet Query Language (PQL) query pins all nodes associated with the parent node group to the child node group.
    Note: This environment node group is temporary, and it is automatically deleted after the code deployment. You'll probably never directly interact with temporary environment node groups.
  4. Run Puppet: Continuous Delivery for PE uses the PE orchestrator to run Puppet on the nodes in the new environment node group. Puppet runs on a few nodes at a time, based on the stagger settings you specified when setting up the deployment. You can monitor each Puppet run's progress on the deployment details page in the Continuous Delivery for PE web UI.
  5. Clean up: After all Puppet runs end, Continuous Delivery for PE deletes the temporary environment node group, moves the HEAD of the target branch (in your source control repository) to point to your chosen commit, and deletes the temporary Git branch that was created at the beginning of this process.

Temporary branch deployment policy parameters

You can use the following optional parameters to customize your temporary branch deployment. In the web UI, you can set these parameters when configuring a pipeline or manual deployment that uses the temporary branch deployment policy. For pipelines-as-code, you can add these parameters to the your .cd4pe.yaml file as part of a type: deployment step declaration.
Parameter Type Description Default value
batch_delay Integer How many seconds to wait between each deployment batch. 60
batch_size Integer How many nodes to include in each deployment batch. 10
max_node_failure Integer The maximum number of nodes that can fail before the deployment is stopped and reported as a failure. Empty (unlimited nodes can fail)
noop Boolean Indicates whether to perform the Puppet runs in no-op mode. false
fail_if_no_nodes Boolean Indicates whether to stop the deployment and report a failure if the selected node group or target environment does not contain any nodes. true

Eventual consistency policy

Use the eventual consistency policy to deploy new Puppet code that nodes can pick up during their next scheduled check-in, rather than immediately applying the changes with a dedicated Puppet run. With this policy, the impacted nodes pick up the new code over time and eventually all become consistent with the new code.

CAUTION: If you have nodes with infrequent check-in schedules, deployments using the eventual consistency policy can take a long time to reach those nodes. If you need code changes applied more rapidly, consider using the Temporary branch policy or Direct deployment policy.
When a deployment uses the eventual consistency policy, Continuous Delivery for Puppet Enterprise (PE) performs the following actions:
  1. Synchronize code: Using Code Manager, Continuous Delivery for PE synchronizes your selected code change with your PE instance by running puppet-code deploy on Puppet Server.
  2. Apply changes during scheduled Puppet runs: Rather than using the orchestrator to start a Puppet run to specifically deploy the new code, the code is distributed to nodes over time. The new code is delivered to each impacted node according to their regular check-in schedule.

Eventual consistency deployment policy parameters

There are no additional parameters associated with the eventual consistency deployment policy.

Feature branch deployment policy

The feature branch deployment policy deploys code changes you've made on a feature branch to a Puppet environment with the same name as the feature branch.

Restriction: The feature branch deployment policy is only available for regex branch pipelines.

When a deployment in a regex branch pipeline uses the feature branch deployment policy, Continuous Delivery for Puppet Enterprise (PE) deploys code to the feature branch environment. Using Code Manager, Continuous Delivery for PE deploys the commit in the pipeline to a Puppet environment with the same name as the feature branch that triggered the pipeline run. If an environment with the feature branch's name doesn't already exist, Continuous Delivery for PE creates this environment during the deployment.

Feature branch deployment policy parameters

There are no additional parameters associated with the feature branch deployment policy.