Integrate with Puppet Enterprise

To set up an integration between your Puppet Enterprise (PE) instance and Continuous Delivery for PE, you must first set up a dedicated PE user with appropriate permissions, then add your PE instance's credentials to Continuous Delivery for PE.

Before you begin

You must enable Code Manager on the PE instance before integrating with Continuous Delivery for PE. For instructions, see Configure Code Manager.

Do not enable invalid branches in PE. Ensure that the Hiera key puppet_enterprise::master::code_manager::invalid_branches is not set to correct in PE. This is set in the PE console using Node Groups > PE Infrastructure > PE Master > Configuration Data.

The Puppet primary server certificate must have dns_alt_names configured. To confirm your certificate configuration, run:

openssl x509 -in $(puppet config print hostcert) -text |grep -A 1 "Subject Alternative Name"

If this returns no output, you must regenerate the primary server certificate before integrating PE with Continuous Delivery for PE. For instructions, go to Regenerate primary server certificates in the PE documentation.

Important: If your PE instance has a replica configured for disaster recovery, Continuous Delivery for PE is not available if a partial failover occurs. Learn more at What happens during failovers in the PE documentation. To restore Continuous Delivery for PE functionality, you must promote the replica to primary server.

Create a Continuous Delivery user and user role in PE

Create a "Continuous Delivery" user and user role in PE. You'll use this to generate the PE authentication token required during the setup process and to view a centralized log of the activities Continuous Delivery for PE performs on your behalf.

In the PE console, click Access control > Users.
Enter a full name (such as Continuous Delivery User) and a login name (such as cdpe_user) and click Add local user.
Next, create a user role containing the permissions the Continuous Delivery user needs when operating Continuous Delivery for PE. In the PE console, click Access control > User roles.
Enter a name and an optional description for new role, such as CDPE User Role. Then, click Add role.
Select the new user role from the list on the User roles page.

Click Permissions, and assign these permissions to the user role:


Type	Permission	Object
Job orchestrator	Start, stop, and view jobs	-
Node groups	Create, edit, and delete child groups	All
Node groups	View	All
Node groups	Edit configuration data	All
Node groups	Set environment	All
Nodes	View node data from PuppetDB	-
Puppet agent	Run Puppet on agent nodes	-
Puppet environment	Deploy code	All
Puppet Server	Compile catalogs for remote nodes	-
Tasks	Run tasks	At minimum, `cd4pe_jobs::run_cd4pe_job`, which is required when running job hardware using a Puppet agent.

Once all permissions are added, click Commit changes.
Add your Continuous Delivery user to the user role. Click Member users, select the name of the user you created earlier, click Add user, and then commit your change.
Create a password for the Continuous Delivery user.
1. Return to the Users page.
2. Find and click the full name of your Continuous Delivery user, and then click Generate password reset.
3. Follow the password reset link and create a password for the user. You'll use this password when adding your PE credentials to Continuous Delivery for PE.

Results

Your Continuous Delivery user is now configured, has a password, and has the permissions needed to operate Continuous Delivery for PE.

Add your Puppet Enterprise credentials

Establishing an integration with your Puppet Enterprise (PE) instance allows Continuous Delivery for PE to work with PE tools, such as Code Manager and the orchestrator service, to deploy Puppet code changes to your nodes.

If necessary, you can add multiple PE instances to your Continuous Delivery for PE installation.

Make sure you are signed in to your individual Continuous Delivery for PE user account.

