Getting started guide
If you're using Continuous Delivery for Puppet Enterprise (PE) for the first time, you'll need to perform some initial workspace setup tasks and learn how to use the core features.
Soon, you'll have a more streamlined, powerful, and flexible Puppet code delivery process.
Part 1: Install Puppet Application Manager and deploy Continuous Delivery for PE
First, install Puppet Application Manager (PAM) and then configure and deploy Continuous Delivery for Puppet Enterprise (PE).
- Make sure your system meets the PAM system requirements.
- Follow the instructions for your environment to Install PAM.
- Deploy Continuous Delivery for PE.
Part 2: Create your user account and set up a workspace
If Continuous Delivery for Puppet Enterprise (PE) were a city, workspaces would be neighborhoods within that city. Your workspace is where you store and access resources such as control repos, pipelines, and jobs. When you're ready to collaborate, you can invite team members to join your workspace.
If you have not done so already, navigate to the Continuous Delivery for PE web UI URL (
https://<HOSTNAME>) you received at the end of Part 1.
Create your personal user account.
- On the login page, click Create an account.
- Fill in the registration form and create a username and password.
Click Sign Up.
Note: For almost all tasks you'll perform in Continuous Delivery for PE, you'll use your individual user account, not the root account. You only use the root account for special administrative tasks such as installation, designating super users, and deleting users.
Set up a workspace.
- On the Choose a workspace screen, click Add new workspace.
- Enter a name for your workspace and click Create workspace.
Part 3: Set up integrations
Next, integrate with your Puppet Enterprise (PE) instance and the source control system where you keep your Puppet code.
- Follow the instructions to Integrate with Puppet Enterprise.
- Follow the instructions to Configure impact analysis.
- Follow the integration instructions for your source control system:
Part 4: Configure job hardware
Configure a node running a Puppet agent to be a job hardware server, where your code is tested before deployments.
- Install a Puppet agent on the node you plan to use as job hardware. Instructions for Installing agents are in the Puppet Enterprise (PE) documentation.
Make sure your Continuous Delivery user role
in PE has permission to run the
puppetlabs-cd4pe_jobsmodule from the Forge, which is required to run Continuous Delivery for PE jobs on your node.
A sample Puppetfile entry:
- The Puppetfile for the production environment on the PE primary server that manages the agent node you've selected as job hardware.
- The Puppetfile on the main branch of the control repo you will add to Continuous Delivery for PE in Part 5.
mod 'puppetlabs-cd4pe_jobs', '1.6.0'Tip: Visit the PE documentation for more information about Managing environment content with a Puppetfile.
puppet code deploy production --waitto deploy the updated code to the production environment.
- Add the
- The job hardware server must be able to use the pre-built jobs included in Continuous Delivery for PE. Since these jobs are Docker-based, you must install and configure Docker on the node. You can find installation files and instructions on the Docker website.
Tell Continuous Delivery for PE that this node is ready to be used as
job hardware for Docker-based jobs by assigning
it to a hardware capability. Capabilities organize your job hardware servers and
ensure that jobs run on hardware with the right characteristics. Continuous Delivery for PE automatically creates a
Docker hardware capability for you.
- In the Continuous Delivery for PE web UI, click Hardware.
- Locate the Docker capability and click Edit.
- Select the PE instance that manages the node you've selected as job hardware, and then select your job hardware node. The selected node appears in the Hardware with this capability list.
- Click Save.
Part 5: Add a control repo
A control repo in Continuous Delivery for Puppet Enterprise (PE) tracks the changes made
on the active development branch of your source control system. When adding a control repo
to Continuous Delivery for PE, it's important to connect the
Adding a repo in Continuous Delivery for PE configures a webhook to the repository in your source control system. The webhook reports new commit activity on the repository to Continuous Delivery for PE, enabling you to track code changes and take action (such as triggering pipelines or running individual tests on the new code).
- In the Continuous Delivery for PE web UI, click Control repos and then click Add control repo.
- Select the source control provider and repository.
mainbranch is automatically selected, if one exists. If your control repo does not have a
mainbranch, select Create a main branch from an existing branch and select your active development branch as the basis for the new
mainbranch. Continuous Delivery for PE creates a
mainbranch for you based on the existing branch you choose.CAUTION: When working with Continuous Delivery for PE, only commit to the
mainbranch and any feature branches (which are eventually merged back into the
mainbranch). Do not push code changes to any other Git branches; this can create conflicts with Continuous Delivery for PE workflows.
- Optional: Edit the control repo's Display name name as it appears in the Continuous Delivery for PE web UI. The name can contain only numbers, letters, dashes, and underscores.
- Click Add control repo. The control repo appears in the list on the Control repos page.
Make sure you have added the
puppetlabs-cd4pe_jobsmodule to the Puppetfile on the
mainbranch of your control repo, as explained in Part 4.
Part 6: Set up a pipeline
Continuous Delivery for Puppet Enterprise (PE) pipelines are made up of stages and tasks. Tasks include jobs to test code, deployments, and impact analysis. Stages group tasks into a series of sequential phases.
- In the Continuous Delivery for PE web UI, click Control repos and click the name of the control repo you added in Part 5.
- You'll create a pipeline in the Pipelines section of the page. Click Add default pipeline.
- The Code validation stage includes two tasks (jobs to test Puppet code).
- The Impact analysis stage includes an impact analysis task with a pull request gate (more on this later).
- The Deployment stage, which is where you'll add deployment instructions in Part 8.
Part 7: Set up an environment node group
Next, set up a small environment node group to use for deployment testing and to demonstrate how Continuous Delivery for Puppet Enterprise (PE) deploys new code to PE-managed nodes.
You can learn more About environments in the Puppet documentation and learn about Managing environments with a control repository in the PE documentation.
- In your Git repository, create a new branch called cd4pe_testing. This represents the environment node group for the test.
On your PE primary server, run:
puppet-code deploy cd4pe_testingTip: For more information about the
puppet-codecommand, read about Triggering Code Manager on the command line in the PE documentation. You can also use webhooks and scripts to trigger deployments.
- In the PE console, click Node groups.
Click Add group and create a new node group with these
- Parent name: Select All Environments
- Group name: Enter CD4PE test group
- Environment: Select cd4pe_testing
- Environment group: Select this option.
- Description: Enter any description, such as For Continuous Delivery for PE testing.
- Click Add.
In the node groups list, click your new CD4PE test
group. In the Rules tab, pin two or three
test nodes to the node group. Make sure these nodes are not assigned to any
other node groups in your PE installation.
For more information, refer to Add nodes to a node group in the PE documentation.
Part 8: Deploy changes to your nodes
Once you've added a deployment to your pipeline, you can automatically move code changes to your nodes according the deployment conditions you've set.
- In the Continuous Delivery for PE web UI, in your control repo's pipeline, click Add a deployment.
- Select your PE instance and then select the CD4PE test group node group you created in Part 7.
- Select Direct deployment policy. Don't set special conditions for this deployment.
- Click Add deployment to stage. On the confirmation screen, click Done.
- To trigger the deployment, you need to create a change to pass through to production. On the main branch of your Git repository, make a code change, such as updating a package version. Commit the change and then return to the Continuous Delivery for PE web UI to watch your pipeline in action.
Part 9: Create an impact analysis report
Impact analysis reports show the potential impact that new Puppet code will have on the nodes and resources you're managing with Puppet Enterprise (PE). In Continuous Delivery for PE, you can add impact analysis tasks to your pipelines and you can generate impact analysis reports on demand.
Here, you'll generate an on-demand impact analysis report to review how a change impacts the nodes in the CD4PE test group node group you created in Part 7.
Create a change for the report to analyze.
- In your Git repository, create a feature branch from your main branch.
- Make a code change on the feature branch, such as updating a package version.
- Commit the change on the feature branch.
- In the Continuous Delivery for PE web UI, click Manual actions and select New impact analysis.
- In the New impact analysis window, select your feature branch, and select your new commit. Select your PE instance and the CD4PE test group node group.
Click Analyze to generate the report.
Continuous Delivery for PE generates a new catalog containing your commit and compares this new catalog to the current catalog for the nodes in the CD4PE test group.
- Click View impact analysis. The report shows how the change on your feature branch would impact your nodes and resources if you merged it into the main branch.
Congratulations! By completing the getting started guide for Continuous Delivery for PE, you've become familiar with some of Continuous Delivery for PE's core features, and you have a basic understanding of how Continuous Delivery for PE helps you deploy Puppet code and preview the impact of code changes.