Modelplane Modelplane docs
★ Star the Project
Version
main v0.5 Latest v0.4 v0.3 v0.2

UpCloudCluster 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.5.

An UpCloudCluster provisions an UpCloud Managed Kubernetes (UKS) cluster on a dedicated SDN network, with node groups 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. UKS has no server-side node group autoscaler; pools with maxNodeCount set are scaled by the Kubernetes cluster autoscaler installed on the cluster, which authenticates to the UpCloud API with the token Secret spec.autoscaler references. UpCloud honors only nodeCount changes on an existing node group; any other node group change replaces the group.

#Metadata

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

#Example

Manifest
apiVersion: infrastructure.modelplane.ai/v1alpha1
kind: UpCloudCluster
metadata:
  name: inference-fi-hel2
  namespace: platform
spec:
  zone: fi-hel2
  autoscaler:
    secretRef:
      name: upcloud-autoscaler
  nodePools:
    - name: workers
      role: System
      plan: PREMIUM-4xCPU-16GB
      nodeCount: 2
    - name: gpu-l40s
      role: GPU
      plan: GPU-8xCPU-64GB-1xL40S
      nodeCount: 1
      maxNodeCount: 8
      gpu:
        acceleratorType: nvidia-l40s

#Spec

UpCloudClusterSpec defines the desired state of UpCloudCluster.

# autoscaler optional object

Credentials for the Kubernetes cluster autoscaler that scales pools with maxNodeCount set. UpCloud provisions no API credentials on UKS clusters, so the referenced Secret is copied to the cluster for the autoscaler to read. Required when any pool sets maxNodeCount.

# secretRef required object

Reference to a Secret in this UpCloudCluster’s namespace holding an UpCloud API token.

# key optional string 1–253 chars default: token
# name required string 1–253 chars
# credentials optional object

UpCloud ProviderConfig or ClusterProviderConfig used to authenticate to the UpCloud 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: 1.36

UKS Kubernetes version as major.minor (e.g. 1.36); list current versions with upctl kubernetes versions. Defaults to the newest UKS version. Choose 1.34 or newer so Dynamic Resource Allocation (how GPUs bind to pods) is generally available.

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

Node disk size in GB. Honored for GPU and Cloud Native plans, whose storage UpCloud unbundles from the plan; Starter and Premium plans bundle a fixed disk and ignore it. UKS’s default GPU plan disk is too small to hold an inference serving image.

# gpu optional object

GPU configuration. Required when role is GPU.

# acceleratorType required string 1–63 chars

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

# maxNodeCount optional integer 1–120

Maximum number of nodes for autoscaling. When set the node pool autoscales between minNodeCount (or nodeCount) and this. UKS has no server-side autoscaler, so the Kubernetes cluster autoscaler is installed on the cluster to drive the pool’s node count through the UpCloud API, which requires spec.autoscaler. Omit for fixed-size pools.

# minNodeCount optional integer 1–120

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

# name required string 1–63 chars

Unique name for this node pool. Used as the UKS node group name, so it must be lowercase alphanumeric and dashes.

pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

# nodeCount optional integer 1–120 default: 1

Number of nodes. Fixed unless maxNodeCount enables autoscaling.

# plan required string 1–63 chars

UpCloud server plan for the pool’s nodes (e.g. GPU-8xCPU-64GB-1xL40S, PREMIUM-4xCPU-16GB). This is the instance type used by other clouds; list plans with upctl server plans.

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

# zone required string 1–32 chars

UpCloud zone for the cluster and its network (e.g. fi-hel2, de-fra1). GPU plans are currently available in fi-hel2 only; list zones with upctl zone list.

#Status

# clusterId optional string ≤ 36 chars

UUID of the UKS cluster at UpCloud, once observed. compose-inference-cluster builds account-unique gateway load balancer names from it.

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