Deploying Puppet Master and Puppet Agents for the first time can involve a significant amount of troubleshooting. In this post, I want to review six miscellaneous points that may arise. These are somewhat random, but they can serve in the rudimentary stages of quickly getting a proof of concept established.
1. With a default configuration, Puppet Master on Linux will run manifests with only one name in only one location: /etc/puppet/manifests/site.pp
Many DevOps engineers do use manifests with different names. However, absent special configuration, this the only file name and location that will work.
2. A reality of efficient I.T., particularly in non-production environments with open source technologies, is to ignore certain error messages. If you compile a manifest (e.g., with the puppet agent -t site.pp command), you may be able to ignore this subsequent error if it pertains to the Puppet Master FQDN:
"Error: Could not retrieve catalog from remote server: Error 400 on Server: Could not find default node or by name with ..."
3. To find an error in a Puppet Manifest, try this command: puppet parser validate nameOfManifest.pp
It will find errors such as upper case class names. But it will not find an error such as a time when a resource declaration uses "requires => ..." The correct Puppet DSL reserved word for a given resource declaration is "require" with no "s."
4. Network Time Protocol (ntp) must be configured and running on the Puppet Master and Puppet Agent servers. The time difference between a Puppet Master server and Puppet Agent node may seem insignificant to an individual person. To see if ntp is running, try this:
sudo ps -ef | grep ntp
If ntp is not running on a Puppet Agent, manifests will appear to compile and run without errors on either the Puppet Master or Puppet Agent server. Here is how to get ntp to automatically start.
First, go into the /etc/crontab file. Second, add this entry: * * * * * root service ntpd start
Third, save the file and exit. Now ntp will start every minute regardless of who is logged in.
5. /etc/puppet/puppet.conf can, by default, have the same content on the Agent nodes as the Master nodes. One entry should be like this in the [main] section:
server = FQDNofPuppetMasterServer
This tip clarifies how multiple servers may have the same file and how it relates to the inter-server configuration of Puppet.
6. Problem scenario: Facter does not pick up the correct value from a Puppet Agent node with Windows Server.
Solution: Go to the Puppet Agent node. Open PowerShell. Run this: puppet facts
If the result says something like "no default action," go to the Control Panel -> Uninstall Programs. See if Puppet is installed. If it is, verify it says "Puppet Agent." Puppet Master could be installed, but that will not give you facter.
Update on 12/28/16: For troubleshooting manifests that are not doing what you expect despite no messages or few errors in the logs, see this posting.