What is Puppet?

Puppet is a configuration management tool developed by Puppet labs to automate infrastructure management and configuration. Puppet includes its own declarative language to describe system configuration. It is a model-driven solution that requires limited programming knowledge to use.

Puppet Architecture

• Puppet Master: It performs a critical role by handling all the configuration-related tasks. It applies the configuration to all the target nodes or the client machines.
• Puppet Agent: The Puppet Agent is the application that manages the configurations on your nodes. It requires a Puppet primary server to fetch configuration catalogs from. Depending on your infrastructure and needs, you can manage systems with Puppet agent as a service, as a cron job, or on-demand.
• Configuration Repository: A shared location where all configurations are saved and retrieved when required by the Puppet master.
• Puppet Facts: These are the details related to Master. The target machine consists of classification, functional and regional, etc., related attributes, so Puppet master can analyze them and apply required configurations.
• Catalog: It is a compiled version of configuration which needs to be pushed onto target machines.

Puppet Workflow

Puppet master collects all the details of the target node using Factor, which consists of Fact files of the Node. Puppet master compares retrieved configuration and the defined configuration based on the server’s facts. Then, it creates a Catalog and pushes it to the Puppet agent on the target node. Puppet agent executes the catalog in the next run and updates it back to the Puppet master.

Note: Above all explained to understand the basic functionality of Puppet, so we can quickly troubleshoot the Issues, and below are the few commonly occurring issues and solutions for them.

Puppet Use Cases

Case 1

Challenge: Target Machine stops reflecting in Puppet Console CLI or the Puppet web console. This is probably because the Puppet agent on the target machine is no longer reporting to the Puppet master.

Solution:

1. Log in to the target machine
2. Open PowerShell or CMD with elevated privileges.
3. Set Path to: C:\ProgramData\PuppetLabs\puppet\etc
4. >Notepad Puppet.conf
   In the configuration file, remove the agent server Name, which is highlighted below.
   
5. Save the file Puppet.conf
6. Run Command > Puppet agent -t

Now you should see the target machine in Puppet Web console/CLI if the Agent rerun completes successfully.

Case 2

Challenge: Run of Puppet configuration client already in progress.
This is probably due to the Puppet agent getting stuck during its periodic Run.

Solution:

1. Log into the target machine
2. Open File Explorer
3. Navigate to C:\Programdata\puppetlabs\puppet\cache\state
4. Remove the file named “agent_catelog_run.lock”
5. Now open Powershell/CMD with elevated privileges
6. Run the command> Puppet agent -t

Now the Puppet agent rerun should complete successfully with applying updated configurations.

Case 3

Challenge: Certificate error after Puppet agent rerun, This is probably due to the certificate mismatch of the target machine in the Puppet master configuration file.

Solution:

1. Login to the target machine
2. Open PowerShell/cmd with elevated privileges
3. To clean the certificate from the target machine
4. Run Command>Puppet SSL clean
5. Login to Puppet Master Server
6. If its CLI >run command > puppetserver ca clean –certname targetmachine.contoso.com
7. If its UI> Run the task “Clean Certificate” for the targetmachine.contoso.com,
8. Note: The task must be preconfigured in Web UI.
9. Run>Puppet agent -t in target machine Powershell/CMD

Now the puppet agent rerun should be complete successfully.

Case 4

Error 1

Error 2

“Could not evaluate: Failed to open TCP connection to Puppetmaster.contoso.com:443 (getaddrinfo: No such host is known. )”

Error 3

Exception calling “DownloadFile” with “2” argument(s): “Unable to connect to the remote server.”
This is probably due to a communication block between the target machine and the Puppet master on ports 443 and 8140.

Solution:

1. Login to Target machine
2. Telnet (Puppet Master IP) 443/8140 or Test-NetConnection -ComputerName (PuppemasterIP) -Port 8140
3. If the connection is a success, you can proceed with the rerun of the Puppet agent or the puppet installation.
4. If not, A firewall request to be submitted to open the ports between Puppet master and the subnet of Target machine for ports 443 and 8140

Then you can proceed with the rerun or the installation of Puppet.

Case 5

Challenge: Puppet facts mismatch with the details in the Puppet.config
This is probably due to a mismatch of the details between Puppet.config file and facts.d.

Solution:

1. Login to Target machine
2. Open Puppet.config file at C:\programdata\puppetlabs\puppet\etc
3. Open Fact files at C:\programdata\puppetlabs\factor\facts.d
4. Make sure they have identical attributes for server classification or, if any, in common.
5. Make necessary changes and save them and Rerun the agent

Puppet agent rerun should be successful now.

Case 6:

Challenge: Puppet installs but Puppet.config file missing. While installing the Puppet on the target machine, the installation will be successful, but it will not write the puppet.config file.
Solution: In this case, we can copy the puppet.config file from the adjacent server and same subnet and do the necessary changes for server classification ex: Production, Test, etc., on the environment attribute. Now Rerun the Puppet agent, and it should be successful.

Conclusion

Being Puppet is a vast subject and I have come across the above troubleshooting scenarios commonly encountered and provided with solutions. I am glad if my article will help troubleshoot the issues related to Puppet and resolve them. This is documented completely in my personal view and looking forward to hearing any feedback or advice. Good luck!