# 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:

```hcl
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.