Published on 9 December 2016 by

First, we have something to admit: It’ll take longer than 45 minutes to get up and running with your Puppet deployment. Not that Puppet isn’t fast, but there are some environmental factors that will play a role in how quickly you can install the packages you’ll need to run the installer script and activate your agents. This could also be dependent on network connectivity and the kind of VM you are running — if it’s in the cloud or running on your local machine. All of these things influence how fast you can download, and how quickly you can implement Puppet.

Still, the goal of this post is to review a few Puppet basics and show you where to find resources for standing up a master and installing agents on both Linux and Windows machines so you can be quick and efficient. I’ll be using a Vagrant environment that’s running VirtualBox to create the VMs, but the information provided in this post can be used to get Puppet Enterprise up and running in any sandbox or lab environment.

A Puppet deployment

First, we’ll look at the architecture of a Puppet deployment. The Puppet master operates as the server for various clients, including Windows and Linux machines, network devices, or cloud VMs. With Puppet, you can manage almost any type of OS with the same master.

Puppet Master diagram

What is Puppet?

Let’s say you are the leader of a senior IT team. You’ve realized there’s an ongoing problem with the SSL configuration on many of your machines, but you don’t know exactly what’s going on. The issue is affecting your bottom line, because the SSL configurations are vital in your online sales process. Customers need to buy your products online, using an SSL-enabled browser. This SSL configuration problem is repeatedly happening and you're losing money.

One of our customers experienced this very problem. They discovered that a time configuration was throwing off their SSL certificates. They were losing thousands of dollars every day.

When they implemented Puppet Enterprise and had it automatically manage their time configuration, the SSL problems went away. Just as important, the customer was able to gain insight into when, where and why the problem was occurring. This is a great example of how Puppet Enterprise can help you identify problems, and create and maintain the stable state you want in your environment.

How does Puppet work?

On a regular interval, agents phone home to the master in what is called a Puppet run. During a Puppet run, agents communicate key inventory information to the master and receive their desired configuration state. The inventory information, called facts, is key-value metadata about each system. These facts include things like which operating system is running, or where your data center is located. These facts are pre-populated for the machine once the agent is installed, so right away you get value out of your Puppet deployment, because each agent is telling the Puppet master key things about itself.

With these facts, the Puppet master is able to filter which agents are going to be receiving the desired configurations you want to apply. This is done via an artifact called the catalog, which contains the resources we want on specific machines that have been filtered by the facts.

When you trigger a Puppet run, the correct nodes receive the configurations they need, and some systems will not receive a specific configuration because they don’t need it. These configurations are held in the catalog.

A Puppet run

Within a Puppet run, you’re able to identify key attributes about a system, and you can use those attributes to send out correct configurations, plus get the reporting you need — all within a 30-minute cycle.

The pre-steps

Let’s get started. The example I’m going to share assumes we're running with VirtualBox and Vagrant. There is a Vagrant repo available that you can use to get started. Be sure to check out the readme for additional help.

If you want to use another type of virtual machine, like an AWS instance, you’ll still be able to follow the instructions below. This is one of many key advantages of Puppet: The ability to recycle configurations and apply them to cloud instances, bare-metal instances or any virtualized instance.

Stand up a master

I’ve created a video that takes us through the process of installing a master and two agents. The video uses a Vagrant and VirtualBox environment, and shows me going through the steps listed below. However, if you want to bypass this portion and immediately start running Puppet, use the Vagrant repo mentioned earlier and skip ahead to the Installing a module section. The repo has all the bootstrap scripts and networking you’ll need to get started.

For those of you who’ll be doing everything manually, you will want to go to our website and visit the downloads page. Here you will have the option to identify what master machine you have. I’d like to point out that the master must be a Linux machine. You can specify the version of Linux you are running, find the proper download, then download the tarball and extract it. If you want to do this from the command line, SSH into your box, become root and run the appropriate command for downloading items from the internet.

After the download is complete, you’ll need to untar the tarball. I'd recommend consulting the installation documentation if you run into any complications.

Once you are in the Puppet Enterprise directory, you’ll find more directories and a few files. The two most important items for now are the installer and uninstaller scripts.

From here you’ll execute the installer script:


After it executes, it will prompt you on how you want to run the installation. You can run the installation in text mode or in the browser. I’d recommend the browser option, since it allows you to see what is happening.

From there you select a monolithic installation. Then you specify a fully qualified domain name for your master, set an admin password and review the installation plan. Once you’ve made those selections, you can trigger the installation process, which allows you to view the logs so you can see what’s happening on the backend.

This is a good time to mention that you’ll need to make sure the proper ports are open, or disable firewalld altogether. You'll also need to set a hostname and make sure there’s some form of DNS available. For this and other tuning requirements, please view these docs.

Once the installation is complete, select the “Start using Puppet Enterprise” button, and you’ll go to your overview page in your Puppet console. The overview page shows you a few key items about what is happening in your environment, like the nodes you currently have in enforcement that are running Puppet. It will also show you which nodes are not reporting. The overview page also lists which nodes you have under Puppet management, and when they last had a run.

Installing agents

You are now ready to install a few agents. This is an integral part of getting value out of Puppet. You can go to the 2:44 point in the video for assistance with this portion.

In order to install a Linux agent, you’ll grab the curl command that’s available in the console view. Go to the Nodes tab on the far left sidebar, then select the Unsigned Certificates section. Copy and paste that command into the command line of the system you wish to have a Puppet agent.

