A simplistic classroom non-root user/package/service management simulation.
OTHER License
Walking students through the PE installation process is counterproductive. Requiring them to manage their own virtual machine and debug networking issues takes up a great deal of classroom time.
This project was designed to eliminate that need. Students can create user accounts with the click of a button, allowing them to work along with exercises without the overhead of managing a full VM.
Puppetfactory is pluggable and highly configurable. By default, it provides just a user account and a standard shell login embedded in a web page. Add in the Docker plugin and that user account then logs into a container. Add in the Classification plugin and PE Console node groups and classification rules will be managed automatically. Add in either the R10k or CodeManager plugin and sources will be managed, allowing the user to deploy a codebase from a control repository.
The accompanying pltraining/puppetfactory
Puppet module will build a Docker
image suitable for fully comprehensive Puppet agent nodes and stand up the
components of the Puppetfactory stack.
Users should have their shell set to pfsh
, which is located in /usr/local/bin
by default. It will request the current session ID, and then invoke the login
action of whichever plugin is currently configured.
If this is being used for a Puppet training class, each course should have a
pltraining/classroom
profile associated with it. The module should be
installed into the global modulepath
puppet module install pltraining/classroom --modulepath /etc/puppetlabs/code/modules
classroom::course::<name>
.Students will need to use the Users tab to create their accounts. This tab will also list all known users along with statuses, including useful information about their accounts; certname, Console login, etc.
They can use their username to SSH to the master, either from their own client or from the SSH Login tab. Their Console login will use the same password.
Run puppetfactory configprint
to get a printout of all the configuration
settings. If no config file exists, this will be all the default options. To
change any of the options, add them to the /etc/puppetfactory/config.yaml
config file.
Most of the options are self explanatory. Some that you may want to configure include:
:port
:bind
0.0.0.0
means bind to all.:user
:password
:session
Container options:
:puppetcode
:modulepath
:readwrite
, :readonly
, or :none
Code management options:
:gitserver
, :gituser
, :controlrepo
:repomodel
:single
, :peruser
Enable plugins to configure how Puppetfactory works by adding them to the :plugins
option:
:plugins:
- :Certificates
- :Classification
- :Docker
- :Logs
- :Dashboard
- :CodeManager
- :ShellUser
List of current plugins:
:Certificates
:Classification
:CodeManager
:ConsoleUser
:Dashboard
:dashboard_path
:dashboard_interval
:Docker
:container_name
:privileged
systemd
.:Github
:githubtoken
:Gitlab
:Gitviz
:Hooks
:hooks_path
:LoginShell
pfsh
will run the system shell.:Logs
:R10k
r10k
sources for each user.:ShellUser
:UserEnvironment
Puppetfactory's plugin model is simple. Each time an action is called, that action
is invoked on each plugin that exposes it. That means that if your plugin has a
method named create
, then it will be invoked with two arguments, (the new user's
username and password) each time a new user is created.
Plugins are sorted by their weight
property, low to high. The default weight is
100, and the ShellUser
weight is 1, indicating that it should run first when enabled.
See the Example
plugin in lib/puppetfactory/plugins/example.rb
for an
explanation of each action. The plugin class name must match the filename, where
the class name is CamelCased
and the file is snake_cased
.
Plugins can also add new tabs and new web routes. See the Logs
plugin for a
simple example of that.
Several components and services work together to make up the Puppetfactory
stack. It's recommended to use the pltraining/puppetfactory
module to manage
the full stack.
This is the actual graphical Web UI allowing the students to interact with the system. It allows students to create their own user account and provides a tab for an SSH console login.
This is the web terminal embedded in the SSH console tab.
This is used to proxy the services into a cohesive whole, including exposing HTTP for each student container if configured to do so.
The default container service used by Puppetfactory. This provides students full root access to their own Puppet agent node.
Because we're using docker containers for the student environments there are a few things you can do to troubleshoot.
Run puppetfactory --help
on the master to see commands to create, remove, or
repair user accounts.
If you need to access a student environment:
su - #{username}
To interact directly with a container (assuming the Docker plugin):
docker start #{username}
docker stop #{username}
docker info #{username}
The containers also have valid init scripts so they can be start/stopped with:
systemctl start docker-#{username}
systemctl stop docker-#{username}
Users can be created by treating the classroom manager like a RESTful API:
curl --data 'username=fooh&password=bar' admin:admin@localhost/new
There are also the following RESTful API endpoints:
GET /api/users
GET /api/users/:username
GET /api/users/:username/port
GET /api/users/:username/node_group_status
GET /api/users/:username/consoe_user_status
POST /api/users
DELETE /api/users/:username
Note: These are mostly intended for use in a future UI, but they can be helpful for troubleshooting.
Special thanks to Britt Gresham for the inspiration for this project: https://github.com/demophoon/webvim