Migrating Bolt tasks and plans to PE

If you use Bolt tasks and plans to automate parts of your configuration management, you can move that Bolt content to a control repo and transform it into a Puppet Enterprise (PE) environment. This lets you manage and run tasks and plans using PE and the console. Bolt projects have the same structure as Puppet modules, and they can be loaded from the modules directory of a PE environment.

The control repo is a central Git repository from which PE fetches content. An environment is a space for PE authors to write and install content, similar to a Bolt project.

There are two ways to get your Bolt content into an environment:

  • Move your Bolt code to a new control repo. Do this if you have a Boltdir, or an embedded project directory, in a repo that also contains other code that you do not want to migrate to PE.
  • Configure PE to point to the Bolt project. Do this is if you have a dedicated repo for Bolt code, or a local project directory, and don't want to duplicate it in PE.

Move Bolt content to a new PE repo

Move your Bolt project content out of your Boltdir and into a fresh PE control repo.

Before you begin
To move Bolt content to a repo:
  1. Commit the contents of your Bolt project to a branch of your PE control repo. Place the Bolt project under the modules directory. If you're using Bolt module workflows, make sure you run bolt module install and commit the resulting Puppetfile to your control repo.
    Your new structure is similar to a project directory in Bolt, for example: 
    test-environment/
├── Puppetfile
├── bolt-project.yaml
├── data
│   └── common.yaml
├── inventory.yaml
└── modules
    └── project
        ├── manifests
        │   └── my_class.pp
        ├── plans
        │   ├── deploy.pp
        │   └── diagnose.pp
        └── tasks
            ├── init.json
            └── init.py
  2. Create a configuration file called environment.conf and add it to the root directory of the branch. This file configures the environment in PE.
  3. Add the modulepath setting to the environment.conf file by adding the following line: 
    modulepath = modules:modules:$basemodulepath
    Note: PE picks up modules only from the modules directory. It's important to add modules to the modulepath setting so it matches the defaults for your Bolt project. If you have a modulepath setting in bolt-project.yaml, match it to the modulepath setting in environment.conf.
  4. Publish the branch to the PE control repo.
  5. Deploy code using puppet code deploy --<ENVIRONMENT>, where <ENVIRONMENT> is the name of your branch, to commit the new branch to Git.
    Note: You can also deploy code using a webhook. See Triggering Code Manager with a webhook for more information.
Results
After you deploy code, modules (and the tasks and plans within them) listed in the new environment's Puppetfile are available to use in PE.

Point PE to a Bolt project

Allow PE to manage content in your dedicated Bolt repo.

Before you begin

To point PE to your Bolt content:

  1. To allow access to the control repo, generate a private SSH key without a password:
    1. To generate the key pair, run: 
      ssh-keygen -t ed25519 -P '' -f /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519
    2. To allow the pe-puppet user to access the key, run: 
      puppet infrastructure configure
      Your private key is located at /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519, and your public key is at /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519.pub.
    3. Configure your Git host to use the SSH public key you generated. Usually, this involves creating a user or service account and assigning the SSH public key to it, but the exact process varies for each Git host. For instructions on adding SSH keys to your Git server, check your Git host's documentation (such as GitHub, BitBucket Server, or GitLab).
      Important: Code management needs read access to your control repository, as well as any module repositories referenced in the Puppetfile.
  2. Change the name of your branch to production. PE uses branches in Git as environments and the default environment is production.
  3. Create a configuration file called environment.conf and add it to the root directory of the branch. This file configures the environment.
  4. Add the modulepath setting to the environment.conf file by adding the following line: 
    modulepath = modules:modules:$basemodulepath
    Note: PE picks up modules only from the modules directory. It's important to add modules to the modulepath setting so it matches the defaults for your Bolt project. If you have a modulepath setting in bolt-project.yaml, match it to the modulepath setting in environment.conf.
  5. Publish the branch to the PE control repo.
  6. Deploy code using puppet code deploy --<ENVIRONMENT>, where <ENVIRONMENT> is the name of your branch, to commit the new branch to Git.
    Note: You can also deploy code using a webhook. See Triggering Code Manager with a webhook for more information.
Results
After you deploy code, modules (and the tasks and plans within them) listed in the new environment's Puppetfile are available to use in PE.

PE workflows for Bolt users

Understand the differences between PE and Bolt commands and workflows before you start running tasks and plans in PE.

Connecting to nodes

You must connect PE to each node you want to run tasks on or include in a plan. See Add nodes to the inventory for instructions on adding agent or agentless nodes to your inventory.

Installing tasks and plans

In PE, as in Bolt, you use the mod command to download modules. But instead of running the bolt puppetfile install command to install them, you trigger Code Manager and deploy code using the puppet code deploy command. See Triggering Code Manager on the command line.

Running tasks and plans

PE does not recognize the bolt command for running tasks and plans. Instead, use the puppet task run and puppet plan run commands, or use the console.

To run tasks or plans from the command line, see:
To run tasks or plans from the console, see:

Limitations in PE

Not everything in Bolt works in PE. For example, many pre-installed Bolt modules are not included in PE and many plan functions do not work, such as file::exists and set_feature. See Plans in PE versus Bolt plans.