tfmodules/hpc/README.md

hpc module

Provisions an HPC cluster and generates the consumer access credentials. One submodule per cloud provider, selected by the provisioner from the cloud provider of the provisioning request:

• ovh: one head node (Slurm controller, munge authority, NFS server, consumer entry point) plus N compute nodes (Slurm execution daemon, OpenMPI, NFS client) on a dedicated private network (vRack). All nodes are private only: internet egress goes through a managed cloud gateway attached to the cluster subnet, and the head node is reached from outside through a floating ip routed by the same gateway. The cluster bootstraps entirely from per-role cloud-init at first boot (Slurm configless, per-deployment munge key, shared /home over NFS, fixed uids cluster-wide) with no manual step.

Contract

Variable	Description
deployment_id	Unique deployment identifier, used in resource names
cloud_account	Cloud account (environment) name, second segment of the Vault credentials path, filled by the provisioner from the cloudAccount header via the {CLOUD_ACCOUNT} placeholder
requester_unique_id	Requester unique id, third segment of the Vault credentials path, filled by the provisioner from the requesterUniqueId header via the {REQUESTER_UNIQUE_ID} placeholder
username	Consumer username on the head node, defaults to simpl_user, last segment of the Vault credentials path. The user exists on every node with the same uid (Slurm runs jobs under it) but can only log in on the head node
admin_username	Management username created on all nodes with SSH key access only, defaults to simpladmin
credentials_version	Opaque rotation marker for the consumer credential, defaults to 1. Changing the value regenerates the consumer password, applies it on the head node over SSH and republishes the fresh credential to Vault in the same apply, without touching any instance. Managed by the credential renewal workflow, not by the deployment script author
name_prefix	Prefix for resource names, defaults to simpl
region	OVH region for the instances and the private network, for example SBG5
project_id	Optional override of the OVH project; by default the provider resolves it from the OVH_CLOUD_PROJECT_SERVICE variable of the runner environment, which the provisioner derives from the OVH_PROJECT_ID key of the cloud account configuration
compute_node_count	Number of compute nodes, defaults to 2
head_flavor, compute_flavor	Instance flavors per role, default b3-8
compute_cpus	Schedulable CPUs per compute node declared to the Slurm controller, must not exceed the vCPUs of compute_flavor, defaults to 2
image	Cloud-init enabled image for every node, defaults to Ubuntu 24.04
cluster_cidr	Private cluster network CIDR, defaults to 192.168.100.0/24. The head node takes host 50, compute nodes host 60 onward; lower pool addresses stay free for the DHCP agent ports (an instance on a DHCP-port address is silently canceled by the cloud)
vlan_id	vRack VLAN id for the private network, must be unused in the project, defaults to 212
gateway_model	Size of the cloud gateway providing the cluster egress, defaults to s

Cloud credentials are never module inputs, they reach the provider from the runner environment.

Credentials, following the existing Vault contract: the module generates the consumer password and the management SSH keypair and writes them to Vault, secret/{provider}/{cloud_account}/{requester_unique_id}/{username} (keys username, password, host, port) and the .../admin sibling (keys username, ssh_private_key, ssh_public_key). The consumer password never travels through user data: it is applied on the head node over SSH, keyed on both the rotation marker and the head node instance id, so a recreated head node receives the credential again. Day 2 credential renewal follows the same Terraform rotation flow as the other catalog modules, changing the credentials_version input. No secret material is ever part of an output or of the user body. The Vault provider configuration is generated by the provisioner next to the deployment script, and it authenticates through the Vault Kubernetes auth method with the service account of the Terraform runner, against a Vault role configured at installation time.

Outputs, deliberately restricted to the entry point (the response payload returned to the backend carries strictly the head node access information, never the compute node details):

Output	Description
head_node_ip	Public (floating) IPv4 address of the head node, the single entry point of the cluster
head_node_hostname	Hostname of the head node
ssh_port	SSH port of the head node
vmIps	Entry point address list, kept for compatibility with the single VM notification flow
credentials_ref	Vault path of the consumer credentials entry

Usage

The provisioner rewrites the {HPC_SOURCE} placeholder to this module's location for the cloud provider of the request (each catalog module has a placeholder derived from its directory name), so a deployment script only declares:

module "hpc" {
  source              = "{HPC_SOURCE}"
  deployment_id       = "{UUID}"
  region              = "<region>"
  cloud_account       = "{CLOUD_ACCOUNT}"
  requester_unique_id = "{REQUESTER_UNIQUE_ID}"

  compute_node_count = 2
}

output "head_node_ip" {
  value = module.hpc.head_node_ip
}

output "vmIps" {
  value = module.hpc.vmIps
}

output "credentials_ref" {
  value = module.hpc.credentials_ref
}

The root file must re-export the module outputs it wants published to the deployment outputs.