Skip to main content
A managed Kubernetes cluster turns the GPU nodes you already reserved into a Kubernetes cluster you reach with a namespace-scoped kubeconfig. Ornn runs the control plane; you get full control inside your own namespace. You launch the cluster from the console, download a kubeconfig, and connect with kubectl.

​
When to use Kubernetes

  • You run containerized training or inference and want orchestration, not a single host.
  • You want to schedule multiple GPU jobs across your reserved nodes.
  • You already have Kubernetes manifests, Helm charts, or operators to deploy.
For a single machine you SSH into, VM access or Bare Metal access is simpler. Choose Kubernetes when you want a cluster.

​
Prerequisites

  • The bid is promoted to a confirmed reservation that is visible in your portfolio.
  • Checkout and payment for the reservation are complete.
  • You have kubectl installed locally.

​
Launch the cluster

1

Open Clusters

From the console, go to Clusters (/clusters) and start a new cluster, or open your reservation in Portfolio and choose the Kubernetes access mode.
2

Choose Kubernetes and a network mode

Pick Kubernetes, then a network mode:
  • Public — the API is reachable over the internet.
  • Private — the API is reachable only over your reservation’s WireGuard VPN (nothing is exposed publicly).
3

Launch

Launch the cluster. The first launch after an enrollment takes a few extra minutes while the GPU images download. The manage page shows live progress and, once the cluster is active, a Download kubeconfig action plus a Need help connecting? link to this guide.

​
Connect with kubeconfig

1

Download the kubeconfig

On the cluster panel, click Download kubeconfig. It contains a short-lived, namespace-scoped token and the API endpoint.
2

Point kubectl at it

export KUBECONFIG="$HOME/Downloads/ornn-<reservation-id>-kubeconfig.yaml"
3

Confirm the connection

Your access is scoped to your namespace, so namespace commands work:
kubectl get ns tenant-<id>
kubectl get pods
Cluster-wide commands like kubectl get nodes and kubectl cluster-info return Forbidden. That is the security boundary working as intended — your token is scoped to your namespace — not a connection failure.

​
Run a GPU smoke test

Your GPU node is dedicated to your reservation, so every pod must select it (nodeSelector), tolerate its reservation taint, and request nvidia.com/gpu. This pod runs nvidia-smi and cleans up after itself: 
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: ornn-smoke
  namespace: tenant-<id>
spec:
  restartPolicy: Never
  nodeSelector:
    ornn.ai/reservation: "<reservation-id>"
  tolerations:
    - key: ornn.ai/reservation
      operator: Equal
      value: "<reservation-id>"
      effect: NoSchedule
  containers:
    - name: smoke
      image: nvidia/cuda:12.4.1-base-ubuntu22.04
      command: ["nvidia-smi"]
      resources:
        limits:
          nvidia.com/gpu: 1
EOF

kubectl wait --for=jsonpath='{.status.phase}'=Succeeded pod/ornn-smoke --timeout=300s || true
kubectl logs ornn-smoke || true
kubectl delete pod ornn-smoke --ignore-not-found
You should see your allocated GPU in the nvidia-smi table. Apply the same nodeSelector, tolerations, and nvidia.com/gpu request to your real workloads.

​
Private clusters: bring up WireGuard first

Private clusters expose nothing publicly — the API is reachable only over your reservation’s WireGuard tunnel. Set it up once: 
# 1. Generate a WireGuard keypair locally.
wg genkey | tee privatekey | wg pubkey

# 2. Paste the printed PUBLIC key into the cluster panel's Connect section and
#    generate a config.
# 3. Save the returned config (fill in your private key) and bring the tunnel up.
sudo wg-quick up ./ornn-wg.conf
Once the tunnel is up, the downloaded kubeconfig reaches the API and the steps above are unchanged.

​
Tear down

Tearing down drains all workers, revokes the kubeconfig, and returns the GPU nodes to your reservation. A torn-down or failed cluster relaunches in place.
Teardown interrupts running workloads and can’t be undone. Persist checkpoints and data to your own object storage first.

​
Troubleshooting

Expected. Your token is namespace-scoped, so cluster-wide reads (get nodes, cluster-info, other namespaces) are denied by design. Use namespace-scoped commands like kubectl get pods.
The kubeconfig token is short-lived. Download a fresh kubeconfig from the cluster panel and re-export KUBECONFIG.
The node is dedicated to your reservation. Confirm the pod has the nodeSelector, the matching ornn.ai/reservation toleration, and a nvidia.com/gpu request, as shown in the smoke test.
Make sure the WireGuard tunnel is up (sudo wg show) before using the kubeconfig. Re-generate the peer config from the Connect section if your public key changed.

​
What’s next

access

Slurm access

Prefer batch scheduling? Run a managed Slurm cluster on your reserved GPUs instead.
access

Access overview

Compare the ways to access your reserved Ornn compute.