docuiment issues with Hiera and roles, particularly with team#40030

howto/puppet.md

@@ -686,7 +686,7 @@ checkout are not writable by your user. It could also happen that the
 repository itself (in `/srv/puppet.torproject.org/git/tor-puppet`)
 could have permission issues.
 
-This problem is described in [issue 29663](https://gitlab.torproject.org/tpo/tpa/team/-/issues/29663) and is due to someone
+This problem is described in [issue 29663][] and is due to someone
 not pushing properly before you. To fix the permissions, try:
 
     sudo chown -R root:adm /etc/puppet
@@ -694,6 +694,8 @@ not pushing properly before you. To fix the permissions, try:
     sudo chmod -R g+rw /etc/puppet
     sudo chmod g-w /etc/puppet/secret
 
+[issue 29663]: https://gitlab.torproject.org/tpo/tpa/team/-/issues/29663
+
 A similar recipe could be applied to the git repository, as
 needed. Hopefully this will be resolved when we start deploying with a
 role account instead.
@@ -734,13 +736,20 @@ the future if we rely more on it for deployments.
 
 ### Before it all starts
 
-- `puppet.tpo` is currently being run on `pauli.tpo`
-- This is where the tor-puppet git repository lives
+- The Puppet server is currently being run on `pauli.torproject.org`
+- This is where the main git repository (`tor-puppet`) lives, in
+  `/srv/puppet.torproject.org/git/tor-puppet`
 - The repository has hooks to populate `/etc/puppet` with its contents, most
   notably the modules directory.
 - All paths in this document are relative to the root of this
   repository.
 
+Note that this layout might change in the future with the introduction
+of a role account ([issue 29663][]) and when/if the repository is made
+public (which requires changing the layout, see [issue 29387][]).
+
+[issue 29387]: https://gitlab.torproject.org/tpo/tpa/team/-/issues/29387
+
 ### File layout
 
 - `3rdparty/modules` include modules that are shared publicly and do
@@ -754,8 +763,14 @@ the future if we rely more on it for deployments.
 - `modules` includes roles, profiles, and classes that make the bulk
   of our configuration.
 
-- in there, the `roles` class (`modules/roles/manifests/init.pp`) maps
-  services to roles, using the `$nodeinfo` variable.
+- each node is assigned a "role" through Hiera, in
+  `hiera/nodes/$FQDN.yaml`
+
+  To be more accurate, Hiera assigns a Puppet class to each node,
+  although each node should have only one special purpose class, a
+  "role", see [issue 40030][] for progress on that transition.
+
+[issue 40030]: https://gitlab.torproject.org/tpo/tpa/team/-/issues/40030
 
 - The `torproject_org` module
   (`modules/torproject_org/manifests/init.pp`) performs basic host
@@ -783,19 +798,25 @@ the future if we rely more on it for deployments.
   the `manifests/site.pp` file, but this file is now mostly empty, in
   favor of Hiera.
 
-Note that the above is the current state of the file hierarchy. As part
-of the transition to Hiera, a lot of the above architecture will
-change in favor of the more standard [role/profile/module][]
-pattern. See [ticket #29387][] for an in-depth discussion.
+Note that the above is the current state of the file hierarchy. As
+part Hiera transition ([issue 30020][]), a lot of the above
+architecture will change in favor of the more standard
+[role/profile/module][] pattern. See [ticket #29387][] for an in-depth
+discussion.
 
 [role/profile/module]: https://puppet.com/docs/pe/2017.2/r_n_p_intro.html
 [ticket #29387]: https://bugs.torproject.org/29387
+[issue 30020]: https://bugs.torproject.org/30020
+
+### Installed packages facts
 
-### Custom facts
+The `modules/torproject_org/lib/facter/software.rb` file defines our
+custom facts, making it possible to get answer to questions like "Is
+this host running `apache2`?" by simply looking at a puppet
+variable. 
 
-`modules/torproject_org/lib/facter/software.rb` defines our custom
-facts, making it possible to get answer to questions like "Is this
-host running `apache2`?" by simply looking at a puppet variable.
+Those facts are deprecated and we should instead install packages
+through Puppet instead of manually installing packages on hosts.
 
 ### Style guide
 
@@ -847,7 +868,8 @@ 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.
+role `roles::monitoring` follows that pattern correctly. See [issue
+40030][] for progress on that work.
 
 #### Node configuration