Deploying Heliast
This page says what you need before a deployment, what the nine deployment stages do and how model weights are staged and checked.
Status: the deployment pipeline, the Terraform modules and the Helm chart exist and are tested against fixtures and on a single development host. They have not yet run in a real customer estate. Treat the details below as the designed behaviour and confirm them with your Heliast contact before you plan an install.
What you provide
Heliast runs inside your environment. You provide the following.
| Item | Minimum |
|---|---|
| Host operating system | Ubuntu 22.04 LTS or RHEL 9 |
| Kubernetes | K3s or RKE2, version 1.28 or later |
| Container runtime | containerd 1.7 or later |
| Accelerator | A data-centre or workstation-class NVIDIA card. GeForce cards are refused. At least 16 GB of video memory, and the reference tiers set higher bars (see below) |
| Accelerator software | NVIDIA driver 550 or later with the container toolkit, and CUDA 12.4 or later |
| Identity provider | An OIDC or SAML provider the cluster can reach |
| Git repository | One you control, for your policy and configuration |
| Storage | A CSI driver with dynamic provisioning, and a storage class |
| Network | A network policy engine in the cluster network plugin (see network and ports) |
Notes on this table:
- The reference tiers are one 96 GB card for Tier 1 and 128 GB of unified memory for Tier 0. Sizing for your workload is agreed with Heliast before purchase. Heliast does not resell hardware.
- Only vLLM is supported as the inference engine.
- Kubernetes distributions other than K3s and RKE2 are to be confirmed with your Heliast contact.
- Identity: OIDC sign-in through oauth2-proxy is the designed path. Federation against a commercial identity provider has not yet been proven end to end. Nested groups, group overage behaviour, conditional access and multi-factor prompts are not yet verified.
- Heliast does not host model weights. Weights are pulled from a source you choose and checked on arrival.
The nine stages
The pipeline runs the stages in order. Each stage needs the earlier stages to have completed in the same run, and it refuses to start if a predecessor failed or left no completion marker. A stage that cannot finish does not quietly pass. You can run a subset of stages, for example stages 1 to 5.
| Stage | Name | What it does | If it fails |
|---|---|---|---|
| 1 | Preflight | Reads the host and changes nothing. Checks the NVIDIA driver (550 or later), CUDA (12.4 or later), that a Kubernetes node is present, that a storage class with dynamic provisioning exists, and that the network plugin reports network policy support | Aborts. Nothing has been changed |
| 2 | Environment acceptance | Checks that a GPU is visible, refuses GeForce cards, requires at least 16 GB of video memory, and runs the GPU node verification script. Writes a report that lists each check as proven or not proven | Aborts, with the report |
| 3 | Infrastructure | Applies the Terraform baseline: the cluster, the GPU node and the default-deny network policy | Roll back from Terraform state |
| 4 | Platform | Installs the Helm release in one atomic step and waits for it to become ready | Helm rolls the release back |
| 5 | Model staging | Verifies every model weight file by digest and format, and optionally by signature, then places the files (next section) | Aborts. A digest mismatch is a security event |
| 6 | Policy | Loads your policy bundle from your Git repository, runs its unit tests, records the commit as the policy revision, writes the bundle into the cluster and restarts the policy engine | Aborts. Heliast stays closed until a valid policy is loaded |
| 7 | Identity | Connects sign-in to your identity provider | Aborts |
| 8 | Smoke tests | Sends one request that must be allowed and one that must be denied through the live enforcement hook and router | Aborts and reports |
| 9 | Baseline | Records starting measurements | Warns only. It never fails the run |
What is not complete today:
- Stage 2 records several checks as not proven, because a tenant cannot observe them: sustained-load clock and memory behaviour, disk class, network class, noisy neighbours, hypervisor health, host firmware and provider GPU telemetry. They are listed in the report and do not abort the stage.
- Stage 7 currently issues test virtual keys without sign-in. The real connection to your identity provider is not yet part of the pipeline. Plan identity integration with your Heliast contact.
- Stage 9 writes a baseline record with the host, tier and time. It does not yet capture latency, throughput or GPU utilisation figures.
- Stage 6 and the cluster: the policy bundle is written to a configuration object that the policy engine mounts. This path has not run in a real cluster.
- A policy revision is the Git commit of your policy repository. The loaded policy must report that same commit, so a running policy cannot cite a revision other than the one that produced its rules.
How model weights are staged
Stage 5 reads a manifest of admitted models. For each model the manifest names the format, a SHA-256 digest and the files that make up the model. The checks run in this order.
- Digest. Every file in the model's set is hashed and compared with the digest pinned for that file. A model split across several shards is checked shard by shard, including the index file. A manifest that pins only the first shard is refused. A mismatch aborts the run.
- Format. The format must be safetensors, and each file is validated by its content. A pickle-format file renamed to look like safetensors is rejected.
- Signature, if you pin a key. If you supply a public key, each model needs a detached ed25519 signature over its digest. With a key pinned, a missing signature is a failure, not a warning. Without a key, no signature check runs.
- Atomic placement. Every model is verified in a staging directory first. Only when every model in the set has passed are the files moved to the destination. A partial or altered set is never made available to the inference engine.
On any failure the pull stops, exits with an error, writes nothing to the destination and records a security event: a JSON file with the reason and the expected and observed digests. Weights and secrets are never written into the event.
A digest mismatch is treated as a security event, not as a transient error. Do not retry it. Treat the source and the transfer path as suspect, and review the event with your security lead.
The pinned digests come from Heliast's admission checks on public models. The staging check is a second, byte-level proof that the file that reached your environment is the file that was admitted.
Limits
- Staging checks weights that you stage into your own environment. For a model served by a hosted provider, Heliast cannot check the weights, and the route is labelled as provenance by host attestation, not verified.
- A model you own and serve yourself is recorded as assessed or registered. It is never described as admitted.
- Performance has not been measured on reference hardware. The design target of 50 to 100 concurrent users with a 95th percentile latency under 2 seconds is a target, not a result.
- Heliast makes no statement that a deployment satisfies any framework. Evidence the deployment produces is declared by the system and should be checked against your own obligations.