README.md

Puppet Automation Demo

This demo demonstrates how to write a manifest using Puppet to configure switches running Cumulus Linux and servers running Ubuntu. This manifest configures a CLOS topology running BGP unnumbered in the fabric with Layer 2 bridges to the hosts, and installs a webserver on one of the hosts to serve as a Hello World example. When the demo runs successfully, any server on the network should be able to access the webserver via the BGP routes established over the fabric.

Topology Diagram

This demo runs on a spine-leaf topology with two single-attached hosts. Each device's management interface is connected to an out-of-band management switch and bridged with the out-of-band management server that runs the Puppetserver.

Setting up the Infrastructure

Puppet uses a client-server model where a Puppet agent runs on each device in the network and periodically polls the Puppetserver daemon to check for updated configuration. To install the Puppetserver:

Puppet configuration is broken up into environments, which can be found in /etc/puppetlabs/code/environments. Puppet environments are usually used to separate production from testing code. Each puppet agent is assigned to an environment (default production) and pulls the appropriate code from the server. This demo provides a production environment that can be dropped or symlinked directly into that folder. Assuming you cloned the repository into the cumulus user's home directory:

Back on the puppet agent, run the test command again. The test command manually triggers puppet to check for new configuration and applies it if it finds it.

/opt/puppetlabs/bin/puppet agent --test

Assuming everything worked, run the following command to enable the puppet agent in the background. Roughly every 30 minutes, the puppet agent will attempt to query the puppetmaster for updated configuration. To force a client to update, run the test command again.

sudo service puppet start

Anatomy of a Puppet Environment

hieradata/

This folder contains the data received via hiera, Puppet's tool for pulling variables. When a hiera is called, variables will be pulled from fully.qualified.domain.name.yaml, and will fall back to common.yaml if the file does not exist or if the variable is missing.

manifests/site.pp

This file includes the node definitions for each device. In this file, each device in the network receives a node definition based on its hostname. Multiple devices can subscribe to the same node definition using regular expression matching, but each node must be mutually exclusive. Since we install an extra module on server02, server01 needs its own block. While this file could technically contain any puppet code, conventionally this file is kept very lean only including code in modules.

modules/

Puppet code is broken into packages called "modules", and are included in the node definitions in the top-level manifest. Each module generally installs and configures a single package.

manifests/init.pp: This file contains the actual puppet code that installs and configures the node.

templates/ - configuration file templates, written using Jinja2

files/ - files to be copied to target hosts without modification

Expanding the Network

To add a new device, add the new hostnames to the site.pp file and add the appropriate variables to the hieradata to connect them with the rest of the network. In a well-written manifest, templates and tasks should not need to be changed when new devices are added to the infrastructure. If you are using the reference topology, you can run vagrant up leaf03 server03 to add a third host and tor to the infrastructure, and install the puppet agent on the new devices.