Applying Puppet code

Bolt can apply a manifest from a file by passing an absolute path to the manifest:

• *nix shell command

  bolt apply manifests/server.pp --targets servers

• PowerShell cmdlet

  Invoke-BoltApply -Manifest manifests/server.pp -Targets servers

Bolt can apply manifest code directly by passing the code to the execute command-line option:

• *nix shell command

  bolt apply --execute "file { '/etc/puppetlabs': ensure => present }" --targets servers

• PowerShell cmdlet

  Invoke-BoltApply -Execute "file { '/etc/puppetlabs': ensure => present }" -Targets servers

When applying manifest blocks, it's important to understand the distinction between definitions and declarations.

Definitions, which include class definitions and defined resource types, are blocks of Puppet code that can be used when called by name. Defining a class or defined type makes the code available to a catalog, but does not add it to the catalog. A class or defined type that is not called by name, or declared, is not added to the catalog, and thus none of the code in those definitions will be applied to the targets.

When you apply a manifest containing only definitions, Bolt will issue a helpful warning to let you know that the apply will do nothing:

$ bolt apply --execute "define bolt { file { 'etc/puppetlabs': ensure => present } }" --targets servers

Manifest only contains definitions and will result in no changes on the targets.
. . .

📖 Related information

• Defining and declaring classes

• Defining and declaring defined types

Bolt compiles the code in your manifest block into a catalog. Bolt compiles code in the following order:

• Facts gathered from the targets or set in your inventory.

• vars set in your inventory.

Like the code compiled with the puppet apply command, all of the variables are generated. As a result, you can reuse code between Bolt and Puppet. Bolt then copies custom module content from the modulepath to the targets and applies the catalog using Puppet.

After the catalog compiles and is executed successfully on all targets, bolt apply displays the reports generated by applying the catalog on each target.

When you run the command, Bolt will first install required packages and gather facts, apply the catalog compiled from the manifest blocks, and then report a summary of any changes made on the remote systems:

Starting: install puppet and gather facts on target1, target2
Finished: install puppet and gather facts with 0 failures in 3.81 sec
Starting: apply catalog on target1, target2
Started on target1...
Started on target2...
Finished on target1:
  changed: 1, failed: 0, unchanged: 0, skipped: 0, noop: 0
Finished on target2:
  changed: 1, failed: 0, unchanged: 0, skipped: 0, noop: 0
Finished: apply catalog with 0 failures in 4.52 sec
Successful on 2 targets: target1,target2
Ran on 2 targets in 8.42 sec

The apply function supports the following options:

• _catch_errors => true returns a ResultSet including failed results, rather than failing the plan.

• _description => <DESCRIPTION> adds a description to the apply block, allowing you to distinguish apply blocks.

• _noop => true applies the manifest block in Puppet no-operation mode, returning a report of the changes it would make, but takes no action.

• _run_as => <USER> applies the manifest block as the specified user. (This option is for transports that allow a user to run commands under a different username.)

# Preview installing docker as root on $targets.
apply($targets, _catch_errors => true, _noop => true, _run_as => root) {
    include 'docker'
}

Bolt compiles the code in your manifest block into a catalog. Bolt compiles code in the following order:

• Facts gathered from the targets or set in your inventory.

• Local variables from the plan.

• vars set in your inventory.

Like the code compiled with the puppet apply command, all the variables are generated. As a result, you can reuse code between Bolt and Puppet. Bolt then copies custom module content from the Bolt modulepath to the targets and applies the catalog using Puppet.

After the catalog compiles and is executed successfully on all targets, apply returns the reports generated by applying the catalog on each target.

The apply function returns a ResultSet object that contains an ApplyResult object for each target.

$results = apply($targets) { ... }
$results.each |$result| {
   notice($result.report)
}

The ApplyResult object includes a report method that returns a hash representation of the Puppet::Transaction::Report object. Each property on the object corresponds to a key with the same name in the report hash. However, not every property is presented in the hash for every result. Only properties that have a value from the apply are present in the hash.

For example, to access and print the logs from a report in your plan, you can access the logs key in the report hash:

plan example (
  TargetSpec $targets
) {
  # Install the puppet-agent package and gather facts
  $targets.apply_prep

  # Apply Puppet code
  $apply_results = apply($targets) {
    file { '/etc/puppetlabs': 
      ensure => present
    }
  }

  # Print log messages from the report
  $apply_results.each |$result| {
    $result.report['logs'].each |$log| {
      out::message("${log['level'].upcase}: ${log['message']}")
    }
  }
}

Running the above plan prints output similar to this:

