Modelplane Modelplane docs

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

A CivoCluster provisions a Civo Kubernetes (k3s) cluster with a dedicated network and firewall, and 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. Civo has no server-side node pool autoscaler; pools with maxNodeCount set are scaled by the Kubernetes cluster autoscaler installed on the cluster. The system pool is a fixed inline pool on the cluster resource, honored at creation time only.

#Metadata

API version
infrastructure.modelplane.ai/v1alpha1
Kind
CivoCluster
Scope
Namespaced

#Example

Manifest
apiVersion: infrastructure.modelplane.ai/v1alpha1
kind: CivoCluster
metadata:
  name: inference-nyc1
  namespace: platform
spec:
  region: NYC1
  nodePools:
    - name: workers
      role: System
      size: g4p.kube.small
      nodeCount: 2
    - name: gpu-l40s
      role: GPU
      size: an.g1.l40s.kube.x1
      nodeCount: 1
      maxNodeCount: 8
      gpu:
        acceleratorType: nvidia-l40s

#Spec

CivoClusterSpec defines the desired state of CivoCluster.

# credentials optional object

Civo ProviderConfig or ClusterProviderConfig used to authenticate to the Civo 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–32 chars

Civo Kubernetes (k3s) version. Civo requires an exact version string including the k3s build suffix (e.g. 1.36.0-k3s1); list current versions with civo kubernetes versions. Choose 1.34 or newer so Dynamic Resource Allocation (how devices bind to pods) is generally available, and 1.36 or newer for a CPU pool: its cores are claimed as consumable capacity, which Kubernetes enables by default from 1.36 (DRAConsumableCapacity). Defaults to Civo’s current default version, which may be older than a CPU pool needs.

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

# maxNodeCount optional integer 1–1000

Maximum number of nodes for autoscaling. When set the node pool autoscales between minNodeCount (or nodeCount) and this. Civo has no server-side autoscaler, so the Kubernetes cluster autoscaler is installed on the cluster to drive the pool’s node count through the Civo API. 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 Civo cluster.

# nodeCount optional integer 1–1000 default: 1

Number of nodes. Fixed unless maxNodeCount enables autoscaling.

# 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 size and the modelplane.ai/cpu label and taint.

# size required string 1–63 chars

Civo instance size for the pool’s nodes (e.g. an.g1.l40s.kube.x1, g4p.kube.small). This is the instance type used by other clouds; list sizes with civo kubernetes size.

# region required string 1–32 chars

Civo region for the cluster (e.g. LON1, NYC1, FRA1). GPU sizes vary by region; list availability with civo region ls and civo kubernetes size.

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