Getting started with Continuous Delivery for PE

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

First, use the main documentation to install Continuous Delivery for PE.

Follow the instructions in Install Continuous Delivery for PE.

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.

  1. 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.
  2. Create your user account.
    1. On the login page, click Create an account.
    2. Fill in the registration form and create a username and password.
    3. 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.
  3. Set up a workspace.
    1. On the Choose a workspace screen, click + Add new workspace.
    2. 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.

  1. Follow our Integrate with Puppet Enterprise instructions.
  2. Follow the Configure impact analysis instructions.
  3. Select your source control system from the list below and follow the integration instructions:
  4. Optional. To make sure you're always running the latest available version of the software, install the puppetlabs-cd4pe module to automate upgrades of Continuous Delivery for PE.

Step 4: 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.

  1. Install a Puppet agent on the node you plan to use as job hardware. See Installing agents in the PE documentation for details.
  2. Make sure your Continuous Delivery user role in PE includes the permission to run the cd4pe_jobs::run_cd4pe_job task.
  3. Install the puppetlabs-cd4pe_jobs module, which is required to run Continuous Delivery for PE jobs on your node:
    1. Add the puppetlabs-cd4pe_jobs module to the following:
      • 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 master branch of the control repo you added to Continuous Delivery for PE in step 4
      A sample Puppetfile entry:
      mod 'puppetlabs-cd4pe_jobs', '1.5.0'
    2. Deploy the updated code to the production environment: 
      puppet code deploy production --wait
  4. 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.
  5. 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.
    1. In the Continuous Delivery for PE web UI, click Hardware.
    2. Locate the Docker capability and click + Edit.
    3. Select the PE instance that manages the node you've selected as job hardware. Then, select your job hardware node.
      The selected node is added to the Hardware with this capability list on the right.
    4. Click Save.
Results
Your job hardware node is now configured and ready for use. We'll see it in action during step 8, when we run our pipeline for the first time.

Step 5: 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.

  1. In the Continuous Delivery for PE web UI, click Control repos, then click Add control repo.
  2. Follow the prompts to select your source control, organization, and your chosen repository.
  3. 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.
  4. Optional: Edit the name of your new control repo.
    Tip: The control repo name must contain only alphanumeric characters, dashes, and underscores.
  5. 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.

  1. In the Continuous Delivery for PE web UI, click Control repos. Click the name of the control repo you added in Step 5.
  2. On the right side of the web UI, you'll see the space where we'll create your pipeline. Click + Add default pipeline.
  3. 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.

  1. In your Git repository, create a new branch called cd4pe_testing. This will represent the environment node group.
  2. On your master, run puppet code deploy cd4pe_testing.
  3. In the PE console, click Classification.
  4. Click Add group... and create a new node group with the following specifications:

    • Parent name: All Environments

    • Group name: CD4PE test group

    • Environment: cd4pe_testing

    • Environment group: yes

    • Description: Node group used for Continuous Delivery for PE testing

    Click Add.

  5. In the list of node groups, click 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.

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.

  1. In the Continuous Delivery for PE web UI, in your control repo's pipeline, click Add a deployment.
  2. Select your PE instance, then select the CDPE test group node group we created in Step 7.
  3. Select the Direct deployment policy. Don't worry about setting special conditions for this deployment.
  4. Click Add deployment to stage. On the confirmation screen, click Done.
  5. 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.
Results
When triggered by your commit, the pipeline automatically runs tests on your code, skips over the impact analysis stage that we haven't yet set up, and stops, as the pipeline is set up not to autopromote into the Deployment stage. Click Promote to continue the pipeline run and launch the deployment. The results of the pipeline run are logged in the Events area on the left of the screen.

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.

  1. 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
  2. On the feature branch, make a code change, such as updating a package version.
  3. Commit the change on the feature branch and then return to the Continuous Delivery for PE web UI.
  4. In the Continuous Delivery for PE web UI, click Manual actions and select New impact analysis.
  5. 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.
  6. 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.
  7. 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.
Results

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.