Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 38 ยท Getting Started

Your First Puppet Run with puppet apply

Install the Puppet agent, write a first manifest and run it with puppet apply, using --noop, --test and --debug to see what Puppet would change.

You do not need a server to use Puppet. The command puppet apply reads a manifest from a file on the same machine, compiles it and enforces it immediately. It is the fastest way to learn the language, to test code and to configure a single machine. In this lesson you install the agent, write a manifest and read the results.

These commands are for your own Linux virtual machine or container (a throw-away VM is best). Puppet cannot run in the browser, so the code blocks here are read-only. The stand-in at the end imitates a --noop dry run.

Installing the agent

Puppet ships as the puppet-agent package, which bundles its own Ruby, Facter and Hiera so it does not depend on system Ruby. Everything lives under /opt/puppetlabs. On Debian or Ubuntu the steps are: add the Puppet repository package for your release (from apt.puppet.com), then:

Terminal
sudo apt-get update
sudo apt-get install -y puppet-agent

On Red Hat family systems the repository comes from yum.puppet.com and you run sudo dnf install -y puppet-agent. The binaries are not on the default PATH, so use the full path or extend it:

Terminal
export PATH=/opt/puppetlabs/bin:$PATH
puppet --version

The installation lesson covers the Puppet Server too. For puppet apply you only need the agent package.

A first manifest

Create a file first.pp:

PUPPET
file { '/tmp/hello.txt':
  ensure  => file,
  content => "Hello from Puppet\n",
  mode    => '0644',
}

notify { 'finished':
  message => 'The hello file is in place.',
}

notify is a handy resource that only prints a message during the run. Apply it:

Terminal
sudo /opt/puppetlabs/bin/puppet apply first.pp

A typical run prints lines like these (timestamps and version numbers vary):

TEXT
Notice: Compiled catalog for myhost.example.com in environment production in 0.02 seconds
Notice: /Stage[main]/Main/File[/tmp/hello.txt]/ensure: defined content as '{sha256}...'
Notice: The hello file is in place.
Notice: Applied catalog in 0.01 seconds

Run it a second time: the File line disappears, because the file is already correct. That is idempotence in action. Now edit /tmp/hello.txt by hand and run again: Puppet reports a content change and restores it.

Useful flags

Flag What it does
--noop Dry run: report what would change, change nothing
--test Shortcut for several options (verbose, detailed exit codes, show diffs)
--debug Very detailed log of every step
--verbose More informational messages
--modulepath=PATH Where to find modules
-e 'CODE' Apply a one-line manifest without a file

A safe habit is to run --noop first on every change:

Terminal
sudo /opt/puppetlabs/bin/puppet apply --noop first.pp

With --noop the output says current_value 'absent', should be 'file' (noop) instead of acting. With --test, --detailed-exitcodes is included, so the exit status tells you what happened: 0 no changes, 2 changes were made, 4 failures, 6 both changes and failures. Automation can use that.

You can also try a one-liner:

Terminal
sudo /opt/puppetlabs/bin/puppet apply -e 'package { "tree": ensure => installed }'

What happens during apply

flowchart LR
    A["first.pp"] --> B["Parse and compile<br/>(uses facts and Hiera)"]
    B --> C["Catalog<br/>(resource graph)"]
    C --> D["Apply<br/>(compare, fix)"]
    D --> E["Report"]

The same pipeline runs with an agent and server, except the server compiles.

  1. Facter collects facts about the machine (OS, memory, hostname).
  2. Puppet compiles your manifest into a catalog: a list of resources and their order. Resource order in the file does not matter beyond relationships (Relationships and Ordering).
  3. For each resource Puppet asks the type's provider for the current state, compares, and fixes what differs.
  4. A report records the outcome.

A stand-in for --noop

Python Stand-in: a --noop dry run

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that the noop run leaves state untouched.

Python Stand-in: detailed exit codes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common problems

  • puppet: command not found: the binary is in /opt/puppetlabs/bin; add it to your PATH.
  • Permission errors: run as root with sudo, or the run cannot manage system files.
  • Syntax errors: validate before applying with puppet parser validate first.pp.
  • Style: puppet-lint (a separate tool) flags style issues.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does puppet apply --noop file.pp do?

    --noop is a dry run.
  2. 2. Where does the puppet-agent package install its binaries?

    The package is self-contained under /opt/puppetlabs.
  3. 3. What exit code means changes were made and no failures with --detailed-exitcodes?

    0 = no changes, 2 = changes, 4 = failures, 6 = changes and failures.
  4. 4. Why does the second puppet apply of the same manifest print fewer lines?

    Idempotent resources report nothing when no change is needed.

Summary

  • puppet apply compiles and enforces a manifest on the local machine, no server needed.
  • Install puppet-agent; binaries live in /opt/puppetlabs/bin.
  • Use --noop first, --test for convenient output and exit codes, --debug for detail.
  • The pipeline is facts, compile to a catalog, apply, report.
  • puppet parser validate checks syntax.

Next: Puppet Editions, Versions, and Terms