use home_volume_provisioning

Author: sjpb

docs/production.md

@@ -58,7 +58,7 @@ and referenced from the `site` and `production` environments, e.g.:
 
     Note that:
         - Environment-specific variables (`cluster_name`) should be hardcoded
-          into the module block.
+          into the cluster module block.
         - Environment-independent variables (e.g. maybe `cluster_net` if the
           same is used for staging and production) should be set as *defaults*
           in `environments/site/tofu/variables.tf`, and then don't need to
@@ -76,18 +76,37 @@ and referenced from the `site` and `production` environments, e.g.:
   instances) it may be necessary to configure or proxy `chronyd` via an
   environment hook.
 
-- The cookiecutter provided OpenTofu configurations define resources for home and
-  state volumes. The former may not be required if the cluster's `/home` is
-  provided from an external filesystem (or Manila). In any case, in at least
-  the production environment, and probably also in the staging environment,
-  the volumes should be manually created and the resources changed to [data
-  resources](https://opentofu.org/docs/language/data-sources/). This ensures that even if the cluster is deleted via tofu, the
-  volumes will persist.
-
-  For a development environment, having volumes under tofu control via volume
-  resources is usually appropriate as there may be many instantiations
-  of this environment.
-
+- By default, the cookiecutter provided OpenTofu configurations provision
+  a volume named "$cluster_name-state" and attach it to the control node. This
+  is used to persist monitoring and Slurm data when the control node is re-built.
+  In production environments (and probably staging) it is undesirable to have
+  this volume deleted if the cluster is deleted. Therefore the volume should be
+  manually created, e.g. via the CLI:
+
+      openstack volume create --size 100 mycluster-home # size in GB
+
+  and OpenTofu configured to use that volume rather than managing one itself
+  by setting
+
+      home_volume_provisioning = "attach"
+
+  either for a specific environment in the cluster module block in
+  `environments/$ENV/tofu/main.tf`, or as the site default by changing the
+  default in `environments/site/tofu/variables.tf`.
+  
+  For a development environment allowing OpenTofu to manage the volume using
+  the default value
+  
+      home_volume_provisioning = "manage"
+  
+  is usually appropriate, as it allows for multiple clusters to be created with
+  this environment.
+  
+  If no home volume at all is required because the home directories are provided
+  by a parallel filesystem (e.g. manila) use
+
+      home_volume_provisioning = "none"
+  
 - Enable `etc_hosts` templating:
 
     ```yaml

environments/skeleton/{{cookiecutter.environment}}/tofu/control.tf

@@ -87,7 +87,7 @@ resource "openstack_compute_instance_v2" "control" {
 
     mounts:
       - [LABEL=state, ${var.state_dir}]
-      %{if var.home_volume_size > 0}
+      %{if var.home_volume_provisioning != "none"}
       - [LABEL=home, /exports/home]
       %{endif}
   EOF

environments/skeleton/{{cookiecutter.environment}}/tofu/variables.tf

@@ -132,11 +132,14 @@ variable "state_volume_type" {
 
 variable "home_volume_size" {
     type = number
-    description = <<-EOT
-        Size of state volume on control node, in GB. If zero, a volume with the
-        name $cluster_name-home must already exist unless home_volume_enabled = false
-    EOT
+    description = "Size of state volume on control node, in GB."
     default = 100
+    validation {
+        condition = var.home_volume_provisioning == "manage" ? var.home_volume_size > 0 : true
+        error_message = <<-EOT
+            home_volume_size must be > 0 when var.home_volume_provisioning == "manage"
+        EOT
+    }
 }
 
 variable "home_volume_type" {
@@ -145,10 +148,26 @@ variable "home_volume_type" {
     description = "Type of home volume, if not default type"
 }
 
-variable "home_volume_enabled" {
-    type = bool
-    default = true
-    description = "Whether to use a home volume"
+variable "home_volume_provisioning" {
+    type = string
+    default = "manage"
+    description = <<-EOT
+        How to manage the home volume. Valid values are:
+            "manage": (Default) OpenTofu will create a volume "$cluster_name-home"
+                      and delete it when the cluster is destroyed. A volume
+                      with this name must not already exist. Use for demo and
+                      dev environments.
+            "attach": A single volume named "$cluster_name-home" must already
+                      exist. It is not managed by OpenTofu so e.g. is left
+                      intact if the cluster is destroyed. Use for production
+                      environments.
+            "none":   No home volume is used. Use if /home is provided by
+                      a parallel filesystem, e.g. manila.
+        EOT
+    validation {
+      condition = contains(["manage", "attach", "none"], var.home_volume_provisioning)
+      error_message = "home_volume_provisioning must be one of manage, attach or none"
+    }
 }
 
 variable "vnic_types" {

environments/skeleton/{{cookiecutter.environment}}/tofu/volumes.tf

@@ -7,11 +7,10 @@ resource "openstack_blockstorage_volume_v3" "state" {
 
 resource "openstack_blockstorage_volume_v3" "home" {
 
-    # NB: Changes CANNOT be made to this resource's "address"
-    # i.e. (label or for_each key)
-    # else existing clusters may get home volumes deleted and recreated!
+    # NB: Changes to this resource's "address" i.e. (label or for_each key)
+    # will lose user data for existing clusters using this volume
 
-    count = var.home_volume_size > 0 ? 1 : 0
+    count = var.home_volume_provisioning == "manage" ? 1 : 0
 
     name = "${var.cluster_name}-home"  # last word used to label filesystem
     description = "Home for control node"
@@ -21,25 +20,20 @@ resource "openstack_blockstorage_volume_v3" "home" {
 
 data "openstack_blockstorage_volume_v3" "home" {
 
-/*  May or may not have a volume, depending on home_volume_enabled, so this
-    has to use for_each.
-
-    For the case where we use the above provisioned volume resource, we need
-    to create a depenency on it to avoid a race.
-
-    The logic is:
-    - If not home_volume_enabled, there is no volume
-    - Else if home_volume_size > 0 - use the provisioned volume resource
-    - Else find an existing volume with the specified name
-*/
+/*  We use a data resource whether or not TF is managing the volume, so the
+    logic is all in one place. But that means this needs a dependency on the
+    actual resource to avoid a race.
     
-    for_each =  toset(
-                    (var.home_volume_enabled) ? (
-                        (var.home_volume_size > 0) ? 
-                            [for v in openstack_blockstorage_volume_v3.home: v.name] :
-                                ["${var.cluster_name}-home"]
-                    ) : []
-                )
+    Because there may be no volume, this has to use for_each.
+*/
+
+    for_each = toset(
+        (var.home_volume_provisioning == "manage") ?
+            [for v in openstack_blockstorage_volume_v3.home: v.name] :
+                (var.home_volume_provisioning == "attach") ?
+                    ["${var.cluster_name}-home"] :
+                        []
+    )
 
     name = each.key
 }