Karpenter Provider for UpCloud

Karpenter provider implementation for UpCloud, enabling efficient, just-in-time node autoscaling.

Important

Beta — in working state but not yet considered production-ready. Core provisioning, scale-from-zero, drift detection, node repair, GPU (spot) scheduling all work. Expect breaking changes in early stages.

Note: the n+1 VM issue (kubernetes-sigs/karpenter#3121) is fixed in this provider via a fork of Karpenter with a fix PR (#3243) pending upstream merge. Until the PR is merged, this provider uses the forked dependency via a replace directive in go.mod.

Features

This provider contains these features:

• Scale-from-zero provisioning
• Full UpCloud plan catalog as instance types (CLOUDNATIVE, STARTER, PREMIUM, GPU)
• GPU spot instance support
• Drift detection (recycles nodes when the UpCloudNodeClass changes)
• Node repair (replaces unhealthy or unjoined nodes)
• Configurable node storage (CLOUDNATIVE, GPU)
• Support for storage-bundled plans (STARTER, PREMIUM)
• Absolute NodeClaim lifetime TTL (alpha version - expect unstability)

For full feature details, see FEATURES.md.

Required environment variables

Variable	Description
UPCLOUD_TOKEN	UpCloud API token
UPCLOUD_KUBERNETES_CLUSTER_ID	UKS cluster UUID
UPCLOUD_TEMPLATE_UUID	OS template UUID for node boot disk
UPCLOUD_REPAIR_TOLERATION	How long a NotReady/Unknown node is tolerated before Karpenter recycles it
UPCLOUD_NODECLAIM_TTL	Enable NodeClaim TTL controller by setting a duration. Defines the absolute lifetime for NodeClaims (e.g. 50m, 1h). Disabled by default.

Note

UPCLOUD_TEMPLATE_UUID and UPCLOUD_REPAIR_TOLERATION are considered required unless deploying via the Helm chart, which provides their defaults.

Required UpCloud API permissions

The credentials need the following permissions in the UpCloud API:

Resource	Reason
Kubernetes cluster	Auto-detect zone, plan, and API server endpoint of the target cluster
Server	Provision and terminate Karpenter-managed nodes
Storage	Create/clean up cloud-init and OS disk storage
Private network	Attach nodes to the correct K8s network

Use a dedicated token or sub-account with the above permissions. UPCLOUD_TOKEN is used with bearer auth.

Project structure

├── cmd/karpenter-upcloud/     ← entry point + Containerfile
├── internal/version/          ← build-time version info
├── apis/v1alpha2/             ← UpCloudNodeClass CRD types
├── pkg/
│   ├── cloudprovider/         ← core provider implementation
│   │   └── helpers.go         ← bootstrap token + CA bundle
│   ├── controllers/           ← Kubernetes controllers
│   │   ├── nodeclaimttl/      ← alpha TTL controller
│   │   └── nodeclass/         ← nodeclass reconciliation
│   ├── events/                ← Kubernetes events emitted by the provider
│   ├── providers/
│   │   ├── options.go         ← env var parsing
│   │   ├── instance/          ← server lifecycle (Create/Delete/Get/List)
│   │   ├── instancetypes/     ← plan discovery + cached pricing
│   │   └── userdata/          ← cloud-init generation
│   └── util/                  ← shared utility helpers
├── deploy/helm/               ← Helm chart
├── examples/                  ← sample CRDs
├── test/e2e/                  ← end-to-end integration tests
├── Makefile

Developing

make test      # vet + test
make build     # compile binary
make container-build  # build OCI image via buildah

Credits

• UpCloud Ltd — Sponsors the test infrastructure used for integration and e2e testing.
• Zed Industries — Provides a free version of their editor.

License

EUPL 1.2 — see LICENSE.

Changelog

See CHANGELOG.md for version history.