Modelplane Modelplane docs

VultrCluster Custom Resource

This document is for an unreleased version of Modelplane.

This document applies to the Modelplane main branch and not to the latest release v0.5.

A VultrCluster provisions a Vultr Kubernetes Engine (VKE) cluster with dedicated node pools for GPU inference and system workloads. It outputs a Secret containing the cluster kubeconfig. The kubeconfig embeds static client certificates, so consumers need nothing beyond it to reach the cluster. Note that provider-vultr only honors node pool changes at creation time; resize existing pools through VKE’s server-side autoscaler by setting maxNodeCount up front.

#Metadata

API version
infrastructure.modelplane.ai/v1alpha1
Kind
VultrCluster
Scope
Namespaced
Short names
vke

#Example

Manifest
apiVersion: infrastructure.modelplane.ai/v1alpha1
kind: VultrCluster
metadata:
  name: inference-ewr
  namespace: platform
spec:
  region: ewr
  kubernetesVersion: "v1.36.2+1"
  nodePools:
    - name: workers
      role: System
      plan: vc2-6c-16gb
      nodeCount: 2
    - name: gpu-l40s
      role: GPU
      plan: vcg-l40s-16c-180g-48vram
      nodeCount: 1
      maxNodeCount: 8
      gpu:
        acceleratorType: nvidia-l40s

#Spec

VultrClusterSpec defines the desired state of VultrCluster.

# credentials optional object

Vultr ProviderConfig or ClusterProviderConfig used to authenticate to the Vultr API. Defaults to the ClusterProviderConfig named default.

# name optional string 1–253 chars default: default
# type optional enum: ProviderConfig | ClusterProviderConfig default: ClusterProviderConfig
# kubernetesVersion optional string 1–16 chars default: v1.36.2+1

VKE cluster Kubernetes version. VKE requires an exact version string including the build suffix; list current versions with vultr-cli kubernetes versions. Defaults to a version where Dynamic Resource Allocation (how GPUs bind to pods) is generally available.

# nodePools required object[] 1–8 items
# gpu optional object

GPU configuration. Required when role is GPU.

# acceleratorType required string 1–63 chars

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

# maxNodeCount optional integer 1–1000

Maximum number of nodes for autoscaling. When set the node pool autoscales between minNodeCount (or nodeCount) and this; VKE autoscaling is server-side, no in-cluster autoscaler is installed. Omit for fixed-size pools.

# minNodeCount optional integer 1–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 pool. Used as the pool’s label in the VKE cluster.

# nodeCount optional integer 1–1000 default: 1

Number of nodes. Fixed unless maxNodeCount enables autoscaling. VKE pools always run at least one node.

# plan required string 1–63 chars

Vultr plan ID for the pool’s nodes (e.g. vcg-l40s-16c-180g-48vram, vc2-6c-16gb). This is the instance type used by other clouds; list plans with vultr-cli plans list.

# role required enum: System | GPU | CPU

Determines what workloads this pool runs. System pools host controllers, gateways, and infrastructure. GPU pools host inference workloads and are tainted to exclude non-GPU pods. CPU pools host CPU inference workloads: a non-GPU plan and the modelplane.ai/cpu label and taint.

# region required string 1–32 chars

Vultr region for the cluster (e.g. ewr, fra). GPU plans and Vultr File System availability vary by region.

#Status

# nodePools optional object[] ≤ 8 items
# message optional string

The provider’s error, prefixed with the name of the composed resource it’s about. Set only when state is Failed.

# name required string ≤ 40 chars

Name of the node pool in spec.nodePools.

# state required enum: Pending | Provisioning | Ready | Failed

Pending until Modelplane composes the pool’s cloud resources, Provisioning until their provider reports them all Ready, then Ready. Failed while the provider reports that its last create, update or delete of one of them failed.

# 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.

# type required enum: Kubeconfig

The type of credential this secret contains. Kubeconfig contains a kubeconfig file with the cluster endpoint, CA certificate, and static client certificates.