kubernetesPractitioner

Mastering K3s with k0rdent: Custom Templates for On-Prem GitOps

5 min read CNCF BlogApr 17, 2026Reviewed for accuracy

Practitioner — Hands-on experience recommended

K3s is a lightweight Kubernetes distribution designed for on-prem and edge environments. When you need a robust yet simple solution for managing your Kubernetes clusters, K3s paired with k0rdent offers a streamlined approach. k0rdent enables you to manage the full cluster lifecycle, making it easier to provision and maintain your K3s clusters in a GitOps fashion.

The process involves using k0rdent to provision a K3s cluster on your on-premise environment. You’ll write custom Helm charts and utilize k0rdent’s Bring Your Own Template (BYOT) approach. The flow is straightforward: User → k0rdent → Proxmox Infrastructure (BYOT VMs) → Control Plane Provider → Bootstrap Provider (K3s) → Running Kubernetes Cluster. Key configuration parameters include the version of K3s you want to deploy, which defaults to v0.3.0, and the URL to fetch the bootstrap components for K3s, also defaulting to a GitHub link.

In production, understanding how to leverage k0rdent effectively is crucial. Pay attention to the configuration parameters, especially the fetchConfig.url, as this points to the necessary bootstrap components. The versioning is also vital; ensure you’re using the correct version to avoid compatibility issues. While k0rdent simplifies cluster management, be aware of potential pitfalls in your specific environment, especially when integrating with existing infrastructure.

Key takeaways

→Utilize k0rdent to manage the full lifecycle of your K3s clusters.
→Write custom Helm charts to tailor your K3s deployment to your needs.
→Leverage the BYOT approach for flexible provisioning on Proxmox.
→Set the K3s version to v0.3.0 for consistent deployments.
→Fetch bootstrap components from the specified GitHub URL.

Why it matters

Using K3s with k0rdent allows for efficient management of Kubernetes clusters in on-prem environments, reducing overhead and improving deployment speed. This is crucial for teams looking to implement GitOps practices effectively.

Code examples

YAML

1apiVersion: operator.cluster.x-k8s.io/v1alpha2
2
3kind: BootstrapProvider
4
5metadata:
6
7
8name: k3s
9
10spec:
11
12
13version: v0.3.0
14
15
16fetchConfig:
17
18
19
20url: https://github.com/k3s-io/cluster-api-k3s/releases/v0.3.0/bootstrap-components.yaml
21
22
23{{- if .Values.configSecret.name }}
24
25
26configSecret:
27
28
29
30name: {{ .Values.configSecret.name }}
31
32
33
34namespace: {{ .Values.configSecret.namespace | default .Release.Namespace | trunc 63 }}
35
36
37{{- end }}

YAML

1apiVersion: operator.cluster.x-k8s.io/v1alpha2
2
3kind: ControlPlaneProvider
4
5metadata:
6
7
8name: k3s
9
10spec:
11
12
13version: v0.3.0
14
15
16fetchConfig:
17
18
19
20url: https://gi