Important: Do not perform these steps as the root user. Sign into your individual Continuous Delivery for PE user account before proceeding.
In the Continuous Delivery for PE web UI, click Settings > Puppet Enterprise.
Click Add new integration.
On the Integrate with Puppet Enterprise page, enter a unique, friendly name for your Puppet Enterprise instance.
If you need to work with multiple PE instances within Continuous Delivery for PE, these friendly names help you to differentiate which instance's resources you're managing, so choose them carefully.
Enter the fully qualified domain name (FQDN) you use to access the PE console, such as sample.pe.instance. The FQDN must match the certname of your PE primary server or an alias included in the dns_alt_names entry in your puppet.conf file.
Select Basic authorization or API token and enter the required information.
Important: If SAML is enabled for your Continuous Delivery for PE installation, you must select API token.
- Basic authorization: Enter the username and password for your "Continuous Delivery" user. Continuous Delivery for PE uses this information to generate an API token for you. The username and password are not saved. Optionally, you can change the token's lifetime.
- API token: Use puppet-access or the RBAC v1 API to generate a PE access token for your "Continuous Delivery" user, as explained in Token-based authentication. Paste the token into the API token field.
Tip: To avoid unintended service interruptions, create an access token with a multi-year lifespan.
Click Add integration.
Continuous Delivery for PE uses the information you provide to access the primary SSL certificate generated during PE installation and to look up the endpoints for PuppetDB, Code Manager, orchestrator, and node classifier.
Note: If Continuous Delivery for PE cannot automatically locate the endpoints for your PE services, you are directed to a new page where you can manually enter these credentials. If this happens, go to Manually configure a Puppet Enterprise integration.

Results

Your PE instance is now integrated with Continuous Delivery for PE. You can see integration details on the Puppet Enterprise integrations page. To edit an integration, click More actions > Edit integration.

To enable impact analysis for this instance, see Configure impact analysis.

If you want code deployments to skip unavailable compilers, go to Enable compiler maintenance mode.

To delete an integration, click More actions > Remove integration. You must remove all hardware and pipelines associated with the integration before you can delete the integration itself.

Create environment node groups

For code deployments managed by Continuous Delivery for PE to work correctly, your environment node groups must be set up in a specific hierarchy.

Continuous Delivery for PE deploys changes to environment node groups. Setting up environment node groups allows you to define groups of nodes that you can choose to deploy changes to.

In the PE console, click Node groups.
If there is an Agent-specified environment node group, make sure the All Environments group is that group's parent. The Agent-specified environment node group doesn't have rules and doesn't match any nodes.
Make sure the All Environments group is the parent of the Production environment node group. Make sure the Production environment node group's rules only match production nodes.
For each of your environments (such as development, testing, and staging), deploy an environment branch and create an environment node group:
1. In your control repo, create a Git branch to represent the environment.
2. On your PE primary server, run:
```
puppet-code deploy <ENVIRONMENT_NAME>
```
  Tip: For more information about the puppet-code command, read about Triggering Code Manager on the command line in the PE documentation. You can also use webhooks and scripts to trigger deployments.
3. Click Add group and create a new node group with these specifications:
  - Parent name: Select All Environments.
  - Group name: Enter the environment name. Match the corresponding Git branch name.
  - Environment: Select the name of the environment, which is derived from the corresponding Git branch that you just deployed.
  - Environment group: Select this option.
  - Description: Enter any relevant description.
  Tip: You can learn more About environments in the Puppet documentation and learn about Managing environments with a control repository in the PE documentation.
4. Associate the relevant nodes with the environment group by creating rules or pinning nodes. For more information and instructions, refer to Add nodes to a node group in the PE documentation.
  Follow these best practices for associating nodes with environment node groups:
  - Use the pp_environment trusted fact, or a similar custom fact, to define which environment each node belongs to. Write a rule in each environment group that uses pp_environment or your custom fact to match nodes.
  - See if you can use other facts or trusted facts to create rules that match nodes to one, and only one, environment group.
  - If you can't use trusted facts, custom facts, or other facts to determine node environments, use pinning. Pin each node to only one environment group.
5. Specify the Git branch corresponding to the environment.
Optional: Usually environment node groups do not have children; however there are two scenarios where your environment node groups can have children:
- You want to perform canary testing. Refer to Environment-based testing in the PE documentation for information and instructions.
- You want to Run impact analysis on fewer nodes.

Results

Once you've created an environment node group for each of your environments (represented by Git branches in source control), you'll have a hierarchy of groups starting with All Environments as the parent, a number of direct children equal to the number of environments you have (including Production) plus (if present) an Agent-specified environment. Your environment node groups might have additional children if you configured canary testing or impact analysis groups.

What to do next

After configuring environment node groups, you can deploy new code to your nodes.