reshuffling info to puppet

infrastructure-guide/puppet/modules.md

@@ -0,0 +1,107 @@
+# Modules
+
+The repository for the Puppet role/profile modules is <https://git.psi.ch/linux-infra/puppet>.
+
+
+So we have some roles that are generic PSI-wide (eg. `role::server`) while
+some roles that are specific to some projects and have a dedicated namespace (e.g. `role::hpc::database`).
+
+For the profiles we have
+
+
+- `profile::ssh_client`
+- `profile::afs_client`
+- `profile::log_client`
+- `profile::mysql_server`
+- ...
+
+For profiles maybe we will not need namespace areas dedicated to
+specific projects, since profiles should be generic enough to be
+reusable.
+
+
+Components are gernerally useful Puppet modules and they reside in an own git repository and are handled like any other externally used module.
+
+
+## Hiera queries
+
+Only profiles and roles query Hiera. Components should take all their inputs as
+parameters or facts.
+
+In profiles, Hiera queries must generally be done as default arguments to
+parameters, **not** inside the modules body
+
+```
+class profile::logging (
+    $forward_to = lookup('...'),
+    $persistent_journal = lookup('...'),
+)
+{
+```
+
+The reason is that this allows a role to enforce certain parameters and disable
+the corresponding Hiera query.
+
+
+## Layout
+
+Roles and profiles are usually implemented in a single file, e.g.
+`code/profile/manifests/logging.pp`. Components on the other hand follow the
+standard Puppet layout, i.e.
+`auditd/manifests/{init,install,config,service}.pp`.
+
+## Files and templates
+
+Every file or template should be used by only one class and its path inside the
+module should reflect this. Eg. if the template `sshd_config.erb` is used by
+the `profile::ssh_server` module, it will be places inside the
+`templates/profile/ssh_server` directory.
+
+Furthermore, on top of every file managed by puppet, a header like the
+following should be present:
+
+```
+########################################################################
+#
+# THIS FILE IS MANAGED BY PUPPET - DO NOT MODIFY!
+#
+# profile::ssh_server
+# sshd_config.erb
+#
+########################################################################
+```
+
+The last two lines should be:
+
+  - the puppet class using the file;
+  - the name of the file/template.
+
+## Debugging templates
+
+You can use the `erb` tool to test the variable interpolation. One easy way is to prepare a file with the variable values and pipe it together with the template through erb. Define the variables in a file `test-vars.erb` like in this example
+
+```
+<%
+@partitions = {'a' => 'aa', 'b' => 'bb', 'c' => 'cc'}
+@group_whitelist = ['groupA', 'groupB']
+@port = 8000
+%>
+```
+
+and then use a commmand line like the following to pipe it through `erb`
+
+```
+erb <(cat /tmp/test-vars.erb /tmp/my-template.erb)
+```
+
+The output will contain the variable substituted template. If you want to check your
+template for syntax errors, you can just use the following command
+
+```
+erb -P -x -T '-' jupyterhub_config.py.erb | ruby -c
+```
+
+## Contents
+
+```{tableofcontents}
+```