Once again, you’ll want to make sure that you’ve SSH’d into the box, and that you have root access. After you run that command, make sure the /etc/hosts or /etc/known_hosts file has the master’s FQDN, IP address and any aliases that are being used. When you’ve completed those checks, run Puppet.

puppet agent -t

After the run is complete, go back to the Unsigned Certificates page and hit refresh. You should see that there’s a cert to accept.

Installing the Windows agent is a little different. From your Windows box, you’ll want to revisit the downloads page. Select the version of Windows you have, and run the installation for the .msi file. You’ll receive a prompt for this.

When the download is complete, you’ll run the installation wizard and have the agent installed. Modifying the hosts file will also be different on a Windows machine, but can actually be done with Puppet from the PowerShell terminal. In PowerShell, run the following Puppet command:

puppet config set server master.vm --section main 


puppet resource host master.vm ip=<master’sIPaddress> 

Now run Puppet on this same machine.

puppet agent -t

You can accept the cert in the same manner you did for your Linux box. Since you’re using a 10-node free license, feel free to add up to nine agents.

Once you determine that you have the appropriate nodes up and running with Puppet, you can then begin the process of using a Puppet module to classify and configure something in your environment.

Install a module

Earlier I mentioned the customer who had an issue with time that triggered an SSL configuration problem. Leveraging the tse/time module on the Puppet Forge lets you use NTP to modify time. Before running this command, be sure you are connected to the master and have root access once again. Now run the command to install the module:

puppet module install tse-time --version 1.0.1

There are a few other ways to get modules installed, but this is the simplest method for quickly installing and using Forge modules. For instance, if I wanted to use the NTP module from the Forge, simply type puppet module install puppetlabs/ntp. Running the install command places the module in the appropriate folder, which can be found at ‘/etc/puppetlabs/code/environments/production/modules/’. Once the module is installed, it will be placed here, including any dependencies that are required.

For more experienced Puppet practitioners, you can add a line to your Puppetfile and have the module be present in the aforementioned location. For even more advanced practitioners or people familiar with version control workflows, Code Manager is the best option for managing, maintaining, and modifying Puppet code and modules.

Let’s classify something

At this point, you’ve got some content, you’ve got some nodes — what do you do next? Let’s classify something and run Puppet. In the world of Puppet, classification is mapping a machine or machines to a configuration.

First, get into the configuration view and before creating these groups, identify which machines need to be members of that group. Go to the node you want to group, and look at the node details. This is where you’ll see many facts that cover everything from kernel version to the IP address to the location of the data center.

One of the cool things about facts is that you can create custom facts. If there is an attribute item that is not already listed, you can create a fact for yourself. As you look through the facts, you’ll see that there is a value for each fact. Note that facts are case sensitive, so you must make sure you capitalize things that should be capitalized and keep things lowercase that should be lowercase. The foolproof way is to just copy and paste.

From there you’ll go back into your classification view and create a node group. Make sure you use a name that easily identifies the type of nodes in the group. Then you go into that node group and create rules that identify server membership, using the appropriate facts. The great thing is, the facts self-populate, so you can just scroll down and select the facts you want to use, add the rule and commit those changes. You can also add nodes to a group by selecting them and pinning them.

Once you’ve got rules added to your facts, select the Classes tab and refresh your class definitions. Always make sure your classes are current so you can access the code you need and ensure the tse/time module is installed and viewable. In our case, we’ll add the time class and commit the changes. Once that’s done, we’ll be able to see the time class is available in the console, and we'll have the option to modify it.

Now you can add a parameter, commit the change, and do your Puppet run. You can trigger a run by going to that node in the Overview section and running Puppet from the browser. When that run completes, you’ll be notified and you can view a report.

View reports

At PuppetConf, Vern Linder gave an excellent talk on the node graph and how you can identify corrective and intentional changes. This is a very powerful view. You can search for a class, then drill down into that classification to see what changed. The graph gives you a health check view of what has happened and whether or not it was intended.

You can identify where those changes were made, and the lines of code that affect the changes. In the sidebar, you’ll see the path to the file as well as the line of code that is managing it.

Remember, when things go right everything is great; but when things go wrong, you want to be able to drill down quickly to see where misconfiguration or missteps may have happened.

You have both an Event Inspector view and a log view in the console that let you view changes and errors, as well as past reports. (See images below.) Puppet eventsPuppet reports

Both visual displays are a great way to see the changes that are happening on individual nodes. You can drill down and see changes on the node at the class and resource level, and identify what is occurring during the run. All this is very useful when you're troubleshooting errors.

Next steps

For more details on how to install Puppet Enterprise and manage resources in less than an hour, be sure to check out my PuppetConf 2016 talk. It covers the basics of Puppet code, navigating the console, leveraging the Forge, and also covers some key features in the product that can help you start managing resources today. Also, the installation docs are a wonderful resource for installing Puppet in other environments, including virtualized environments, cloud or bare metal.

Finally, you don’t have to have to do this all on your own. We’re here to help you by whatever methods you prefer, whether it’s support, professional services, training, or certification.

Grace Andrews is a technical solutions engineer at Puppet.
Jeremy Adams is a senior technical solutions manager at Puppet.
Stephanie Stouck is a senior services marketing manager at Puppet.

Learn more

  • Haven't tried out Puppet Enterprise yet? You can download our Learning VM for free and go through a series of fun quests to see how PE works.
Share via:
The content of this field is kept private and will not be shown publicly.

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.