Provision and connect to managed Kubernetes

Launch Kubernetes on your reserved GPU nodes through the console or the REST API, then run GPU workloads with kubectl or a Kubernetes client library. The Ornn CLI is optional. There are two separate APIs:

Ornn REST API (https://api.ornn.com): authenticate with an Ornn API key to create clusters, read their status, retrieve access, add or remove workers, and tear clusters down.
Your cluster’s Kubernetes HTTPS API: authenticate with the issued kubeconfig to manage Pods, Jobs, Deployments, Services, namespaces, and quotas. Use the server address and namespace in that file, not api.ornn.com. An Ornn API key is not a Kubernetes bearer token.

To automate the whole lifecycle with an API key, follow Automate managed Kubernetes with the Ornn API. Use the REST API reference for endpoint schemas, or download OpenAPI for Swagger, Postman, or a client generator. Ornn’s provisioning API is REST over HTTPS; there is no gRPC or GraphQL provisioning API. These steps provision an Ornn-managed cluster. They do not attach Ornn workers to an existing EKS, GKE, or AKS cluster. Contact Ornn about external-cluster requirements before designing that integration. Ornn creates a control plane for your cluster and joins the GPU nodes you select as workers. Your reservation remains visible in Nodes; manage the cluster from Orchestration (/controllers). Buying capacity does not launch a cluster. The cluster table shows cluster name, status, node count, GPU model, network, and last update. On the cluster manage page, the node list fits each page to the available window space, with previous and next controls and a result count. Search and filters apply to the whole cluster and return you to the first page. This also applies to Slurm clusters. Old /compute/kubernetes bookmarks now open Orchestration (/controllers), where you create and manage clusters.

Before you start

Sign in to an approved organization that owns the reservation.
The reservation must be active and have available, eligible nodes.
For API integration, create an API key and use an HTTPS client. For the terminal workflow, install kubectl and use a version compatible with your cluster.
Your organization can run one Kubernetes cluster at a time, and cannot run a Kubernetes cluster and a Slurm cluster at the same time. Tear down the other cluster and wait for it to finish first.
Decide whether you need a Public or Private connection. Private access requires WireGuard on your computer. Choose Private if you need a shared filesystem at /workspace.
Save any data on selected nodes before launch. If Ornn asks to clean an existing environment, that cleanup can destroy local data.

Kubernetes does not require an SSH key for API access. Nodes already allocated to another cluster are unavailable. A multi-node selection does not guarantee a high-speed interconnect; confirm your workload’s networking requirements before reserving capacity.

Spot VMs cannot join a cluster.
Running VMs on your reservation can join as workers, alone or alongside nodes. While a VM is in a cluster, its SSH keys are set aside and its open SSH sessions end; its disk and data stay. The keys come back when the VM leaves the cluster, including any key changes you made in the meantime.
In a Public cluster, every worker needs its own network address. A VM whose address another worker already uses cannot join; choose a different VM or use Private networking.

Provision and manage through REST

Every lifecycle step in the console has an API equivalent. With an Ornn API key, your automation can:

List the hosts on a reservation and choose eligible ones.
Create a cluster on those hosts.
Poll the cluster list until its state is active.
Fetch the kubeconfig.
Run GPU workloads through the cluster’s own Kubernetes API.
Add or remove workers.
Tear down the cluster and confirm it is gone.

Automate managed Kubernetes with the Ornn API walks through each step with CLI, curl, and Python examples, including polling, safe retries, and teardown confirmation. Keep these rules in mind:

Creating a cluster for a reservation that already has one returns the existing cluster; it does not add hosts. Use the worker endpoints to change membership.
Ornn does not add or remove workers automatically. Pending Pods do not add capacity; scaling is an API call your automation makes against hosts you already reserved.
The kubeconfig token is valid for seven days. Reading access again returns the same token. Contact support for new credentials; do not tear down a working cluster to renew access.
There is no GET for one cluster. Read the cluster list and select by controller.id.

Launch through the console or Ornn CLI

Open Orchestration

Open Orchestration and start a new cluster. Select Kubernetes.

Select your nodes

Open Choose available nodes to cluster, select your reservation group, and select the nodes to use. Only eligible nodes appear. The node count is a worker count, not a GPU count.Select VMs in the same dropdown alongside nodes. Only running VMs that are not in another cluster appear.If the picker is empty, check that the term has started and the nodes are available. Launch On-Demand, when shown, opens a separate VM purchase flow; it does not create a Kubernetes cluster.

Choose networking and launch

Public makes the cluster API reachable over the internet; authentication is still required. Private requires a connection to the selected organization’s private network. Set up its WireGuard config in the launch dialog or the cluster’s Network tab.Review the selected nodes and any cleanup confirmation, then click Create cluster. The manage page shows progress while Ornn creates the control plane, prepares the hosts, joins the workers, and issues access. Image downloads and host preparation can take several minutes. Wait for Download kubeconfig to become available.

From an interactive terminal, you can also launch with the CLI:

ornn login
ornn context
ornn launch <reservation-id> --mode kubernetes --network public --nodes <count> --wait
ornn clusters list
ornn connect <cluster-id> --output ./ornn-kubeconfig.yaml

Replace angle-bracket placeholders with your values. Interactive launch asks you to review the exact nodes. Add running VMs with --vms <vm-id>,<vm-id>; use --nodes 0 for a cluster of VMs only. For automation, use the complete inputs and consent described in ornn help launch and the CLI interaction guide.

Connect and verify access

Download your kubeconfig

On the cluster manage page, select the Download kubeconfig icon beside the Actions menu. This file contains the API address, default namespace, and a token with cluster-admin access to your cluster. The token is valid for seven days. Keep it private.

Select the downloaded file

In a macOS or Linux terminal, replace the path with the actual downloaded filename:

export KUBECONFIG="$HOME/Downloads/ornn-<reservation-id>-kubeconfig.yaml"
chmod 600 "$KUBECONFIG"
kubectl config current-context
kubectl config view --minify -o jsonpath='{.contexts[0].context.namespace}{"\n"}'

The commands below use that default namespace. Do not paste a placeholder such as tenant-<id> into a manifest. If your manifest specifies a namespace, use the Namespace shown on the cluster page.

Check the cluster

Bring up WireGuard first if the cluster is Private, then run:

kubectl get nodes
kubectl get pods
kubectl get resourcequota

Check that your selected workers are Ready. The node list also includes managed control-plane nodes; they are not GPU capacity for your workloads.

Run your first GPU job

This NVIDIA example requests one GPU, runs nvidia-smi, and exits. Use it on NVIDIA capacity with a compatible driver. It does not install a training framework.

kubectl apply -f - <<'EOF'
apiVersion: batch/v1
kind: Job
metadata:
  name: ornn-gpu-smoke
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      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=condition=complete job/ornn-gpu-smoke --timeout=300s
kubectl logs job/ornn-gpu-smoke

Success means the Job completes and its logs list an NVIDIA GPU. If the wait fails, inspect the job before deleting it:

kubectl describe job ornn-gpu-smoke
kubectl get pods -l job-name=ornn-gpu-smoke
kubectl describe pods -l job-name=ornn-gpu-smoke

After checking the result, remove only this test:

kubectl delete job ornn-gpu-smoke

For AMD Instinct capacity, use an image with ROCm and amd-smi installed, request amd.com/gpu: 1, and run ["amd-smi", "list"] instead. Use a distinct job name. See the Kubernetes GPU scheduling guide for resource-request rules.

Run your application

Use an image that includes your framework and dependencies. Match its CUDA or ROCm requirements to the reserved hardware. Private images need your own registry credentials in an imagePullSecret in the workload namespace. In the supplied namespace, Ornn adds the scheduling rules that place pods on the workers from the reservation the cluster launched on. You do not need to add a reservation node selector or toleration. Those defaults apply to that namespace; a namespace you create yourself does not automatically receive them. Avoid changing managed scheduling policies or placing workloads on control-plane nodes. Request CPU and memory as well as GPUs. A single container’s GPU request must fit on one worker; requesting eight GPUs does not combine four GPUs on each of two workers. Distributed training needs separate worker pods and an application configured for distributed execution.

MPI and distributed training

The cluster includes the MPI Operator. Check that its resource is available:

kubectl api-resources --api-group=kubeflow.org
kubectl auth can-i create mpijobs.kubeflow.org

Use compatible launcher and worker images, request GPUs on workers, and configure the MPI runtime’s network interface. RDMA performance depends on the reserved hosts and interconnect; first confirm a small multi-node job works before scaling training.

Autoscaling and queueing

A Horizontal Pod Autoscaler can scale a Deployment, ReplicaSet, or StatefulSet using CPU or memory. Set the corresponding container resources.requests. GPU utilization needs a separately configured metrics adapter. Autoscaling changes pod replicas, not your purchased node count. Ornn does not add workers when pods are pending; there is no Cluster Autoscaler or Karpenter integration. To change capacity, add or remove workers yourself or from your own automation through the API. Pending and running pods count toward the namespace GPU request quota, ornn-gpu-quota. A quota rejection prevents pod creation; an admitted pod can remain Pending while all matching GPUs are busy. Inspect workload events and kubectl describe resourcequota ornn-gpu-quota before increasing replicas. Adding workers and changing a namespace quota are separate operations.

Choose storage before running a long job

Storage	Use it for	What survives
Container filesystem or `emptyDir`	Temporary files	Not durable across pod replacement or teardown
`local-path` PVC	Data used by a workload on one worker	Pod replacement on that worker; no node-loss recovery
Shared filesystem at `/workspace`	Shared datasets, checkpoints, and files across workers	Separate filesystem resource, retained after cluster teardown
Your external object storage	Exports and backups	Independent of the cluster

Local persistent volumes

The default local-path class supports ReadWriteOnce and binds when the first consumer pod is scheduled. A Pending PVC without a consumer is expected. Mount the PVC in your workload; do not rely on an arbitrary host path. Local data stays on the selected worker. It does not follow a workload to another worker after disk or node loss. Requested capacity is not an enforced filesystem limit, and resizing is unsupported. The class uses a Delete reclaim policy: deleting the PVC can delete its backing data. Export important data before deleting a claim, removing a worker, or tearing down the cluster.

Shared filesystem at `/workspace`

A shared filesystem requires a Private cluster. Contact Ornn to confirm capacity, performance, region, cost, and reservation networking. The console’s shared-filesystem view directs you to Ornn for provisioning. If using the CLI, this command requests both provisioning and attachment for the reservation. It does not require a second console attachment step:

export RESERVATION_ID='<reservation-id>'
ornn filesystems deploy "$RESERVATION_ID" --performance-tier standard --capacity-gib 1024
ornn filesystems show "$RESERVATION_ID"

standard, performance, and enterprise are the supported tier keys. Capacity rules and region availability vary; confirm the storage cost with Ornn before provisioning. Wait for provisioning and attachment to finish. Once active, the supplied namespace injects /workspace into workload pods. Verify both the claim and access from your application:

export POD_NAME='<pod-name>'
kubectl get pvc ornn-workspace
kubectl exec "$POD_NAME" -- sh -c 'test -d /workspace && ls -ld /workspace'

A Bound claim alone does not prove every worker can reach the filesystem. Test a disposable file from pods on different workers before using it for distributed checkpoints. Changing a workspace attachment can restart workloads; checkpoint first. Cluster teardown does not delete the separately provisioned filesystem. Detaching removes access; deleting the filesystem is a separate destructive action. Do not use ornn filesystems delete as a data-preserving detach command. Export data first and confirm deletion and the end of storage charges with Ornn. Keep backups outside the cluster.

Private access with WireGuard

Install WireGuard on your computer. Generate a key pair locally:

umask 077
wg genkey | tee ./ornn-wg-private.key | wg pubkey > ./ornn-wg-public.key
cat ./ornn-wg-public.key

Paste only the public key into Create config in the cluster’s Network tab. Download the returned .conf, replace its private-key placeholder locally with the contents of ornn-wg-private.key, and protect the file. Keep MTU = 1200 and PersistentKeepalive = 25 from the generated config. The cluster’s Network tab uses the private network selected at launch. You do not need to create another network to add a device. Confirm that the tab shows your cluster’s network before creating a config. Shared (default) means the cluster has no dedicated network selected. A dedicated network that is not active keeps its name and shows its status; Dedicated network (unavailable) means its details could not be loaded. Wait for a pending or provisioning network to become active. Contact support if the network is degraded or unavailable, or if Shared (default) appears when you expected a dedicated network. On Linux with wg-quick installed:

chmod 600 ./ornn-wg.conf
sudo wg-quick up ./ornn-wg.conf
sudo wg show

On macOS or Windows, import the completed config into the WireGuard app and activate it. Keep private keys on your own computer. Each device needs its own key pair and peer. To rotate a key, remove that device’s old peer, create a replacement, and import its new config. Removing a peer disconnects that device.

Add or remove workers

On the cluster manage page, use Add nodes to select eligible nodes owned by your organization or running VMs from the Target nodes dropdown. Ornn prepares each node before it joins, which wipes its tenant home directory and removes any VM on it; a VM joins as it is. Wait for the new workers to become Ready, then check their GPU capacity before increasing your workload. Adding a worker does not raise the supplied namespace’s GPU quota, which Ornn sizes from the cluster’s workers when it first becomes active. Pods in that namespace also stay pinned to the reservation the cluster launched on, so prefer nodes from that reservation. After new workers are Ready, run kubectl describe resourcequota ornn-gpu-quota, and contact support if the quota does not cover the GPUs you plan to request. To remove workers, select them in Nodes and use Remove. Removal drains those workers and interrupts workloads using them. Export local data and checkpoint first. Review remaining GPU capacity and pending workloads afterward. Removing a worker does not cancel its reservation. A removed VM keeps running and gets its SSH keys back. To add and remove workers from your own automation, see Scale workers up or down.

Stop, tear down, or retry

In the cluster list, hover over a row or focus it with the keyboard to reveal Delete cluster. On mobile, the delete button is always visible. Select it and confirm to tear down the cluster. Reservation billing continues. Use Stop launch while provisioning, or Tear down cluster for an active cluster, from the manage page’s actions menu. Confirm the affected nodes and wait for cleanup to finish. Teardown removes workloads, revokes cluster access, and releases workers back to their reservations. A failed or torn-down cluster can disappear from Orchestration after cleanup. Start a new launch from your available reserved nodes. Do not rely on the old URL or downloaded credentials.

Save checkpoints and export local data before teardown. Deleting a test Job is different from tearing down its cluster. Teardown does not cancel the reserved term or delete separate storage resources.

Troubleshooting

No nodes available to select

Confirm the correct organization, an active reservation, and available hosts. Offline nodes and nodes held by another cluster cannot be selected. If capacity is missing, contact support with the reservation ID.

A VM did not join

If the VM left the cluster with a message that another machine already uses its network address, choose a different VM or relaunch with Private networking. If its host needs a management update, contact support with the VM ID.

API connection times out

Confirm KUBECONFIG points to this cluster’s file. For Private access, activate the matching WireGuard tunnel first. Check your local firewall and VPN routes. A small ping succeeding does not prove the API works; keep the generated MTU of 1200.

Unauthorized or Forbidden

For Unauthorized, confirm you selected this cluster’s downloaded file. Its token expires seven days after it is issued, and downloading the stored file again does not renew it. Contact support if the correct file has expired; do not tear down a working cluster just to renew access. For Forbidden, check the context and identity. After a relaunch, use the new cluster credentials. Do not print or share tokens.

Pod stays Pending or a Job cannot create pods

Run kubectl describe pod <pod-name>, kubectl describe job <job-name>, and kubectl describe resourcequota. Check GPU vendor, per-worker capacity, quota, CPU and memory, and volume placement. Use the supplied namespace so its scheduling defaults apply.

ImagePullBackOff or ErrImagePull

Read pod events. Check the image name and tag, registry access, and your imagePullSecrets. A registry can reject a pull because of authentication, permissions, rate limits, or an unavailable image; the error alone does not establish which cause applies.

PVC stays Pending or data is missing

For local-path, create the consumer pod and inspect its scheduling events. Local volumes cannot move between workers. For /workspace, check that the cluster is Private, the filesystem is ready, and the attachment is active before testing from a pod.

Launch stalls or fails

Open the progress details and record the failed stage and customer error. Avoid repeated launches while cleanup is in progress. Contact support with the reservation or cluster ID, approximate failure time, and sanitized error text.

Monitor and get help

Use the cluster’s Observability tab for host metrics and kernel console logs. Use kubectl logs, describe, and events for application failures. Host metrics do not prove a training job completed. Open Support in the console or email support@ornn.com. Include the cluster and reservation IDs, workload name, failed stage, and time. Never include kubeconfig contents, private keys, registry secrets, or tokens.

What’s next

Kubernetes API automation

Provision, scale, and tear down clusters from your own automation with an API key.

Slurm access

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

Access overview

Compare the ways to access your reserved Ornn compute.

Get Started

Buy and sell

Supplier

Accessing Compute

Storage

Nodes

Account

Provision and connect to managed Kubernetes

Before you start

Provision and manage through REST

Launch through the console or Ornn CLI

Connect and verify access

Run your first GPU job

Run your application

MPI and distributed training

Autoscaling and queueing

Choose storage before running a long job

Local persistent volumes

Shared filesystem at `/workspace`

Private access with WireGuard

Add or remove workers

Stop, tear down, or retry

Troubleshooting

Monitor and get help

What’s next

Kubernetes API automation

Slurm access

Access overview

​Before you start

​Provision and manage through REST

​Launch through the console or Ornn CLI

​Connect and verify access

​Run your first GPU job

​Run your application

​MPI and distributed training

​Autoscaling and queueing

​Choose storage before running a long job

​Local persistent volumes

​Shared filesystem at /workspace

​Private access with WireGuard

​Add or remove workers

​Stop, tear down, or retry

​Troubleshooting

​Monitor and get help

​What’s next

Kubernetes API automation

Slurm access

Access overview

Before you start

Provision and manage through REST

Launch through the console or Ornn CLI

Connect and verify access

Run your first GPU job

Run your application

MPI and distributed training

Autoscaling and queueing

Choose storage before running a long job

Local persistent volumes

Shared filesystem at `/workspace`

Private access with WireGuard

Add or remove workers

Stop, tear down, or retry

Troubleshooting

Monitor and get help

What’s next