HyperbolicLabs/rental-operator

HyperbolicLabs/rental-operator

Description: Official Kubernetes operator for Hyperbolic on-demand GPUs

Language: Go

License: Apache-2.0

Stars: 0

Forks: 0

Open issues: 13

Created: 2026-09-29T19:44:22Z

Pushed: 2026-10-28T06:17:25Z

Default branch: main

Fork: no

Archived: no

README:

rental-operator


Rent Hyperbolic on-demand GPUs from your own Kubernetes cluster, declaratively.

Drop your Hyperbolic API key into a Secret, kubectl apply a GPURental, and the operator provisions the GPUs against the Hyperbolic public API, keeps them reconciled, and surfaces the SSH/connection details on the resource's status. Delete the object and the rental is terminated and the GPUs released.

apiVersion: compute.hyperbolic.ai/v1alpha1
kind: GPURental
metadata:
name: train-run-42
spec:
providerConfigRef: { name: default }
gpuType: h100
gpuCount: 8

$ kubectl get gpurentals
NAME PHASE GPU COUNT REGION CENTS/HR RENTAL-ID RENTAL-NAME AGE
train-run-42 Running h100 8 us-central-1 2200 B-k3Qm7vXa2P conscious-bougainvillea-oryx 6m

It is built to never spend money you didn't ask for: a create is never retried blindly (so a timeout can't rent twice), and a rental is never deleted from the cluster while it may still be billing.

---

Project status

rental-operator is at v0.1, its first public release. The API is compute.hyperbolic.ai/v1alpha1, so fields may still change in a minor release, and the release notes call out each change with migration steps. [SUPPORT.md](SUPPORT.md) lists the supported releases and Kubernetes versions. [API versioning](docs/api-versioning.md) explains what each API version promises.

How it works

The operator is a controller in your cluster that calls the Hyperbolic public API with your API key, the same way you would. It keeps no state of its own: everything durable lives on the custom resources or at Hyperbolic.

flowchart LR
you(["You"])
subgraph cluster["Your Kubernetes cluster"]
direction TB
rental["GPURental
what to rent, for how long"]
config["ProviderConfig
and a Secret with your API key"]
operator["rental-operator"]
rental --> operator
config --> operator
end
api["Hyperbolic API"]
gpus["GPU machines"]
you -- "kubectl apply" --> rental
operator -- "create, poll, terminate
over HTTPS with your key" --> api
api -- "provisions" --> gpus
you -. "ssh, address from status" .-> gpus

Five custom resources, all in the hyperbolic category (kubectl get hyperbolic -A):

• `ProviderConfig` points at the labeled Secret holding your API key, validates it, and reports your account's balance, active rentals and hourly cost as Hyperbolic reports them.
• `ClusterProviderConfig` does the same for a key a platform team shares across namespaces. Its Secret stays in the operator's namespace.
• `GPURental` is one on-demand rental. The operator creates it, polls it to Running, publishes SSH details on status, and on delete terminates it and waits until Hyperbolic confirms it is gone.
• `GPUAvailability` is a filtered, always-fresh view of what your account can rent.
• `SSHKey` saves an SSH public key on your account, so GPURentals can authorize it by name, and deletes it again with the object.

[Architecture](docs/architecture.md) shows the GPURental lifecycle and how creates and deletes stay safe when the API times out, the operator restarts or a namespace is deleted.

Quickstart

You need Kubernetes 1.35 to 1.37, Helm 3, a Hyperbolic API key from the dashboard, and an SSH public key. See [Install](docs/install.md) for the namespaced install, upgrades and uninstalling.

helm install rental-operator \
oci://ghcr.io/hyperboliclabs/charts/rental-operator \
--namespace rental-operator-system --create-namespace

1. Store your API key (in whatever namespace your rentals will live in):

read -rs HYPERBOLIC_API_KEY # paste the key; it is not echoed or kept in shell history
kubectl create secret generic hyperbolic-key \
--from-literal=api-key="$HYPERBOLIC_API_KEY"
kubectl label secret hyperbolic-key compute.hyperbolic.ai/credentials=true
unset HYPERBOLIC_API_KEY

The operator only reads Secrets with that label, so it never holds the rest of your cluster's Secrets in memory.

If you manage Secrets declaratively, for example with External Secrets or Sealed Secrets, put the label in the Secret's metadata:

metadata:
name: hyperbolic-key
labels:
compute.hyperbolic.ai/credentials: "true"

2. Create a ProviderConfig:

apiVersion: compute.hyperbolic.ai/v1alpha1
kind: ProviderConfig
metadata:
name: default
spec:
credentials:
secretRef:
name: hyperbolic-key
key: api-key

Check it authenticated:

$ kubectl get providerconfig default
NAME ENDPOINT BALANCE CENTS/HR RENTALS READY AGE
default https://api.hyperbolic.ai 124035 0 0 True 5s

3. Save your SSH key on the account:

kubectl apply -f - [!IMPORTANT]
> Before you delete the cluster, delete your GPURentals first. `kind delete cluster`, or losing a cluster any other way, removes the operator too. Nothing is left to terminate the rentals, and they keep billing until you terminate them in the [dashboard](https://app.hyperbolic.ai).

## Documentation

| | |
|---|---|
| [Architecture](docs/architecture.md) | Components, the GPURental lifecycle, the create and delete guarantees, polling and API budget. |
| [Install, upgrade and uninstall](docs/install.md) | Cluster-wide and namespaced installs, verifying a release, CRD upgrades. |
| [Custom resources](docs/resources.md) | What each field does, and the conditions and reasons. |
| [Common operations](docs/operations.md) | Regions, ports, terminating, orphaning, rebooting. |
| [Observability](docs/observability.md) | Prometheus metrics and the alerts the chart ships. |
| [API reference](docs/reference/api.md) | Every field, generated from the Go types. |
| [API versioning](docs/api-versioning.md) | What `v1alpha1` promises and how the API will graduate. |
| [Development](docs/development.md) | Running the operator locally. |
| [Releases](RELEASE.md) | Versioning, what a release contains, how one is cut. |
| [Support](SUPPORT.md) | Getting help, supported releases and...