reflect the ENC/roles work done in team#40358

howto/puppet.md

@@ -411,11 +411,12 @@ See [howto/cumin](howto/cumin) for more examples.
 
 If you are making a major change to the infrastructure, you may want
 to deploy it progressively. A good way to do so is to include the new
-class manually in the node configuration, say in
-`hiera/nodes/$fqdn.yaml`:
+class manually in an existing role, say in
+`modules/role/manifests/foo.pp`:
 
-    classes:
-      - my_new_class
+    class role::foo {
+      include my_new_class
+    }
 
 Then you can check the effect of the class on the host with the
 `--noop` mode. Make sure you disable Puppet so that automatic runs do
@@ -1175,6 +1176,50 @@ Otherwise the style already in use in the file should be followed.
 [Flycheck]: http://flycheck.org/
 [vim-puppet]: https://github.com/rodjek/vim-puppet
 
+### ENC
+
+ENC stands for External Node Classifier. When implemented, as is the
+case here, it causes the Puppet server to request information about
+a node before a catalog is compiled.
+
+It can be used on the Puppet server to define three elements about
+nodes:
+
+ * **Environment**: is the standard way to assign nodes to a
+ Puppet environment. The default is `production` which is the only
+ environment currently deployed.
+ * **Parameters**: is a hash where each key is made available as a
+ top-scope variable in a node's manifests. We use this assign a unique
+ role to each node. This role is in turn used to include a `role::foo`
+ class which should only consist of a set of profile classes.
+ * **Classes**: is an array of class names which Puppet includes
+ on the target node. We are currently transitioning from this method
+ of including classes on nodes (previously in Hiera) to the `role`
+ parameter and unique role classes.
+
+These elements are defined in `/etc/puppet/hiera-enc/nodes/$fqdn.yaml`.
+
+#### Role classes
+
+Each host defined in the ENC declares which unique role it should be
+attributed through the `parameter` hash. For example, this is what
+configures a GitLab runner:
+
+    parameters:
+      - role: gitlab::runner
+
+Roles should be *abstract* and *not* implementation specific. Each
+role class includes a set of profiles which *are* implementation
+specific. For example, the `monitoring` role includes
+`profile::prometheus::server` and `profile::grafana`.
+
+As a temporary exception to this rule, old modules can be included as
+we transition from the Hiera mechanism, but eventually those should
+be ported to shared modules from the Puppet forge, with our glue built
+into a profile on top of the third-party module. The role
+`role::gitlab` follows that pattern correctly. See [issue 40030][] for
+progress on that work.
+
 ### Hiera
 
 [Hiera][] is a "key/value lookup tool for configuration data" which
@@ -1187,30 +1232,32 @@ currently use Hiera.
 
 [Hiera]: https://puppet.com/docs/hiera/
 
-#### Classes definitions
+#### Common configuration
 
-Each host declares which class it should include through a `classes`
-parameter. For example, this is what configures a Prometheus server:
+Class parameters which are common across several or all roles can be
+defined in `hiera/common.yaml` to avoid duplication at the role level.
 
-    classes:
-      - roles::monitoring
+However, unless this parameter can be expected to change or evolve over
+time, it's sometimes preferable to hardcode some parameters directly in
+profile classes in order to keep this dataset from growing too much,
+which can impact performance of the Puppet server and degrade its
+readability. In other words, it's OK to place site-specific data in
+profile manifests, as long as it may never or very rarely change.
 
-Roles should be *abstract* and *not* implementation specific. Each
-role includes a set of profiles which *are* implementation
-specific. For example, the `monitoring` role includes
-`profile::prometheus::server` and `profile::grafana`. Do *not* include
-profiles directly from Hiera.
+These parameters can be override by role and node configurations.
 
-As a temporary exception to this rule, old modules can be included as
-we transition from the `has_role` mechanism to Hiera, but eventually
-those should be ported to shared modules from the Puppet forge, with
-our glue built into a profile on top of the third-party module. The
-role `roles::monitoring` follows that pattern correctly. See [issue
-40030][] for progress on that work.
+#### Role configuration
+
+Class parameters specific to a certain node role are defined in
+`hiera/roles/${::role}.yaml`. This is the principal method by which we
+configure the various profiles, thus shaping each of the roles we
+maintain.
+
+These parameters can be override by node-specific configurations.
 
 #### Node configuration
 
-On top of the host configuration, some node-specific configuration can
+On top of the role configuration, some node-specific configuration can
 be performed from Hiera. This should be avoided as much as possible,
 but sometimes there is just no other way. A good example was the
 `build-arm-*` nodes which included the following configuration: