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).

  1. Make sure your system meets the PAM system requirements.
  2. Follow the instructions for your environment to Install PAM.
  3. 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.

  1. 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.
  2. Create your personal 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. You only use the root account 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.

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.

  1. 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.
  2. Make sure your Continuous Delivery user role in PE has permission to run the cd4pe_jobs::run_cd4pe_job task.
  3. Install the puppetlabs-cd4pe_jobs module from the Forge, which is required to run Continuous Delivery for PE jobs on your node.
    1. Add the puppetlabs-cd4pe_jobs module to:
      • 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.
      A sample Puppetfile entry:
      mod 'puppetlabs-cd4pe_jobs', '1.6.0'
      Tip: Visit the PE documentation for more information about Managing environment content with a Puppetfile.
    2. Run puppet code deploy production --wait to deploy the updated code to the production environment.
  4. 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.
  5. 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, and then select your job hardware node. The selected node appears in the Hardware with this capability list.
    4. Click Save.
Results
Your job hardware node is configured and ready for use. You'll use it in Part 8 when you run your pipeline for the first time.

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 main Git branch.

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).

  1. In the Continuous Delivery for PE web UI, click Control repos and then click Add control repo.
  2. Select the source control provider and repository.
  3. Your repository's main branch is automatically selected, if one exists. If your control repo does not have a main branch, select Create a main branch from an existing branch and select your active development branch as the basis for the new main branch. Continuous Delivery for PE creates a main branch for you based on the existing branch you choose.
    CAUTION: When working with Continuous Delivery for PE, only commit to the main branch and any feature branches (which are eventually merged back into the main branch). Do not push code changes to any other Git branches; this can create conflicts with Continuous Delivery for PE workflows.
  4. 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.
  5. Click Add control repo. The control repo appears in the list on the Control repos page.
  6. Make sure you have added the puppetlabs-cd4pe_jobs module to the Puppetfile on the main branch 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.

  1. In the Continuous Delivery for PE web UI, click Control repos and click the name of the control repo you added in Part 5.
  2. You'll create a pipeline in the Pipelines section of the page. Click Add default pipeline.
Results
Continuous Delivery for PE automatically creates a default pipeline for your main branch. This pipeline has three stages:
  • 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.

This is only for testing. You can change the configuration later.

You can learn more About environments in the Puppet documentation and learn about Managing environments with a control repository in the PE documentation.

  1. In your Git repository, create a new branch called cd4pe_testing. This represents the environment node group for the test.
  2. On your PE primary server, run: 
    puppet-code deploy cd4pe_testing
    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. In the PE console, click Node groups.
  4. Click Add group and create a new node group with these specifications:
    • 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.
  5. Click Add.
  6. 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.

  1. In the Continuous Delivery for PE web UI, in your control repo's pipeline, click Add a deployment.
  2. Select your PE instance and then select the CD4PE test group node group you created in Part 7.
  3. Select Direct deployment policy. Don't set special conditions for this deployment.
  4. Click Add deployment to stage. On the confirmation screen, click Done.
  5. 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.
Results
When triggered by your commit, the pipeline automatically runs tests on your code, skips over the impact analysis stage (which isn't currently configured), and then stops, because the pipeline is configured to not automatically promote into the Deployment stage. You must click Promote to continue the pipeline run and launch the deployment. The Events section of the page logs the results of the pipeline run.

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.

  1. Create a change for the report to analyze.
    1. In your Git repository, create a feature branch from your main branch.
    2. Make a code change on the feature branch, such as updating a package version.
    3. Commit the change on the feature branch.
  2. In the Continuous Delivery for PE web UI, click Manual actions and select New impact analysis.
  3. 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.
  4. 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.
  5. 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.
Results

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.