4/23/2014 PE 3.

2 Quick Start Using PE Documentation Puppet Labs

http://docs.puppetlabs.com/pe/latest/quick_start.html 1/21
Quick Start: Using PE 3.2
Welcome to the Puppet Enterprise 3.2 quick start guide. This document is a short
walkthrough to help you evaluate Puppet Enterprise (PE) and become familiar with its
features. There are two parts to this guide, an introductory guide (below) that
demonstrates basic use and concepts and a follow-up guide where you can build on the
concepts you learned in the introduction while learning some basics about developing puppet
modules for either Windows or *nix platforms.
Quick Start Part One: Introduction
In this first part, follow along to learn how to:
Quick Start Part Two: Developing Modules
For part two, youll build on your knowledge of PE and learn about module development .
You can choose from either the Linux track or the Windows track.
Creating a Deployment
Preparing Your Proof-of-Concept Systems
Installing the Puppet Master
Installing the PE Agent
Connecting Agents to the Master
Approving the Certificate Request
Testing the Agent Nodes
Viewing the Agent Node in the Console
Avoiding the Wait
Using Live Management to Control Agent Nodes
Discovering Resources
Triggering Puppet Runs
Installing Modules
Installing a Forge Module
Using Modules in the PE Console
Viewing Changes with Event Inspector
Summary
Next Steps
Create a small proof-of-concept deployment
Examine and control nodes in real time with live management
Install a PE-supported Puppet module
Apply Puppet classes to nodes using the console
Set the parameters of classes using the console
Use the console to inspect and analyze the results of configuration events
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 2/21
In part two, youll learn about:
Creating a Deployment
A typical Puppet Enterprise deployment consists of:
For this walk-through, you will create a simple deployment where the puppet master, the
console, and database support roles will run on one machine (a.k.a., a monolithic master).
This machine will manage one or two agent nodes. In a production environment you have
total flexibility in how you deploy and distribute your master, console, and database support
roles, but for the purposes of this guide were keeping things simple.
Basic module structure
Editing manifests and templates
Writing your own modules
Creating a site module that builds other modules into a complete machine role
Applying classes to groups with the console
Following this walkthrough will take approximately 30-60 minutes for each part.
A number of agent nodes, which are computers (physical or virtual) managed by
Puppet.
At least one puppet master server, which serves configurations to agent nodes.
At least one console server, which analyzes agent reports and presents a GUI for
managing your site. (This may or may not be the same server as the master.)
At least one database support server which runs PuppetDB and databases that
support the console. (This may or may not be the same server as the console server.)
Preparing Your Proof-of-Concept Systems
To create this small deployment, you will need the following:
At least two computers (nodes) running a *nix operating system supported by
Puppet Enterprise.
These can be virtual machines or physical servers.
One of these nodes (the puppet master server) should have at least 1 GB of
RAM. Note: For actual production use, a puppet master node should have
at least 4 GB of RAM.
For part two, if you choose to follow the Windows track youll need a computer
running a version of Microsoft Windows supported by Puppet Enterprise.
Puppet Enterprise installer tarballs suitable for the OS and architecture your
nodes are using.
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 3/21
Installing the Puppet Master
A network all of your nodes should be able to reach each other.
All of the nodes you intend to use should have their system clocks set to within a
minute of each other.
An internet connection or a local mirror of your operating systems package
repositories, for downloading additional software that Puppet Enterprise may
require.
Properly configured firewalls.
For demonstration purposes, all nodes should allow all traffic on ports
8140, 61613, and 443. (Production deployments can and should partially
restrict this traffic.)
Properly configured name resolution.
Each node needs a unique hostname, and they should be on a shared
domain. For the rest of this walkthrough, we will refer to the puppet master
as master.example.com and the agent node as agent1.example.com. You
can use any hostnames and any domain; simply substitute the names as
needed throughout this document.
All nodes must know their own hostnames. This can be done by properly
configuring reverse DNS on your local DNS server, or by setting the
hostname explicitly. Setting the hostname usually involves
thehostname command and one or more configuration files, while the exact
method varies by platform.
All nodes must be able to reach each other by name. This can be done
with a local DNS server, or by editing the /etc/hosts file on each node to
point to the proper IP addresses. Test this by running ping
master.example.com and ping agent1.example.com on every node.
Optionally, to simplify configuration later, all nodes should also be able
to reach the puppet master node at the hostname puppet. This can be
done with DNS or with hosts files. Test this by running ping puppeton
every node.
The control workstation from which you are carrying out these
instructions must be able to reach every node in the deployment by
name.
1. On the puppet master node, log in as root or with a root shell. (Use sudo -s to get a
root shell if your operating systems root account is disabled, as on Debian and
Ubuntu.)
2. Download the full (NOT agent-only) Puppet Enterprise tarball, extract it, and navigate to
the directory it creates. (The agent-only tarball is used for package-management based
agent installation, which is not covered by this guide.)
3. Run ./puppet-enterprise-installer. The installer will ask a series of questions about
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 4/21
The installer will then install and configure Puppet Enterprise. It may also need to install
additional packages from your OSs repository. This process may take up to 10-15
minutes.
Installing the PE Agent
which components to install, and how to configure them.
Install the puppet master, database support, and console roles; the cloud
provisioner role is not required, but may be useful if you later promote this
machine to production or just want to experiment with PE provisioning features.
Make sure that the unique certname matches the hostname you chose for this
node. (For example, master.example.com.)
You will need the email address and console password it requests in order to
use the console; choose something memorable.
None of the other passwords are relevant to this quick start guide. Choose
something random.
For purposes of this walkthrough, when prompted for an SMTP server you can
enter localhost or other inert text. Otherwise, you can accept the default
responses for every other question by hitting enter.
You have now installed the puppet master node. As indicated by the installer, the
puppet master node is also an agent node, and can configure itself the same way it
configures the other nodes in a deployment. Stay logged in as root for further
exercises.
1. On the agent node, log in as root or with a root shell. (Use sudo -s to get a root
shell if your operating systems root account is disabled.)
2. Copy the Puppet Enterprise tarball you downloaded previously onto your agent node,
extract it, and navigate to the directory it creates.
3. Run ./puppet-enterprise-installer. The installer will ask a series of questions about
which components to install, and how to configure them.
Skip the puppet master role by answering No in the installer script.
Provide the puppet master hostname; in this case, master.example.com. If you
configured the master to be reachable at puppet, you can alternately accept the
default.
Skip the database support and console roles by answering No in the installer
script.
Install the puppet agent role by answering Yes in the installer script. The cloud
provisioner role is optional and is not used in this exercise.
Make sure that the unique certname matches the hostname you chose for this
node. (For example, agent1.example.com.)
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 5/21
The installer will then install and configure the Puppet Enterprise agent.
Note: In a production environment there are other ways to install agents that are faster and
easier. For more information, see the complete installation instructions.
Connecting Agents to the Master
After installing, the agent nodes are not yet allowed to fetch configurations from the
puppet master; they must be explicitly approved and granted a certificate.
Approving the Certificate Request
During installation, the agent node contacted the puppet master and requested a certificate.
To add the node to the console and to start managing its configuration, youll need
to approve its request on the puppet master. This is most easily done via the console.
Accept the default responses for every other question by hitting enter.
You have now installed the puppet agent node. Stay logged in as root for further
exercises.
1. On your control workstation, open a web browser and point it to
https://master.example.com. You will receive a warning about an untrusted certificate.
This is because you were the signing authority for the consoles certificate, and your
Puppet Enterprise deployment is not known to the major browser vendors as a valid
signing authority. Ignore the warning and accept the certificate. The steps to do
this vary by browser.
2. On the login screen for the console, log in with the email address and password you
provided when installing the puppet master.
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 6/21
Testing the Agent Nodes
During this walkthrough, we will be running the puppet agent interactively. By default, the
agent runs in the background and fetches configurations from the puppet master every 30
minutes. (This interval is configurable with the runinterval setting in puppet.conf.)
However, you can also trigger a puppet run manually from the command line.
The console GUI loads in your browser. Note the pending node requests indicator in
the upper right corner. Click it to load a list of currently pending node requests.
3. Click the Accept All button to approve all the requests and add the nodes.
The puppet agents can now retrieve configurations from the master the next time
puppet runs.
1. On the agent node, log in as root and run puppet agent --test on the command
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 7/21
Viewing the Agent Node in the Console
line. This will trigger a single puppet run on the agent with verbose logging.
Note: If you receive a -bash: puppet: command not found error, run export
PATH=/usr/local/sbin:/usr/local/bin:$PATH, then try again. This error can
appear when the /usr/local/bin directory is not present in the root
users$PATH by default.
2. Note the long string of log messages, which should end with notice: Finished
catalog run in [...] seconds.
You are now fully managing the agent node. It has checked in with the puppet master
for the first time and received its configuration info. It will continue to check in and
fetch new configurations every 30 minutes. The node will also appear in the console,
where you can make changes to its configuration by assigning classes and modifying
the values of class parameters.
1. Click Nodes in the primary navigation bar. Youll see various UI elements, which show
a summary of recent puppet runs and their status. Notice that the master and any
agent nodes appear in the list of nodes:
2. Explore the console. Note that if you click on a node to view its details, you can see
its recent history, the Puppet classes it receives, and a very large list of inventory
information about it. See here for more information about navigating the console.
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 8/21
Avoiding the Wait
Although the puppet agent is now fully functional on the agent node, some other Puppet
Enterprise software is not; specifically, the daemon that listens for orchestration messages
is not yet configured. This is because Puppet Enterprise uses Puppet to configure itself.
Puppet Enterprise does this automatically within 30 minutes of a nodes first check-in. To
speed up the process and avoid the wait, do the following:
You now know how to find detailed information about any node PE is managing,
including its status, inventory details, and the results of its last puppet run.
1. On the console, use the sidebar to navigate to the mcollective group:
2. Check the list of nodes at the bottom of the page for agent1.example.com
depending on your timing, it may already be present. If so, skip to on each agent
node below.
3. If agent1 is not a member of the group already, click the Edit button:
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 9/21
4. In the nodes field, begin typing agent1.example.coms name. You can then select it
from the list of autocompletion guesses. Click the Update button after you have
selected it.
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 10/21
In a normal environment, you would usually skip these steps and allow orchestration to
come on-line when Puppet runs automatically.
Using Live Management to Control Agent
Nodes
Live management uses Puppet Enterprises orchestration features to view and edit resources
in real time. It can also trigger puppet runs and perform other orchestration tasks.
5. On each agent node, run puppet agent --test again, as described above. Note the
long string of log messages related to the pe_mcollective class.
The agent node can now respond to orchestration messages and its resources can be
viewed live in the console.
1. On the console, click the Live Management tab in the top navigation.
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 11/21
Discovering Resources
2. Note that the master and the agent nodes are all listed in the sidebar.
1. Note that you are currently in the Browse Resources tab.
2. Choose user resources from the list of resource types, then click the Find Resources
button:
3. Examine the complete list of user accounts found on all of the nodes currently
selected in the sidebar node list. (In this case, both the master and the agent node are
selected.) Most of the users will be identical, as these machines are very close to a
default OS install, but some users related to the puppet masters functionality are only
on one node:
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 12/21
The other resource types work in a similar manner. Choose the node(s) whose resources
you wish to browse. Select a resource type, click Find Resources to discover the resource
on the selected nodes, click on one of the resulting found resources to see details about it.
Triggering Puppet Runs
Rather than using the command line to kick off puppet runs with puppet agent -t one at a
time, you can use live management to run Puppet on several selected nodes.
4. Click on any user to view details about its properties and where it is present.
1. On the console, in the live management page, click the Control Puppet tab.
2. Make sure one or more nodes are selected with the node selector on the left.
3. Click the runonce action to reveal the red Run button and additional options, and then
click the Run button to run Puppet on the selected nodes.
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 13/21
You have just triggered a puppet run on several agents at once; in this case, the master
and the agent node. The runonce action will trigger a puppet run on every node currently
Note: You cant always use the runonce actions additional options with *nix
nodes, you must stop the pe-puppet service before you can use options
like noop.See this note in the orchestration section of the manual for more details.
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 14/21
selected in the sidebar.
When using this action in production deployments, select target nodes carefully, as running
it on dozens or hundreds of nodes at once can strain the Puppet master server. If you need
to do an immediate Puppet run on many nodes, you should use the orchestration command
line to do a controlled run series.
Installing Modules
Puppet configures nodes by applying classes to them. Classes are chunks of Puppet code
that configure a specific aspect or feature of a machine.
Puppet classes are distributed in the form of modules. You can save time by using pre-
existing modules. Pre-existing modules are distributed on the Puppet Forge, andcan be
installed with the puppet module subcommand. Any module installed on the Puppet
master can be used to configure agent nodes.
Installing a Forge Module
We will install a Puppet Enterprise supported module: puppetlabs-ntp. While you can use
any module available on the Forge, PE customers can take advantage of supported
modules which are supported, tested, and maintained by Puppet Labs.
1. On your control workstation, point your browser
tohttp://forge.puppetlabs.com/puppetlabs/ntp. This is the Forge listing for a module
that installs, configures, and manages the ntp service.
2. On the puppet master, run puppet module search ntp. This searches for modules
from the Puppet Forge with ntp in their names or descriptions and results in something
like:
Searching http://forge.puppetlabs.com ...
NAME DESCRIPTION AUTHOR KEYWORDS
puppetlabs-ntp NTP Module @puppetlabs ntp aix
saz-ntp UNKNOWN @saz ntp OEL
thias-ntp Network Time Protocol... @thias ntp ntpd
warriornew-ntp ntp setup @warriornew ntp
We want puppetlabs-ntp, which is the PE supported ntp module. You can view detailed
info about the module in the Read Me on the Forge page you just
visited:http://forge.puppetlabs.com/puppetlabs/ntp.
3. Install the module by running puppet module install puppetlabs-ntp:
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 15/21
There are many more modules, including PE supported modules, on the Forge. In part two
of this guide youll learn more about modules, including customizing and writing your own
modules on either Windows or *nix platforms.
Using Modules in the PE Console
Every module contains one or more classes. Classes are named chunks of puppet code and
are the primary means by which Puppet configures nodes. The module you just installed
contains a class called ntp. To use any class, you must first tell the console about it and
then assign it to one or more nodes.
Preparing to install into /etc/puppetlabs/puppet/modules ...
Notice: Downloading from http://forge.puppetlabs.com ...
Notice: Installing -- do not interrupt ...
/etc/puppetlabs/puppet/modules
puppetlabs-ntp (v3.0.1)
You have just installed a Puppet module. All of the classes in it are now available to be
added to the console and assigned to nodes.
1. On the console, click the Add classes button in the sidebar:
2. Locate the ntp class in the list of classes, and click its checkbox to select it. Click the
Add selected classes button at the bottom of the page.
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 16/21
3. Navigate to the default group page (by clicking the link in the Groups menu in the
sidebar), click the Edit button, and begin typing ntp in the Classes field; you can
select the ntp class from the list of autocomplete suggestions. Click the Update
button after you have selected it.
4. Note that the ntp class now appears in the list of classes for the default group. Also
note that the default group contains your master and agent.
5. Navigate to the live management page, and select the Control Puppet tab. Use the
runonce action to trigger a puppet run on both the master and the agent. This will
configure the nodes using the newly-assigned classes. Wait one or two minutes.
6. On the agent, stop the ntp service.
Note: the NTP service name may vary depending on your operating system; for
example, on Debian nodes, the service name is ntp.
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 17/21
Setting Class Parameters
You can use the console to set the values of the class parameters of nodes by selecting a
node and then clicking Edit parameters in the list of classes. For example, you want to
specify an NTP server for a given node.
The grey text that appears as values for some parameters is the default value, which can be
either a literal value or a Puppet variable. You can restore this value with the Reset value
control that appears next to the value after you have entered a custom value.
7. Run nptdate us.pool.ntp.org. The result should resemble the following:
28 Jan 17:12:40 ntpdate[27833]: adjust time server 50.18.44.19 offset
0.057045 sec
8. Finally, restart the ntp service.
Puppet is now managing NTP on the nodes in the default group. So, for example, if
you forget to restart the NTP service on one of those nodes after runningntpdate, PE
will automatically restart it on the next puppet run.
1. Click a node in the node list.
2. On the node view page, click the Edit button.
3. Find ntp in the class list, and click Edit Parameters.
4. Enter a value for the parameter you wish to set. To set a specific server,
enterntp1.example.com in the box next to the servers parameter.
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 18/21
For more information, see the page on classifying nodes with the console.
Viewing Changes with Event Inspector
The event inspector lets you view and research changes and other events. Click the Events
tab in the main navigation bar. The event inspector window is displayed, showing the default
view: classes with failures. Note that in the summary pane on the left, one event, a
successful change, has been recorded for Nodes. However, there are two changes for
Classes and Resources. This is because the NTP class loaded from the Puppetlabs-ntp
module contains additional classesa class that handles the configuration of NTP
(Ntp::Config)and a class that handles the NTP service (Ntp::Service).
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 19/21
You can click on events in the summary pane to inspect them in detail. For example, if you
click With Changes in the Classes With Events summary view, the main pane will show
you that the Ntp::Config and Ntp::Service classes were successfully added when you
triggered the last puppet run.
You can keep clicking to drill down and see more detail. You can click the previous arrow (left
of the summary pane), the bread-crumb trail at the top of the page, or bookmark a page for
later reference (but note that after subsequent puppet runs, the bookmarks may be
different when you revisit them). Eventually, you will end up at a run summary that shows
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 20/21
you the details of the event. For example, you can see exactly which piece of puppet code
was responsible for generating the event; in this case, it was line 15 of
theservice.pp manifest and line 21 of the config.pp manifest.
If there had been a problem applying this class, this information would tell you exactly what
piece of code you need to fix. In this case, event inspector lets you confirm that PE is now
managing NTP.
In the upper right corner of the detail pane is a link to a run report which contains
information about the puppet run that made the change, including metrics about the run,
logs, and more information. Visit the reports page for more information.
Summary
You have now experienced the core features and workflows of Puppet Enterprise. In
summary, a Puppet Enterprise user will:
Install the PE agent on nodes they wish to manage (*nix and Windowsinstructions),
and add the nodes by approving their certificate requests.
Use pre-built, PE supported modules from the Puppet Forge to save time and effort.
Assign classes from modules to nodes in the console.
Use the console to set values for class parameters.
Allow nodes to be managed by regularly scheduled Puppet runs.
Use live management to inspect and compare nodes, and to trigger on-demand puppet
agent runs when necessary.
4/23/2014 PE 3.2 Quick Start Using PE Documentation Puppet Labs
http://docs.puppetlabs.com/pe/latest/quick_start.html 21/21
Next Steps
Beyond what this brief walkthrough has covered, most users will go on to:
To learn about these workflows, continue to part two of this quick start guide.
Other Resources
Puppet Labs offers many opportunities for learning and training, from formal certification
courses to guided on-line lessons. Weve noted a few below; head over to the learning
Puppet page to discover more.
Use event inspector to learn more about events that occurred during puppet runs, such
as what was changed or why something failed.
Edit Forge modules to customize them to your infrastructures needs.
Create new modules from scratch by writing classes that manage resources.
Use a site module to compose other modules into machine roles, allowing console
users to control policy instead of implementation.
Configure multiple nodes at once by adding classes to groups in the console instead of
individual nodes.
Learning Puppet is a series of exercises on various core topics on deploying and using
PE. It includes the Learning Puppet VM which provides PE pre-installed and configured
on VMware and VirtualBox virtualization platforms.
The Puppet Labs workshop contains a series of self-paced, online lessons that cover a
variety of topics on Puppet basics. You can sign up at the learning page.
To explore the rest of the PE users manual, use the sidebar at the top of this page,
or return to the index.