Modelplane Modelplane docs
Version
main v0.1 Latest

NebiusCluster Custom Resource

On this page

A NebiusCluster provisions a Nebius Managed Service for Kubernetes (mk8s) cluster with dedicated node groups for GPU inference and system workloads. It outputs a Secret containing the cluster kubeconfig. The kubeconfig carries only the cluster endpoint and CA certificate - Nebius clusters authenticate every client through Nebius IAM - so consumers pair it with the credentials Secret of the Nebius ClusterProviderConfig named default, the same identity that provisions the cluster. The cluster is created in the project that ClusterProviderConfig sets as its projectID; Nebius projects are bound to a region, so the project also determines where the cluster runs.

#Metadata

API version
infrastructure.modelplane.ai/v1alpha1
Kind
NebiusCluster
Scope
Namespaced
Short names
mk8s

#Example

Manifest
apiVersion: infrastructure.modelplane.ai/v1alpha1
kind: NebiusCluster
metadata:
  name: inference-eu-north
  namespace: platform
spec:
  kubernetesVersion: "1.34"
  nodePools:
    - name: system
      role: System
      platform: cpu-d3
      preset: 8vcpu-32gb
      nodeCount: 2
    - name: gpu-h100
      role: GPU
      platform: gpu-h100-sxm
      preset: 8gpu-128vcpu-1600gb
      diskSizeGb: 200
      nodeCount: 0
      maxNodeCount: 8
      # Joins an existing physical InfiniBand fabric in the project's region;
      # use the fabric your GPU capacity is allocated on.
      fabric:
        type: InfiniBand
        infiniband:
          fabric: fabric-2
      gpu:
        acceleratorType: nvidia-h100
        driversPreset: cuda13.0

#Spec

NebiusClusterSpec defines the desired state of NebiusCluster.

# kubernetesVersion optional string 1–16 chars default: 1.34

mk8s cluster Kubernetes version. Must be a version mk8s currently supports. Defaults to a version where Dynamic Resource Allocation (how GPUs bind to pods) is generally available.

# nodePools required object[] 1–8 items
# diskSizeGb optional integer 10–65536 default: 100

Boot disk size in GB.

# fabric optional object

High-performance node-to-node fabric for multi-node engines, so a gang’s tensor-parallel traffic isn’t capped by TCP. Omit for standard VPC networking.

# infiniband optional object

InfiniBand fabric configuration. Required when type is InfiniBand.

# fabric required string 1–63 chars

Identifier of the physical InfiniBand fabric to join (e.g. fabric-2). This selects existing Nebius infrastructure, not a name for a new resource: fabrics are per-region - see https://docs.nebius.com/compute/clusters/gpu#fabrics - and multi-node GPU capacity is allocated on specific fabrics, so use the fabric your capacity lives on.

# type optional enum: None | InfiniBand default: None

Fabric technology. None uses standard VPC networking (TCP). InfiniBand places the group’s nodes in a GPU cluster on a physical InfiniBand fabric for GPUDirect RDMA across nodes; only useful on InfiniBand-capable platforms (e.g. gpu-h100-sxm). When set, Modelplane composes a GPU cluster on that fabric and places the group’s nodes in it.

# gpu optional object

GPU configuration. Required when role is GPU.

# acceleratorType required string 1–63 chars

GPU accelerator type (e.g. nvidia-h100, nvidia-l40s). Used to label GPU nodes; the actual GPU and count are determined by the platform and preset.

# driversPreset optional string 1–63 chars default: cuda13.0

NVIDIA driver stack mk8s preinstalls on the group’s nodes (e.g. cuda12.4, cuda13.0). Valid values depend on the platform and Kubernetes version, and mk8s validates them, so new presets work without a Modelplane update. Defaults to the only preset mk8s implements on the default Kubernetes version; older presets remain for older versions.

# maxNodeCount optional integer 1–1000

Maximum number of nodes for autoscaling. When set the node group autoscales between minNodeCount (or nodeCount) and this; mk8s autoscaling is server-side, no in-cluster autoscaler is installed. Omit for fixed-size groups - unlike other clouds there is no default, because mk8s node groups are either fixed size or autoscaled, never both.

# minNodeCount optional integer ≤ 1000

Minimum number of nodes for autoscaling. Defaults to nodeCount when maxNodeCount is set. Requires maxNodeCount.

# name required string 1–40 chars

Unique name for this node group. Used as a suffix in the mk8s NodeGroup resource name.

# nodeCount optional integer ≤ 1000 default: 1

Number of nodes. Fixed unless maxNodeCount enables autoscaling.

# platform required string 1–63 chars

Nebius compute platform for the group’s nodes (e.g. gpu-h100-sxm, gpu-l40s-a, cpu-d3). Together with preset this replaces the instance type used by other clouds.

# preset required string 1–63 chars

Resource preset within the platform (e.g. 8gpu-128vcpu-1600gb, 4vcpu-16gb). Determines the GPU, vCPU, and memory shape of each node.

# role required enum: System | GPU

Determines what workloads this group runs. System groups host controllers, gateways, and infrastructure. GPU groups host inference workloads and are tainted to exclude non-GPU pods.

#Status

# cache optional object

Observed ModelCache RWX storage state, served by the Nebius shared filesystem mounted on every node group and Nebius’s csi-mounted-fs-path CSI driver.

# storageClassName optional string ≤ 253 chars

Name of the Modelplane-managed ReadWriteMany StorageClass composed on this cluster for ModelCache PVCs. ModelCache reads this to target the cache PVC.

# secrets optional object[]
# key required string ≤ 253 chars

Key within the Secret that holds the credential data.

# name required string ≤ 253 chars

Name of the Secret.

# namespace optional string ≤ 253 chars

Namespace of the Secret, when it isn’t this NebiusCluster’s namespace. Set on the credentials entry when the credential is reused from the Secret the Nebius ClusterProviderConfig references.

# type required enum: Kubeconfig | NebiusServiceAccountCredentials

The type of credential this secret contains. Kubeconfig contains a kubeconfig file with the cluster endpoint and CA certificate. NebiusServiceAccountCredentials contains a Nebius service account JSON key that authenticates to the cluster via Nebius IAM.