- Configure a Puppet Master Server
- Configure a Puppet Agent Node
Note: This document covers open source releases of Puppet version 3.8 and lower. For current versions, you should see instructions for installing the latest version of Puppet or installing Puppet Enterprise.
Perform the following tasks after you finish installing Puppet. You should have already done the pre-install tasks and followed the installation instructions for your OS.
Configure a Puppet Master Server
After installing Puppet on a node that will act as a puppet master server, you need to:
- Get the master’s names and certificates set up
- Configure any necessary settings
- Put your Puppet modules and manifests in place
- Configure a production-ready web server
- Configure load balancing and CA service routing if you’re using multiple masters
- Start the puppet master service
Get the Master’s Names and Certificates Set Up
When you create the puppet master’s certificate, you must include every DNS name at which agent nodes might try to contact the master.
Decide on a main name for Puppet services at your site, and make sure your DNS resolves it to the puppet master (or its load balancer). Unconfigured agents will try to find a master at
puppet, so if you use this name it can reduce setup time.
dns_alt_names = puppet,puppet.example.com,puppetmaster01,puppetmaster01.example.com
For CA Masters
If this is the only puppet master in your deployment, or if it will be acting as the CA server for a multi-master site, you should now run:
$ sudo puppet master --verbose --no-daemonize
This will create the CA certificate and the puppet master certificate, with the appropriate DNS names included. Once it says
Notice: Starting Puppet master version <VERSION>, type ctrl-C to kill the process.
For Non-CA Masters
You have two main options:
puppet cert generate <NAME> --dns_alt_names=<NAME 1>,<NAME 2>,<NAME 3>on your CA server, then manually copy the new master’s cert, private key, and public key into place on the new master. You will also need to give it a copy of the CA’s certificate and the CRL. See the reference page on the ssldir for more info about these files.
puppet agent --test --ca_server=<SERVER>to request a certificate. On the CA server, run
puppet cert listand
puppet cert --allow-dns-alt-names sign <NAME>to sign the certificate. On the new master, run
puppet agent --test --ca_server=<SERVER>again to retrieve the cert.
Configure Any Necessary Settings
You’ll want to set a few settings in puppet.conf before putting the new master to work. See the list of master-related settings for details. You may also want to read about how Puppet loads settings and the syntax of the puppet.conf file.
Put Your Puppet Modules and Manifests in Place
If you already have a set of modules and a main manifest you use in your deployment, put them into place now. You will probably be checking them out with version control.
Relevant reference pages:
Configure a Production-Ready Web Server
Puppet includes a basic puppet master web server, but you cannot use it for real-life loads. You must configure a production quality web server before you start managing your nodes with Puppet.
If you have no particular preference, you should use Passenger with Apache, since it works well and is simple to set up. If you installed the
puppetmaster-passenger package on Debian or Ubuntu, this is already configured; otherwise, follow the instructions in the Puppet with Passenger setup guide.
Alternately, Puppet supports the Rack interface, and you can configure your puppet master with any Rack web server stack. You can follow the Passenger guide for general guidelines. You will need to:
- Grab the config.ru file from the
ext/rackdirectory in the Puppet source, and set its ownership to the
puppetuser and group.
- Configure your web stack to listen on port 8140 and use that config.ru file to route requests to the puppet master application.
- Configure your front end to terminate SSL using the puppet master server’s SSL certificate and the local Puppet CA. Make sure that it sets the
SSL_CLIENT_CERTenvironment variable and the
Start the Puppet Master Service
The exact service you need to start will depend on the web server you configured. If you followed the Passenger guide, you’ll want to start the
apache2 service, depending on your OS.
Configure a Puppet Agent Node
After installing Puppet on a normal puppet agent node, you’ll need to:
- Configure Puppet
- Start the puppet agent service (or configure a cron job)
- Sign the new node’s certificate
- Classify (assign configurations to) the new node
You will probably need to configure some settings in each agent’s puppet.conf file, to connect it to your puppet master server and change certain behavior.
Start the Puppet Agent Service
If the puppet agent service isn’t already running, you should now start it and configure it to start on boot. Alternately, you may want to run puppet agent via a cron job instead, or run puppet apply with a cron job for a standalone deployment.
Starting the Service
The name of the puppet agent service may vary by platform. On Windows and most *nix platforms, it will be
puppet; on OS X, it is
You can start and enable the service by running:
$ sudo puppet resource service <NAME> ensure=running enable=true
(Although on Windows you would omit the
Creating a Cron Job
You may want to run puppet agent with cron rather than its init script; this can sometimes perform better and use less memory. You can create this cron job with Puppet:
$ sudo puppet resource cron puppet-agent ensure=present user=root minute=30 command='/usr/bin/puppet agent --onetime --no-daemonize --splay'
(On Windows nodes, you should just run the service.)
If you are creating a standalone deployment, you can create a similar cron job to run puppet apply instead of puppet agent:
$ sudo puppet resource cron puppet-apply ensure=present user=root minute=30 command='/usr/bin/puppet apply $(puppet apply --configprint manifest)'
Sign the New Node’s Certificate
In an agent/master deployment, an admin must approve a certificate request for each agent node before that node can fetch configurations. Agent nodes will request certificates the first time they attempt to run.
- Periodically log into the CA puppet master server and run
sudo puppet cert listto view outstanding requests.
sudo puppet cert sign <NAME>to sign a request, or
sudo puppet cert sign --allto sign all pending requests.
An agent node whose request has been signed on the master will run normally on its next attempt.
Classify the Node
At this point, the new agent node will fetch and apply configurations from the puppet master server. It’s up to you to make sure the configurations it fetches will actually do something. You can do this by assigning Puppet classes to the node.