howto/puppet.md

@@ -1529,16 +1529,16 @@ started with the vocabulary used in this document.
 
 The Puppet server runs on `pauli.torproject.org`.
 
-Two git repositories live there:
+Two bare-mode git repositories live on this server, below
+`/srv/puppet.torproject.org/git`:
 
-- `tor-puppet-hiera-enc`, at
-  `/srv/puppet.torproject.org/git/tor-puppet-hiera-enc.git`: That
-  repository has hooks that deploy to `/etc/puppet/hiera-enc`. See the
+- `tor-puppet-hiera-enc.git`, the external node classifier (ENC) code and data.
+  This repository has a hook that deploys to `/etc/puppet/hiera-enc`. See the
   "External node classifier" section below.
 
-- `tor-puppet`, at `/srv/puppet.torproject.org/git/tor-puppet.git`:
-  That repository has hooks that deploy to
-  `/etc/puppet/code/environments/production`. See the "Environments"
+- `tor-puppet.git`, the puppet environments, also referred to as the "control
+  repository". Contains the puppet modules and data. That repository has a
+  hook that deploys to `/etc/puppet/code/environments`. See the "Environments"
   section below.
 
 #### External node classifier
@@ -1551,7 +1551,8 @@ using the `tor-puppet-hiera-enc.git` repository. The node definitions at
 
 To be more accurate, the ENC assigns top-scope `$role` variable to each node,
 which is in turn used to include a `role::$rolename` class on each node. This
-occurs in the default node definition in `manifests/site.pp` in `tor-puppet.git`.
+occurs in the default node definition in `manifests/site.pp` in
+`tor-puppet.git`.
 
 Some nodes include a list of classes, inherited from the previous Hiera-based
 setup, but we're in the process of transitioning all nodes to single role
@@ -1561,7 +1562,27 @@ classes, see [issue 40030][] for progress on this work.
 
 #### Environments
 
-All paths below are relative to the root of that git repository.
+Environments on the Puppet Server are managed using `tor-puppet.git` which is
+our "control repository". Each branch on this repo is mapped to an environment
+on the server which takes the name of the branch, with the exception of `main`,
+which is mapped to the default environment `production`.
+
+This deployment is orchestrated using a git `pre-receive` hook that's managed
+via the `profile::puppet::server` class and the `puppet` module.
+
+In order to test a new branch/environment on a Puppet node after being pushed
+to the control repository, additional configuration needs to be done in
+`tor-puppet-hiera-enc.git` to specify which node(s) should use the test
+environment instead of `production`. This is done by editing the
+`nodes/<name>.yaml` file and adding an `environment:` key at the document root.
+
+Once the environment is not needed anymore, the changes to the ENC should be
+reverted before the branch is deleted on the control repo using `git push
+--delete <branch>`. The git hook will take care of cleaning up the environment
+files under `/etc/puppet/code/environments`.
+
+The environments themselves are structured as follows. All paths are relative
+to the root of that git repository.
 
 - `3rdparty/modules` include modules that are shared publicly and do
   not contain any TPO-specific configuration. There is a `Puppetfile`