$ bolt plan run example --targets server
Starting: plan example
Starting: install puppet and gather facts on server
Finished: install puppet and gather facts with 0 failures in 4.01 sec
Starting: apply catalog on server
Finished: apply catalog with 0 failures in 4.59 sec
INFO: Applying configuration version '1612480754'
INFO: Creating state file /tmp/d20210204-3818-1az3s99/var/state/state.yaml
NOTICE: Applied catalog in 0.01 seconds
Finished: plan example in 8.64 sec

Create a manifest that sets up a web server with nginx, and run it as a plan.

1. Go to the site-modules directory in the default Bolt project directory: ~/.puppetlabs/bolt/site-modules

2. Create a module named profiles.

   • If you use the Puppet Development Kit: pdk new module profiles

   • Otherwise create ~/.puppetlabs/bolt/site-modules/profiles

3. Add a plans directory to the profiles module.

4. In the plans directory, create a manifest file called nginx_install.pp and add the following code:

   plan profiles::nginx_install(
        TargetSpec $targets,
        String $site_content = 'hello!',
      ) {
   
        # Install the puppet-agent package if Puppet is not detected.
        # Copy over custom facts from the Bolt modulepath.
        # Run the `facter` command line tool to gather target information.
        $targets.apply_prep
   
        # Compile the manifest block into a catalog
        apply($targets) {
          if($facts['os']['family'] == 'redhat') {
            package { 'epel-release':
              ensure => present,
              before => Package['nginx'],
            }
            $html_dir = '/usr/share/nginx/html'
          } else {
            $html_dir = '/var/www/html'
          }
   
          package {'nginx':
            ensure => present,
          }
   
          file {"${html_dir}/index.html":
            content => $site_content,
            ensure  => file,
          }
   
          service {'nginx':
            ensure  => 'running',
            enable  => 'true',
            require => Package['nginx']
          }
        }
      }

5. Run the plan on a target:

   bolt plan run profiles::nginx_install --targets mytarget.mydomain

6. In a web browser, open mytarget.mydomain. The page displays the text hello!

🔩 Tip: For complex web server deployments, consider adding the puppet-nginx module.

📖 Related information

• NGINX

• Specify targets

• Bolt Projects

Create a manifest that sets up a web server with IIS and run it as a plan.

1. Create a directory to use as your Bolt project or use an existing directory.

2. Convert the directory into a Bolt project named 'profiles' by running bolt project init profiles, or New-BoltProject -Name profiles if you're using PowerShell.

3. Add the puppetlabs-iis module to your bolt-project.yaml under the modules key:

   modules:
     - name: puppetlabs-iis
       version_requirement: 4.3.2

4. Run bolt module install or Install-BoltModule if you're using PowerShell.

5. Create a new Puppet language Bolt plan inside your project by running bolt plan new profiles or New-BoltPlan -Name profiles -Pp on PowerShell. This creates a plans/ directory in your Bolt project, and a file named init.pp inside that directory with some basic commands.

6. Replace the contents of <PROJECT DIRECTORY>/plans/init.pp with this Bolt plan:

   plan profiles(
        TargetSpec $targets,
        String $site_content = 'hello!',
   ) {
   
     # Install the puppet-agent package if Puppet is not detected. 
     # Copy over custom facts from the Bolt modulepath.
     # Run the `facter` command line tool to gather target information.
     $targets.apply_prep
   
     # Compile the manifest block into a catalog
     return apply($targets, '_catch_errors' => true) {
       $iis_features = ['Web-WebServer','Web-Scripting-Tools']
   
       iis_feature { $iis_features:
         ensure => 'present',
       }
   
       # Delete the default website to prevent a port binding conflict.
       iis_site {'Default Web Site':
         ensure  => absent,
         require => Iis_feature['Web-WebServer'],
       }
   
       iis_site { 'minimal':
         ensure          => 'started',
         physicalpath    => 'c:\\inetpub\\minimal',
         applicationpool => 'DefaultAppPool',
         require         => [
           File['minimal'],
           Iis_site['Default Web Site']
         ],
       }
   
       file { 'minimal':
         ensure => 'directory',
         path   => 'c:\\inetpub\\minimal',
       }
   
       file { 'content':
         ensure  => 'file',
         path    => 'c:\\inetpub\\minimal\\index.html',
         content => $site_content,
       }
     }
   }

   This plan uses the apply function to apply a manifest to targets. The manifest uses the puppetlabs-iis module to set up an IIS server on the targets.

7. Run the plan on a target: *nix shell command

   bolt plan run profiles --targets winrm://mytarget.mydomain

   PowerShell cmdlet

   Invoke-BoltPlan -Name profiles -Targets winrm://mytarget.mydomain

8. In a web browser, open mytarget.mydomain. The page displays the text hello!

📖 Related information

• IIS

• Specify targets

• Bolt projects

• Puppet language Bolt plans

• For information on how Bolt loads the modulepath, see Modules overview.

• To learn more about using Puppet device modules, see Running Bolt on network devices