review comments

Co-authored-by: Steve Brasier <[email protected]>

Author: wtripp180901

docs/production.md

@@ -7,7 +7,7 @@ production-ready deployments.
 - Get it agreed up front what the cluster names will be. Changing this later
   requires instance deletion/recreation.
 
-- At least two environments should be created on top of the `site` base environment:
+- At least two environments should be created using cookiecutter, which will derive from the `site` base environment:
     - `production`: production environment
     - `staging`: staging environment
 

environments/README.md

@@ -33,12 +33,12 @@ for usage instructions for that component.
 
 Shared configuration for all environments. This is not
 intended to be used as a standalone environment, hence the README does *not* detail
-how to provision the infrastructure. This environment generally should not be edited.
+how to provision the infrastructure. This environment should not be edited, except as part of upstreaming new features or bug fixes.
 
 ## site
 
 Provides the base configuration for all subsequent `cookiecutter` created environments,
-including configuration for provisioning infrastructure. Site specific configuration should generally
+including OpenTofu configurations for infrastructure. In general, most local customisations should be made by adding to this environment.
 be edited here, unless it is specific to a particular cookiecutter environment, in which case it should be set in
 that environment.
 

environments/common/inventory/group_vars/all/firewalld.yml

@@ -3,7 +3,7 @@
 
 firewalld_configs_default:
   # A list of dicts defining firewalld rules.
-  # Using the upstream site groups firewalld is deployed on the login node to enable fail2ban.
+  # Using the default site `groups` file, firewalld is deployed on the login node to enable fail2ban.
   # However by default we rely on openstack security groups so make firewalld permissive.
   # Each dict contains:
   #   name: An arbitrary name or description