General
=======

`Puppet <https://puppetlabs.com>`_ is the *configuration management system* used to configure the hosts.

Introduction
------------

Puppet is used in master mode and the general idea is to make large
use of indipendent and (relatively) small puppet
modules and composing profiles and roles based on them to create
classes that are assigned to the hosts. With indipendence
of puppet modules we mean that each puppet module targets a single
functionality (eg. `web server`, `afs client`) and this
is choosen to keep the code of the single module smaller, more
coherent and easier to debug.

Furthermore the system makes use of some puppet modules from the `puppet forge
<https://forge.puppet.com>`_. These puppet modules are not accessed directly but
through their PSI mirror, inside of the `Linux-infra group <https://git.psi.ch/linux-infra>`_.

Code and data are kept separated, using puppet modules
for code and hiera for data. Secure data are safely managed
inside hiera using `hiera eyaml <https://github.com/TomPoulton/hiera-eyaml>`_.

To each host the following element will determine how it will be configured:

- the puppet environment (that will determine the puppet role/profile code base)
- the sysdb data environment (that will determine the hiera code base)
- the puppet group (that will determine what files will be considered in the hiera code base)
- the role

All these elements are configured inside sysdb as attributes and are accessed
by the puppet master via the ENC.

Here you can get a general overview:

.. following image generated from https://docs.google.com/drawings/d/16AXZd5PF-HgW379Cxgvwzvc6MTl_34LVFHzP5Fi8RdQ/edit

.. image:: puppet_workflow.jpg



Environments
------------

We use Puppet environments for two purposes:

- roll out changes to a small subset of all systems first
- module development


The following environments exist:

- ``prod``

  The most stable, and most systems are attached to it. All changes to ``prod``
  have to go through ``preprod`` first.

- ``preprod``

- Development environments. These are private to a single developer,
  can have arbitrary names like ``ganglia-issue-21`` or
  ``kaminski_k-log_client``, and are used for developing and testing
  changes. Generally, only individual systems are attached to these
  environments.


  
puppet master
-------------

The puppet master will make use of the `ENC
<https://puppet.com/docs/puppet/7/nodes_external.html#external-node-classifiers>`_ for getting
two informations:

  - the environment;
  - the role.

The environment is used to determine the directory location inside
`/etc/puppetlabs/code/environments` where to look code for.

The role is a class-name inside the specific environment that will be
used to generate the node catalog.

Assuming for example the following result from the ENC for a specific node: ::

  ---
     environment: production
     classes:
       - role::log_server

the puppet master will look for the a puppet class named
``role::log_server`` in the file
`/etc/puppetlabs/code/environments/productions/modules/psi/manifests/role/log_server.pp`.

