improve isolated docs

Author: sjpb

docs/experimental/isolated-clusters.md

@@ -9,7 +9,8 @@ all "default" features, i.e. roles/groups which are enabled either in the
 `common` environment or in the `environments/$ENV/inventory/groups` file
 created by cookiecutter for a new environment.
 
-The full list of features and whether they are functional on such an "isolated" network is shown in the table below. Note that:
+The full list of features and whether they are functional on such an "isolated"
+network is shown in the table below. Note that:
 
 1. The `hpl` test from the `ansible/adhoc/hpctests.yml` playbook is not
    functional and must be skipped using:
@@ -21,8 +22,8 @@ The full list of features and whether they are functional on such an "isolated"
 2. Using [EESSI](https://www.eessi.io/docs/) necessarily requires outbound
    network access for the CernVM File System. However this can be provided
    via an authenticated proxy. While the proxy configuration on the cluster node
-   is readable by all users, this proxy can provide access only to EESSI's
-   CVMFS Stratum 1 servers.
+   is readable by all users, this proxy could be limited via acls to only provide
+   access to EESSI's CVMFS Stratum 1 servers.
 
 ## Support by feature for isolated networks
 
@@ -47,6 +48,7 @@ See above for definition of "Default" features. In the "Isolated?" column:
 | fail2ban              | Y | Y | 
 | filebeat              | Y | Y | 
 | firewalld             | Y | Y | 
+| freeipa_client        | - | Y - image build required |
 | gateway               | n/a | n/a - build only | 
 | grafana               | Y | Y | 
 | hpctests              | Y | Y  - except hpl-solo, see above | 
@@ -78,12 +80,50 @@ See above for definition of "Default" features. In the "Isolated?" column:
 | tuned                 | - | Y | 
 | update                | - | No |
 
+## Image build
+A site image build may be required, either for features using packages not
+present in StackHPC images (e.g `freeipa_client`) or to [add additional packages](../operations.md#adding-additional-packages).
+Clearly in this case the build VM does require outbound internet access. For an
+"isolated" environment, this could be achieved by [configuring image build](../image-build.md)
+to use a different network from the cluster. Alternatively if an authenticated
+proxy is avaiable the image build can be configured to use that, e.g.:
+
+```yaml
+# environments/$ENV/builder.pkrvars.hcl:
+...
+inventory_groups = 'proxy,freeipa_client'
+```
+
+```yaml
+# environments/$ENV/group_vars/builder/overrrides.yml:
+proxy_basic_user: someuser
+proxy_basic_password: "{{ vault_proxy_basic_password }}"
+proxy_http_address: squid.mysite.org
+```
+
+```yaml
+# environments/$ENV/group_vars/builder/vault_overrrides.yml:
+# NB: vault-encrypt this file
+vault_proxy_basic_password: 'super-secret-password'
+```
+
+See [ansible/roles/proxy/README.md](../../ansible/roles/proxy/README.md) and
+the convenience variables at
+[environments/common/inventory/group_vars/all/proxy.yml](../../environments/common/inventory/group_vars/all/proxy.yml).
+
+By default, the proxy configuration will be removed at the end of the build and
+hence will not be present in the image.
+
 ## Network considerations
 
-Even when outbound internet access is not required, nodes do require some outbound access, as well as connectivity inbound from the deploy host and
-inbound connectivity for users. This section documents the minimal connectivity required, in the form of the minimally-permissive security group rules. Often default security groups are less restrictive than these.
+Even when outbound internet access is not required, nodes do require some
+outbound access, as well as connectivity inbound from the deploy host and
+inbound connectivity for users. This section documents the minimal connectivity
+required, in the form of the minimally-permissive security group rules. Often
+default security groups are less restrictive than these.
 
-Assuming nodes and the deploy host have a security group `isolated` applied then the following rules are required:
+Assuming nodes and the deploy host have a security group `isolated` applied then
+the following rules are required:
 
     # allow outbound DNS
     ALLOW IPv4 53/tcp to 0.0.0.0/0
@@ -99,15 +139,18 @@ Assuming nodes and the deploy host have a security group `isolated` applied then
     # optionally: allow hosts to reach squid proxy for EESSI:
     ALLOW IPv4 3128/tcp to <squid cidr>
 
-Note that name resolution happens on the hosts, not on the proxy, hence DNS is required for nodes even with a proxy.
+Note that name resolution happens on the hosts, not on the proxy, hence DNS is
+required for nodes even with a proxy.
 
 For nodes running OpenOndemand, inbound ssh and https are also required
 (e.g. in a security group called `isolated-ssh-https`):
 
     ALLOW IPv4 443/tcp from 0.0.0.0/0
     ALLOW IPv4 22/tcp from 0.0.0.0/0
 
-If non-default security groups are required, then the OpenTofu variables `login_security_groups` and `nonlogin_security_groups` can be used to set these, e.g.:
+If non-default security groups are required, then the OpenTofu variables
+`login_security_groups` and `nonlogin_security_groups` can be used to set
+these, e.g.:
 
 ```terraform
 # environments/site/tofu/cluster.auto.tfvars:

docs/networks.md

@@ -6,9 +6,10 @@ subnets or associated infrastructure such as routers. The requirements are that:
 2. The first network defined spans all nodes, referred to as the "access network".
 3. Only one subnet per network is attached to nodes.
 4. At least one network on each node provides outbound internet access (either
-directly, or via a proxy).
+   directly, or via a proxy). In some cases this can be relaxed - see
+   [docs/experimental/isolated-clusters.md](./experimental/isolated-clusters.md).
 
-Addresses on the "access network" used as the `ansible_host` IPs.
+Addresses on the "access network" are used as the `ansible_host` IPs.
 
 It is recommended that the deploy host either has a direct connection to the
 "access network" or jumps through a host on it which is not part of the appliance.

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

@@ -16,6 +16,7 @@ proxy_http_port: "{{ squid_http_port }}"
 # whether to remove the proxy configuration at the end of Ansible runs:
 # (useful for image build where this should not be captured in the image)
 proxy_remove: false
+# NB for the `builder` group this defaults to true
 
 # full http proxy string - override if the above don't provide enough control:
 proxy_http_proxy: >-

environments/common/layouts/everything

@@ -59,6 +59,9 @@ compute
 # Hosts to manage /etc/hosts e.g. if no internal DNS. See ansible/roles/etc_hosts/README.md
 cluster
 
+[freeipa_client]
+# Hosts to be a FreeIPA client. See ansible/roles/freeipa/README.md
+
 [cuda]
 # Hosts to install NVIDIA CUDA on - see ansible/roles/cuda/README.md