Guide for tofu openstack config usage

README.md

@@ -49,6 +49,9 @@ The resources defined in your configuration can then be created using:
 tofu apply
 ```
 
+For user guide see [docs/guide.md](docs/guide.md). The `docs/` directory contains
+information and examples for all supported resources.
+
 For more comprehensive examples see the `examples/` directory. The example
 `arcus` demonstrates how to use variables and the [merge function](https://opentofu.org/docs/language/functions/merge/)
 to minimise repeated configuration.
@@ -100,65 +103,6 @@ The "Import?" column refers to support for [importing existing openstack configu
 | Image elements    | No         | N/A      | Considered out of scope |
 | Ratings           | No         | N/A      | |
 
-## Network config example
-The following is an example config for how to use the new network support. A single
-project is defined which contains a single subnet.
-
-Note that:
-- Networks (and their subnets) and routers do not necessarily have to be associated
-with a project. If they are this association can be made with the project's name
-(if the project is controllled by this config) or by a project/tenant id from
-OpenStack (if it is not).
-- The names in OpenStack for networks, subnets and routers are not necessarily unique
-across projects. Therefore these resources have a tofu resource name which must be
-unique across projects, which can be used to refer to them for other resources.
-It is suggested that a convention of using `$NAME:$PROJECT_NAME` is used.
-
-
-```
-module "openstack" {
-  source = "github.com/stackhpc/tofu-openstack-config?ref=main"
-  projects = {
-    "demo-project" = {
-      compute_quota = {
-      }
-      network_quota = {
-      }
-      blockstorage_quota = {
-      }
-    }
-  }
-
-  networks = {
-    "demo-network:demo-project" = { # unique tofu resource name
-      name = "demo-network" # openstack network name
-      project = "demo-project"
-
-      subnets = {
-        "demo-subnet:demo-project" = { # unique tofu resource name
-          name = "demo-subnet" # openstack subnet name
-          cidr = "10.0.0.0/24"
-        }
-      }
-    }
-  }
-
-  routers = {
-    "demo-router:demo-project"  = { # unique tofu resource name
-      name = "demo-router" # openstack router name
-      project = "demo-project"
-      external_network = "demo-network:demo-project" # unique tofu resource name of network
-      external_fixed_ips = [{
-        subnet = "demo-subnet:demo-project" # unique tofu resource name of subnet
-      }]
-      interfaces = [
-        { subnet = "demo-subnet:demo-project" } # unique tofu resource name of subnet
-      ]
-    }
-  }
-
-}
-```
 
 ## Current Issues
 
@@ -267,3 +211,7 @@ committed, it does not matter.
 - Changes to the `src/` files are picked up when running `tofu-os-cfg`.
 - Note that the `--output` argument can be used to determine where files are
   generated.
+
+## VAST Support
+
+See [docs/vast.md](docs/vast.md).

docs/flavors.md

@@ -0,0 +1,36 @@
+## Flavors
+
+To create a flavor,
+
+Example usage:
+
+```console
+flavors = {
+        "test-flavour" = {
+            ram          = 4096
+            vcpus        = 1
+            disk         = 50
+            ephemeral    = 0
+            swap         = 0
+            rx_tx_factor = 1.0
+            is_public    = true
+            extra_specs = {
+            }
+            projects = [
+                "client", "client-other-project"
+            ]
+        }
+}
+```
+
+Argument reference:
+- `ram` (Required) number. Value in megabytes. Changing this creates a new flavor.
+- `vcpus` (Required) number. Changing this creates a new flavor.
+- `disk` (Required) number. Value in GiB. Changing this creates a new flavor.
+- `ephemral` (Optional) number. Changing this creates a new flavor.
+- `swap` (Optional) number. The amount of disk space in megabytes to use. Changing this creates a new flavor.
+- `rx_tx_factor` (Optional) number. Changing this creates a new flavor.
+- `is_public` (Optional) bool, default true. If "projects" is non-empty this is ignored and set false. Changing this creates a new flavor.
+- `flavor_id` (Optional) string. Changing this creates a new flavor access
+- `extra_specs` (Optional) map of strings
+- `projects` (Optional) list of strings. Project names to have access to the flavor. Changing this creates a new flavor access.

docs/guide.md

@@ -0,0 +1,28 @@
+## Tofu OpenStack Config User Guide
+
+Tofu OpenStack Config allows you to manage your Openstack config using Terraform.
+This guide will provide you with example templates for available resources. A full
+list of variables available for each resource can be found in [variables.tf](https://github.com/stackhpc/tofu-openstack-config/blob/main/variables.tf),
+with a description and type.
+
+It is recommended for easy readibility to separate your resources in `main.tf`
+as follows:
+
+```console
+module "openstack" {
+    source =
+
+    projects = local.project-config
+    networks = local.network-config
+    ...
+}
+```
+
+The config for each resource can then be written into separate files, suggested
+format is `<resource>-config.tf`, for example:
+
+- project-config.tf
+- network-config.tf
+- router-config.tf
+
+For information on how local values work, see this [opentofu.org website](https://opentofu.org/docs/language/values/locals/).

docs/identity.md

@@ -0,0 +1,76 @@
+## Users
+
+To create a new user,
+
+Example usage:
+
+```console
+users = {
+    "<username>" = {
+        name            = "bob"
+        default_project = "client"
+        email           = "bob@client.com"
+        description     = "Bob from client"
+        groups = [
+            "admin:client",
+            "member:client-other-project"
+        ]
+    }
+}
+```
+
+Argument reference:
+- `description` (Optional) string
+- `email` (Optional) string
+- `groups` (Optional) string
+- `password` (Optional) string
+- `default_project` (Optional) string. Project name.
+
+For users to have access to projects - groups and role assignments need to be created then
+users are assigned the corresponding groups that match their `role:project` needs.
+
+## Groups
+
+To create a group, add config to `group-config.tf`.
+
+Template:
+
+```console
+group-config = {
+    "admin:client" = "Admins of client project"
+    "member:client" = "Members of client project"
+    ...
+}
+```
+
+Argument reference:
+- `description` (Optional) string
+
+## Role assignment
+
+To create a role,
+
+Available roles can be seen by running `openstack role list`
+
+Example usage:
+
+```console
+    role_assignments = [
+        {
+            role    = "admin"
+            group   = "admin:client"
+            project = "client"
+        },
+        {
+            role    = "member"
+            group   = "member:client-other-project"
+            project = "client-other-project"
+        },
+        ...
+    ]
+```
+
+Argument reference:
+- `role` (Required) string. Role name, available roles found by running `openstack role list`.
+- `group` (Required) string. Group name.
+- `project` (Required) string. Project name.

docs/images.md

@@ -0,0 +1,29 @@
+## Images
+
+To create an image,
+
+Example usage:
+
+```console
+images = {
+    "Ubuntu-24.04-20260323-noble-server-cloudimg-amd64" = {
+      image_source_url = "https://cloud-images.ubuntu.com/noble/20260323/noble-server-cloudimg-amd64.img"
+      container_format = "bare"
+      disk_format      = "qcow2"
+    }
+}
+```
+
+Argument reference:
+- `container_format` (Required) string. Must be one of "bare", "ovf", "aki", "ari", "ami", "ova", "docker", "compressed".
+- `disk_format` (Required) string. Must be one of "raw", "vhd", "vhdx", "vmdk", "vdi", "iso", "ploop", "qcow2", "aki", "ari", "ami".
+- `image_cache_path` (Optional) string.
+- `image_source_url` (Optional) string.
+- `image_id` (Optional) string.
+- `min_disk_gb` (Optional) number, default 0.
+- `min_ram_mb` (Optional) number, default 0.
+- `protected` (Optional) bool, default false.
+- `hidden` (Optional) bool, default false.
+- `web_download` (Optional) bool, default false.
+- `properties` (Optional) list of strings.
+- `visibility` (Optional) string.

docs/networking.md

@@ -0,0 +1,139 @@
+## Networking config
+
+Note that:
+
+- Networks (and their subnets) and routers do not necessarily have to be associated with a project. If they are this association can be made with the project's name (if the project is controllled by this config) or by a project/tenant id from OpenStack (if it is not).
+- The names in OpenStack for networks, subnets and routers are not necessarily unique across projects. Therefore these resources have a tofu resource name which must be unique across projects, which can be used to refer to them for other resources. It is suggested that a convention of using $NAME:$PROJECT_NAME is used.
+
+
+## Networks
+
+To create a network,
+
+Example usage:
+
+```console
+network = {
+    "client_net_data:client" = {
+      name = "client-net-data"
+      project = "client"
+      admin_state_up = true
+      external = false
+      mtu = 9000
+      port_security_enabled = false
+
+      segments = [{
+        network_type = "vlan"
+        physical_network = "physnet1"
+      }]
+
+      subnets = {
+        "client_subnet_data:client" = {
+            name = "client-subnet-data"
+            ip_version = 4
+            no_gateway = true
+
+            #project-nets
+            subnetpool_id = "..."
+            prefix_length = 24
+        }
+      }
+    }
+}
+```
+
+Argument reference:
+- `name` (Required) string.
+- `region` (Optional) string. Changing this creates a new network.
+- `shared` (Optional) bool, default false.
+- `external` (Optional) bool, default false.
+- `admin_state_up` (Optional) bool, default false.
+- `project` (Optional) string. Project name, overrides `tenant_id`. Changing this creates a new network.
+- `tenant_id` (Optional) string. Openstack project id, overriden by `project`. Changing this creates a new network.
+- `mtu` (Optional) number.
+- `port_sercuirty_enabled` (Optional) bool, default false.
+- `tags` (Optional) list.
+- `segments` (Optional) list of objects, block supports:
+    - `physical_network` (Optional) string.
+    - `network_type` (Optonal) string.
+    - `segmentation_id` (Optional) string.
+- `subnets` (Optional) list of maps, block supports:
+    - `key` (Required) string.
+    - `name` (Required) string.
+    - `region` (Optional) string. Changing this creates a new subnet.
+    - `cidr` (Optional) string. Can omit option if creating subnet from a subnet pool (using `subnetpool_id` ).
+    - `ip_version` (Optional) number, default 4. Changing this creates a new subnet.
+    - `gateway_ip` (Optional) string.
+    - `enable_dhcp` (Optional) bool, default true.
+    - `dns_nameserver` (Optional) list.
+    - `dns_publish_fixed_ips` (Optional) bool, default false.
+    - `service_type` (Optional) list
+    - `subnetpool_id` (Optional) string
+    - `prefix_length` (Optional) number
+    - `no_gateway` (Optional) bool
+    - `tags` (Optional) list
+    - `allocation_pool` (Optional) list, block supports:
+        - `start` (Required) string.
+        - `end` (Required) string.
+
+
+## Routers
+
+To create a router,
+
+Example usage:
+
+```console
+routers = {
+    "internal:admin" = {
+        name                = "internal"
+        external_network    = "internal-net:admin" # tofu resource name of network
+        project             = "admin"
+
+        external_fixed_ips  = [
+            { subnet = "internal-net:admin" }
+        ]
+
+        interfaces = [
+            { subnet = "internal-net:admin" }
+        ]
+    }
+}
+```
+
+Arguments referenece:
+- `name` (Required) string. Openstack router name.
+- `region` (Optional) string. Changing this creates a new router.
+- `external_network` (Optional) string. Tofu resource name of network.
+- `external_network_id` (Optional) string. Openstack network id.
+- `admin_state_up` (Optional) bool.
+- `project` (Optional) string. Project name, overrides `tenant_id`. Changing this creates a new router.
+- `tenant_id` (Optional) string. Openstack project id, overriden by `project`. Changing this creates a new router.
+- `tags` (Optional) list.
+- `external_fixed_ip` (Optional) list of maps, block supports:
+    - `subnet` (Optional) string. Tofu resource name of subnet.
+    - `subnet_id` (Optional) string. Openstack subnet id.
+    - `ip_address` (Optional) string.
+- `interfaces` (Optional) list of maps, block supports:
+    - `region` (Optional) string. Changing this creates a new router interface.
+    - `subnet` (Optional) string. Tofu resource name of subnet, overrides `subnet_id`. Changing this creates a new router interface.
+    - `subnet_id` (Optional) string. Openstack subnet id, overriden by `subnet`. Changing this creates a new router interface.
+    - `port_id` (Optional) string. Openstack port id. Changing this creates a new router interface.
+    - `force_destroy` (Optional) bool, default false.
+
+## Network RBAC
+To create a network RBAC (role based access control),
+
+Example usage:
+
+```console
+network_rbac = {
+
+}
+```
+
+Argument reference:
+- `network` (Required) string. Changing this creates a new routing entry.
+- `projects` (Required) list of strings. Project names.
+- `access` (Required) string. Valid values are either `access_as_external` or `access_as_shared`.
+