Puppet Enterprise 2017.3

This page is meant to help familiarize you with several common tasks used in Puppet Enterprise with Windows agents, and explain the concepts and reasons behind performing them.

Practice Windows Tasks

In other locations in the documentation, these can be found as steps in tasks, but they are not explained as thoroughly.

Write a simple manifest

Puppet manifest files are lists of resources that have a unique title and a set of named attributes that describe the desired state.

Before you begin

You need a text editor to create manifest files. Atom, Visual Studio Code and Sublime Text support syntax highlighting of the Puppet language. Editors like Notepad++ or Notepad won't highlight Puppet syntax, but can also be used to create manifests.

Manifest files are written in Puppet code, a domain specific language (DSL) that defines the desired state of resources on a system, such as files, users, and packages. Puppet compiles these text-based manifests into catalogs, and uses those to apply configuration changes.

  1. Create a file named file.pp and save it in c:\myfiles\
  2. With your text editor of choice, add the following text to the file:
    file { 'c:\\Temp\\foo.txt':
      ensure   => present,
      content  => 'This is some text in my file'
    }

Note the following details in this file resource example:

  • Puppet uses a basic syntax of type { title: }, where type is the resource type — in this case it’s file.

  • The resource title (the value before the :) is C:\\Temp\\foo.txt. The file resource uses the title to determine where to create the file on disk. A resource title must always be unique within a given manifest.

  • The ensure parameter is set to present to create the file on disk, if it's not already present. For file type resources, you can also use the value absent, which removes the file from disk if it exists.

  • The content parameter is set to This is some text in my file, which writes that value to the file.

Validate your manifest with puppet parser validate

You can validate that a manifest's syntax is correct by using the command puppet parser validate

  1. Check your syntax by entering puppet parser validate c:\myfiles\file.pp in the Puppet command prompt. If a manifest has no syntax errors, the tool outputs nothing.
  2. To see what output occurs when there is an error, temporarily edit the manifest and remove the : after the resource title. Run puppet parser validate c:\myfiles\file.pp again, and see the following output:
    Error: Could not parse for environment production: Syntax error at 'ensure' at c:/myfiles/file.pp:2:3

Launch the Puppet command prompt

A lot of common interactions with Puppet are done via the command line.

To open the command line interface, enter Command Prompt Puppet in your Start Menu, and click Start Command Prompt with Puppet.

The Puppet command prompt has a few details worth noting:

  • Several important batch files live in the current working directory, C:\Program Files\Puppet Labs\Puppet\bin. The most important of these batch files is puppet.bat. Puppet is a Ruby based application, and puppet.bat is a wrapper around executing Puppet code through ruby.exe.
  • Running the command prompt with Puppet rather than just the default Windows command prompt ensures that all of the Puppet tooling is in PATH, even if you change to a different directory.

Simulate a Puppet run with --noop

Puppet has a switch that you can use to test if manifests will make the intended changes. This is referred to as non-enforcement or no-op mode.

To simulate changes, run puppet apply c:\myfiles\file.pp --noop in the command prompt:
C:\Program Files\Puppet Labs\Puppet\bin>puppet apply c:\myfiles\file.pp --noop
Notice: Compiled catalog for win-User.localdomain in environment production in 0.45 seconds
Notice: /Stage[main]/MainFile[C:\Temp\foo.txt]/ensure: current value absent, should be present (noop)
Notice: Class[Main]: Would have triggered 'refresh' from 1 events
Notice: Stage[main]: Would have triggered 'refresh' from 1 events
Notice: Applied catalog in 0.03 seconds

Puppet shows you the changes it would make, but does not actually make the changes. It would create a new file at C:\Temp\foo.txt, but it hasn't, because you used --noop.

Enforce the desired state with puppet apply

When the output of the simulation shows the changes you intend to make, you can start enforcing these changes with the puppet apply command.

Run puppet apply c:\myfiles\file.pp.

To see more details about what this command did, you can specify additional options, such as --trace, --debug, or --verbose, which can help you diagnose problematic code. If puppet apply fails, Puppet outputs a full stack trace.

Puppet enforces the resource state you've described in file.pp, in this case guaranteeing that a file (c:\Temp\foo.txt) is present and has the contents This is some text in my file.

Understanding idempotency

A key feature of Puppet is its idempotency: the ability to repeatedly apply a manifest to guarantee a desired resource state on a system, with the same results every time.

If a given resource is already in the desired state, Puppet performs no actions. If a given resource is not in the desired state, Puppet takes whatever action is necessary to put the resource into the desired state. Idempotency enables Puppet to simulate resource changes without performing them, and lets you set up configuration management one time, fixing configuration drift without recreating resources from scratch each time Puppet runs.

To demonstrate how Puppet can be applied repeatedly to get the same results, change the manifest at c:\myfiles\file.pp to the following:

file { 'C:\\Temp\\foo.txt':
  ensure   => present,
  content  => 'I have changed my file content.'
}

Apply the manifest by running puppet apply c:\myfiles\file.pp. Open c:\Temp\foo.txt and notice that Puppet changes the file's contents.

Applying the manifest again with puppet apply c:\myfiles\file.pp results in no changes to the system, demonstrating that Puppet behaves idempotently.

Many of the samples in Puppet documentation assume that you have this basic understanding of creating and editing manifest files, and applying them with puppet apply.

Additional command line tools

Once you understand how to write manifests, validate them, and use puppet apply to enforce your changes, you're ready to use commands such as puppet agent, puppet resource, and puppet module install

puppet agent

Like puppet apply, the puppet agent command line tool applies configuration changes to a system. However, puppet agent retrieves compiled catalogs from a Puppet Server, and applies them to the local system. Puppet is installed as a Windows service, and by default tries to contact the master every 30 minutes by running puppet agent to retrieve new catalogs and apply them locally.

puppet resource

You can run puppet resource to query the state of a particular type of resource on the system. For example, to list all of the users on a system, run the command puppet resource user.

The computer used for this example has three local user accounts: Administrator, Guest, and vagrant. Note that the output is the same format as a manifest, and you can copy and paste it directly into a manifest.

puppet module install

Puppet includes many core resource types, plus you can extend Puppet by installing modules. Modules contain additional resource definitions and the code necessary to modify a system to create, read, modify, or delete those resources. The Puppet Forge contains modules developed by Puppet and community members available for anyone to use.

Puppet synchronizes modules from a master to agent nodes during puppet agent runs. Alternatively, you can use the standalone Puppet module tool, included when you install Puppet, to manage, view, and test modules.

Run puppet module list to show the list of modules installed on the system.

To install modules, the Puppet module tool uses the syntax puppet module install NAMESPACE/MODULENAME. The NAMESPACE is registered to a module, and MODULE refers to the specific module name. A very common module to install on Windows is registry, under the puppetlabs namespace. So, to install the registry module, run puppet module install puppetlabs/registry.

Back to top