Greetings! Welcome to Continuous Delivery for PE. If you're trying out the software for the first time, this getting started guide is for you. As a new user, you'll need to perform some initial workspace setup tasks, and then we'll show you how to begin using core features of Continuous Delivery for PE.
You're just a few steps away from a more streamlined, powerful, and flexible Puppet code delivery process. Ready to get started?
Step 1: Install Continuous Delivery for PE
We'll start by installing Continuous Delivery for PE directly from the PE console.
- In the PE console, click Integrations.
In the Continuous Delivery for PE host field, enter the
name of the node where you wish to install Continuous Delivery for PE.
Note: This node must be running Enterprise Linux 7, and must have a PE version in the 2019.x series installed.
- In the Administrator email field, enter an email address for the Continuous Delivery for PE administrator, also known as the root user. This email address is used as your username when signing in to Continuous Delivery for PE as the root user.
- In the Administrator password field, enter a strong password for the Continuous Delivery for PE administrator account.
Click Install to perform a default installation of Continuous Delivery for PE.
Important: Your Puppet certificate name must be a resolvable DNS hostname.
- When the job is complete, navigate to the URL printed on the task page. Click Trial Mode to start a free seven-day trial.
Step 2: Create your user account and set up a workspace
Think of a workspace like a neighborhood within the Continuous Delivery for PE 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 the members of your team to join your workspace.
- If you haven't already done so, navigate to the Continuous Delivery for PE web UI address you received at the end of the installation process in Step 1.
Create your 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. The root account is only used 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.
Step 3: Set up integrations
Next, it's time to set up integrations with your PE instance and the source control system where you keep your Puppet code.
We're sending you to our integration docs to complete these tasks.
- Follow our Integrate with Puppet Enterprise instructions.
- Follow the Configure impact analysis instructions appropriate to your version of PE.
- Select your source control system from the list below and follow the integration instructions:
- Optional. To make sure you're always running the latest available version of the
software, install the
puppetlabs-cd4pemodule to automate upgrades of Continuous Delivery for PE.
Step 5: Configure job hardware
You'll now configure a node running a Puppet agent as a job hardware server, where your code will be tested before deployments.
- Install a Puppet agent on the node you plan to use as job hardware. See Installing agents in the PE documentation for details.
Make sure your Continuous Delivery user
role in PE includes the permission to
puppetlabs-cd4pe_jobsmodule, which is required to run Continuous Delivery for PE jobs on your node:
puppetlabs-cd4pe_jobsmodule to the following:
A sample Puppetfile entry:
- The Puppetfile for the production environment on the PE master that manages the agent node you've selected as job hardware
- The Puppetfile on the
masterbranch of the control repo you added to Continuous Delivery for PE in step 4
mod 'puppetlabs-cd4pe_jobs', '1.0.0'
Deploy the updated code to the production environment:
puppet code deploy production --wait
- Add the
- We want this job hardware server to 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. See the Installing Docker instructions for details.
Finally, 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. Then, select your job hardware
The selected node is added to the Hardware with this capability list on the right.
- Click Save.
Step 4: Add a control repo
A control repo in Continuous Delivery for 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 master Git branch.
When you set up your new control repo, Continuous Delivery for PE adds a webhook to the associated 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.
- In the Continuous Delivery for PE web UI, click Control Repos, then click Add Control Repo.
- Follow the prompts to select your source control, organization, and your chosen repository.
The master branch of your repository is automatically selected for you. If your
control repo does not currently contain a master branch, follow the prompts to
let Continuous Delivery for PE create one for you, and select the branch
that's under active development to create the master branch from.
Important: When working with Continuous Delivery for PE, commit only to the master branch and to any feature branches (which are eventually merged back into the master branch). Do not push code changes to any of your other Git branches, as doing so can create conflicts with Continuous Delivery for PE workflows.
Edit the name of your new control repo.
Tip: The control repo name must contain only alphanumeric characters, dashes, and underscores.
- Click Add. The control repo is now shown in the master list on the Control Repos page.
Step 6: Set up a pipeline
Pipelines in Continuous Delivery for PE 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. Click the name of the control repo you added in Step 5.
- On the right side of the web UI, you'll see the space where we'll create your pipeline. Click + Add default pipeline.
Your default pipeline is automatically created for your master branch. This
pipeline contains three stages:
- The Code Validation stage includes two jobs (tests for Puppet code).
- The Impact Analysis stage includes an impact analysis task with a pull request gate (more on this later).
- The Deployment stage, where we'll add deployment instructions in step 8.
Step 7: Set up an environment node group
To give us a place to demonstrate how Continuous Delivery for PE deploys new code to your Puppet Enterprise- managed nodes, we'll next set up a small environment node group to use for deployment testing.
- In your Git repository, create a new branch called cd4pe-testing. This will represent the environment node group.
On your master, run
puppet code deploy cd4pe-testing.
- In the PE console, click Classification.
Click Add group... and create a new node group with the
Parent name: All Environments
Group name: CD4PE test group
Environment group: yes
Description: Node group used for Continuous Delivery for PE testing
- In the list of node groups, click CDPE 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.
Step 8: Deploy changes to your nodes
Once you've added a deployment to your pipeline, you can automatically move code changes to your nodes following 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, then select the CDPE test group node group we created in Step 7.
- Select the Direct Deployment Policy. Don't worry about setting special conditions for this deployment.
- Click Add Deployment to Stage. On the confirmation screen, click Done.
- Now we need a change to pass through to production. In your Git repository, on the master branch, 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.
Step 9: Create an impact analysis report
An impact analysis report shows the potential impact that new Puppet code will have on the nodes and resources you're managing with PE. You can add impact analysis tasks to your pipeline, and you can generate impact analysis reports on demand, as we'll do in this step.
- First, create a change for the report to analyze. We'll generate an impact analysis report to review how this change impacts the nodes in your CDPE test group. In your Git repository, create a feature branch from your master branch
- On the feature branch, make a code change, such as updating a package version.
- Commit the change on the feature branch and then return to the Continuous Delivery for PE web UI.
- 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, then select the commit you just made. Select your PE instance and the CDPE test group node group.
Click Analyze to generate the report.
Continuous Delivery for PE will now generate a new catalog containing your commit, and will compare this new catalog to the current catalog of the nodes in the CDPE test group.
- Click View Impact Analysis. The report shows how the change on your feature branch would impact your nodes and resources if it was merged to the master branch.
Congratulations! You've reached the end of this introductory guide. You're now familiar with some of the core features of Continuous Delivery for PE, and have a basic understanding of how the software helps you deploy Puppet code and preview the impact of changes.