Modelplane Modelplane docs
Version
main v0.4 Latest v0.3 v0.2

CivoCluster Custom Resource

On this page
This document is for an unreleased version of Modelplane.

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

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.34.1-k3s1); list current versions with civo kubernetes versions. Choose 1.34 or newer so Dynamic Resource Allocation (how GPUs bind to pods) is generally available. Defaults to Civo’s current default version.

# 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

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.

# 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

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