docs updates

Author: wtripp180901

cookiecutter/{{cookiecutter.environment}}/ansible.cfg

@@ -11,7 +11,7 @@ roles_path = ../../ansible/roles
 filter_plugins = ../../ansible/filter_plugins
 
 [ssh_connection]
-ssh_args = -o ControlMaster=auto -o ControlPath=~/.ssh/%r@%h-%p -o ControlPersist=240s -o PreferredAuthentications=publickey -o UserKnownHostsFile=/dev/null
+ssh_args = -o ServerAliveInterval=10 -o ControlMaster=auto -o ControlPath=~/.ssh/%r@%h-%p -o ControlPersist=240s -o PreferredAuthentications=publickey -o UserKnownHostsFile=/dev/null
 pipelining = True
 
 [inventory]

cookiecutter/{{cookiecutter.environment}}/tofu/main.tf

@@ -8,5 +8,14 @@ module "cluster" {
     environment_root = var.environment_root
 
     # Environment specific variables
-    # cluster_name = "foo"
+    # Note that some of the variables below may need to be moved to the site environment
+    # defaults e.g cluster_networks should be in site if your staging and prod
+    # environments use the same networks
+    cluster_name = 
+    cluster_image_id = 
+    control_node_flavor = 
+    cluster_networks = 
+    key_pair = 
+    login = 
+    compute = 
 }

docs/production.md

@@ -109,7 +109,9 @@ and referenced from the `site` and `production` environments, e.g.:
 - Configure Open OnDemand - see [specific documentation](openondemand.md) which
   notes specific variables required.
 
-- Remove the `demo_user` user from `environments/$ENV/inventory/group_vars/all/basic_users.yml`
+- Remove the `demo_user` user from `environments/$ENV/inventory/group_vars/all/basic_users.yml`.
+  Replace the `hpctests_user` in `environments/$ENV/inventory/group_vars/all/hpctests.yml` with
+  an appropriately configured user.
 
 - Consider whether having (read-only) access to Grafana without login is OK. If not, remove `grafana_auth_anonymous` in `environments/$ENV/inventory/group_vars/all/grafana.yml`
 

docs/upgrades.md

@@ -41,6 +41,12 @@ All other commands should be run on the Ansible deploy host.
    prompts. Generally merge conflicts should only exist where functionality which was added
    for your site (not in a hook) has subsequently been merged upstream.
 
+   Note that if upgrading from a release prior to v2.3, you will likely have merge conflicts
+   with existing site OpenTofu configurations in `environments/site/tofu`. Generally
+   - Changes to `default` values in `environments/site/tofu.variables.tf` should be rejected.
+   - All other changes to the OpenTofu configuration should be accepted, unless they overwrite
+     site-specific additional resources.
+
 1. Push this branch and create a PR:
 
         git push
@@ -51,8 +57,9 @@ All other commands should be run on the Ansible deploy host.
    backward compatible. Alteration of site-specific configuration will usually only be
    necessary to use new functionality or where functionality has been upstreamed as above.
    Note that the upstream `environments/site/inventory/groups` file contains all possible
-   groups which can be used to enable features, check for new groups which have been added in the
-   latest release and remove any which are unnescessary from the `groups` file in your fork.
+   groups which can be used to enable features. This will be updated when pulling changes
+   from the StackHPC repo, and any new groups should be enabled/disable as required for
+   your site.
 
    Make changes as necessary.
 

environments/.caas/inventory/group_vars/all/nfs.yml

@@ -5,7 +5,7 @@ caas_nfs_home:
     nfs_enable:
         server:  "{{ inventory_hostname in groups['control'] }}"
         clients: "{{ inventory_hostname in groups['cluster'] }}"
-    nfs_export: "/exports/home" # assumes upstream site TF is being used
+    nfs_export: "/exports/home" # assumes default site TF is being used
     nfs_client_mnt_point: "/home"
 
 nfs_configurations: "{{ caas_nfs_home if not cluster_home_manila_share | bool else [] }}"

environments/README.md

@@ -39,8 +39,6 @@ how to provision the infrastructure. This environment should not be edited, exce
 
 Provides the base configuration for all subsequent `cookiecutter` created environments,
 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.
 
 
 ## Defining an environment

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

@@ -18,7 +18,7 @@ nfs_configuration_home_volume: # volume-backed home directories
         # Don't mount share on control node:
         clients: "{{ inventory_hostname in groups['cluster'] and inventory_hostname not in groups['control'] }}"
     nfs_server: "{{ nfs_server_default }}"
-    nfs_export: "/exports/home" # assumes upstream site TF is being used
+    nfs_export: "/exports/home" # assumes default site TF is being used
     nfs_client_mnt_point: "/home"
     # prevent tunnelling and setuid binaries:
     # NB: this is stackhpc.nfs role defaults but are set here to prevent being