Eerste cluster
Een gedetailleerde uitleg van het configuratiebestand cluster.lok8s.yaml.
Vereisten
- lok8s CLI geïnstalleerd
- Een Hetzner Cloud-account met een API-token
- Een SSH-sleutelpaar (Ed25519 aanbevolen)
- Een domein dat je beheert: het API-endpoint en de certificaatnamen worden daarvan afgeleid (als
spec.cluster.domain;example.comhieronder is een plaatsaanduiding)
Volledige configuratiereferentie
Toon de volledige cluster.lok8s.yaml
# clusters/example.com/cluster.lok8s.yaml
apiVersion: cluster.lok8s.dev/v1beta1
kind: KubeOne
metadata:
name: my-cluster
spec:
kubernetes:
version: "v1.35.5"
cluster:
# VERPLICHT: een domein dat je beheert; voor ingress en certificaten
domain: example.com
# standaardnamespace voor workloads
namespace: default
provider:
name: hetzner
# De machines, in de termen van Hetzner zelf. Elk `server`-item wordt één
# `hcloud server create`; zijn sleutels zijn hcloud-flags. Zet dezelfde
# inhoud in een apart bestand en verwijs ernaar met `configRef: hetzner.json`
# als je een kortere spec wilt.
config:
cluster_name: my-cluster
sshUser: root
sshPrivateKey: ~/.ssh/id_ed25519
sshPublicKey: ~/.ssh/id_ed25519.pub
ssh-key:
- name: my-cluster
public-key-from-file: ~/.ssh/id_ed25519.pub
network:
- name: my-cluster
# bereik van het privénetwerk
ip-range: 10.0.0.0/16
"#subnets":
- network-zone: eu-central
type: cloud
ip-range: 10.0.0.0/24
server:
# 3 control planes voor HA; 1 is genoeg voor dev
- name: cp-1
type: cx33
image: ubuntu-24.04
# fsn1, nbg1 of hel1
location: fsn1
ssh-key: [0]
network: 0
label: lok8s.dev/cluster=my-cluster,lok8s.dev/role=control-plane
- name: cp-2
type: cx33
image: ubuntu-24.04
location: fsn1
ssh-key: [0]
network: 0
label: lok8s.dev/cluster=my-cluster,lok8s.dev/role=control-plane
- name: cp-3
type: cx33
image: ubuntu-24.04
location: fsn1
ssh-key: [0]
network: 0
label: lok8s.dev/cluster=my-cluster,lok8s.dev/role=control-plane
- name: worker-1
type: cpx31
image: ubuntu-24.04
location: fsn1
ssh-key: [0]
network: 0
label: lok8s.dev/cluster=my-cluster,lok8s.dev/role=worker
- name: worker-2
type: cpx31
image: ubuntu-24.04
location: fsn1
ssh-key: [0]
network: 0
label: lok8s.dev/cluster=my-cluster,lok8s.dev/role=worker
# cluster-infra-addons, toegepast in volgorde
bootstrap:
# CNI (de standaard als weggelaten)
- cilium
# Hetzner cloud-controller-manager
- ccm
- cert-manager
- monitoring
kubehz:
# self (jij draait alles) | hosted (kubehz draait het control plane)
# | shared (een Space op een gedeeld control plane, kind: Kubehz)
hosting: self
# none | registered | managed (Supporter+)
access: registered
# cronjob (alleen-lezen heartbeat) | operator (managed-tier, live weergave)
agent: cronjob
apiUrl: https://api.kubehz.cloudBelangrijkste secties
spec.kubernetes
Stel de Kubernetes-versie in. kubehz biedt een samengestelde lijst aan, elke versie vastgezet op een patchrelease: vandaag v1.34.8 en v1.35.5 (de standaard). Een versie verdwijnt zodra upstream haar minor niet meer patcht.
spec.provider
Wie de machines levert. name: hetzner kiest Hetzner Cloud, de enige geïmplementeerde provider. config (of configRef, een pad naar een JSON- of YAML-bestand naast de spec) is de providerbeschrijving: de SSH-toegang die lok8s gebruikt (sshUser, sshPrivateKey, sshPublicKey), en één lijst per Hetzner-resource (ssh-key, network, server, en optioneel volume en load-balancer). Elk item wordt één hcloud <resource> create, en zijn sleutels zijn de flags van dat commando. ssh-key: [0] en network: 0 bij een server verwijzen op index naar items in die lijsten.
Het label lok8s.dev/role bepaalt wat een server wordt: control-plane of worker. Drie control planes geven je HA; één is genoeg voor ontwikkeling. type is een Hetzner-servertype, location het datacenter.
Bare metal. Een dedicated server van Hetzner sluit als #cloud.root-item aan op dezelfde beschrijving (een Robot-server die lok8s opnieuw imaget en inschrijft). Zie de lok8s-providerreferentie voor de vorm.
Verouderde vorm. Oudere specs bevatten spec.ssh, spec.controlPlane en spec.workers. lok8s leest ze nog als fallback, maar gebruik ze niet in nieuwe specs: de providerbeschrijving bezit de SSH-toegang en de node-topologie.
spec.bootstrap
Een geordende lijst cluster-infra-addons (CNI, CCM, cert-manager, monitoring, …) die bij het provisionen worden toegepast, voordat er workloads landen. Elk item wordt toegepast en afgewacht voordat het volgende aan de beurt is. Kale namen verwijzen naar lok8s-framework-addons; ./pad-items wijzen naar je eigen kustomize-directory’s. Als het veld wordt weggelaten, is de standaard cilium: elk cluster heeft een CNI nodig. Zie de lok8s-addonsgids voor de volledige lijst.
spec.kubehz
Optionele integratie met het kubehz-platform. hosting zegt wie het control plane draait: self (jij, op je eigen account), hosted (kubehz, zie Hosted) of shared (een Space op een control plane dat kubehz deelt tussen klanten; hiervoor is kind: Kubehz nodig). access zegt wat kubehz ziet: none, registered (alleen-lezen gezondheid) of managed (voegt de beheerfuncties toe: healing-beleid, capaciteitsbewaking, beheer van de gewenste staat; vereist een Supporter-abonnement of hoger). Handelen is pull-gebaseerd: de in-cluster agent haalt de gewenste staat op bij het platform en past die toe met de eigen credentials van je cluster; kubehz heeft nooit inkomende toegang.
De overige sleutels zijn optioneel:
| Sleutel | Betekenis |
|---|---|
agent | Welke in-cluster agent de heartbeat bezit: cronjob (de alleen-lezen standaard) of operator (de live weergave van de managed-tier). |
apiUrl | De kubehz-API, alleen HTTPS. Verplicht zodra access niet none is, en voor hosted en shared. |
connectHcloudToken | true geeft het platform bij registratie je HCLOUD_TOKEN, alleen over HTTPS, zodat een gehost cluster worker pools kan aanmaken. Standaard uit. |
upgrades | channel: none / patch / minor (hoe ver het platform ongevraagd mag upgraden, standaard patch) en defer: window / immediate. |
maintenanceWindow | Wanneer platformgestuurd werk mag draaien: daysOfWeek, startTime, durationMinutes, timezone en exclusions (datums of periodes die alles bevriezen). |
space | Alleen bij hosting: shared: de slug van de Space, de weergave-name en de nodes waarvoor bij het provisionen join-tickets worden aangemaakt. |
Zie Hoe het werkt voor het volledige model en de vertrouwensgrens, en Registratie om zichtbaarheid in te schakelen.
Sla het bestand op
lo houdt één map per cluster bij onder clusters/, vernoemd naar het domein, en leest daar cluster.lok8s.yaml uit. Maak de map aan, sla het bestand op en markeer het domein daarna als actief:
mkdir -p clusters/example.com
# plak de bovenstaande reference in clusters/example.com/cluster.lok8s.yaml
lo use example.comlo use legt het actieve domein vast in clusters/.active; --domain <domein> of DOMAIN_NAME overschrijft het voor één commando.
Pas dit aan vóór het uitrollen. De reference bevat placeholders, geen standaardwaarden:
| Veld | Placeholder | Wat het moet zijn |
|---|---|---|
metadata.name | my-cluster | de naam van je cluster |
spec.cluster.domain en de map | example.com | een domein dat je beheert (wordt gebruikt voor het API-endpoint) |
de SSH-paden in provider.config | ~/.ssh/id_ed25519[.pub] | het echte pad van je sleutel, alleen als die niet de standaard Ed25519-naam heeft |
Geef lok8s je Hetzner-token
lo provision maakt echte, factureerbare infrastructuur aan in je Hetzner-account en authenticeert met het API-token uit de vereisten. Exporteer het in dezelfde shell van waaruit je zo gaat uitrollen. Het wordt uit de omgeving gelezen, nooit uit het configuratiebestand, dus het belandt nooit in git:
export HCLOUD_TOKEN="<jouw-token>"Rol je cluster uit
Voer dit uit vanuit je projectmap, met het domein actief:
lo provisionUitrollen duurt meestal 10–15 minuten. De kubeconfig wordt weggeschreven naar .kubeconfig/my-cluster.yaml in je project, vernoemd naar metadata.name. Je ~/.kube/config blijft ongemoeid.
De referentieconfiguratie hierboven vraagt Hetzner om vijf servers (3 voor het control plane en 2 workers), die per uur worden gefactureerd tegen de gepubliceerde prijzen van Hetzner voor die servertypes. Niets hiervan is onomkeerbaar: lo destroy verwijdert wanneer je maar wilt elke server die lok8s heeft aangemaakt.
Verifiëren
kubectl wijst nog steeds naar de context die je eerder gebruikte, dus selecteer het nieuwe cluster expliciet; anders antwoordt get nodes voor je vorige:
export KUBECONFIG=.kubeconfig/my-cluster.yaml
kubectl get nodes
# (AGE trimmed — STATUS is what to check)
# NAME STATUS ROLES VERSION
# cp-1 Ready control-plane v1.35.5
# cp-2 Ready control-plane v1.35.5
# cp-3 Ready control-plane v1.35.5
# worker-1 Ready <none> v1.35.5
# worker-2 Ready <none> v1.35.5
kubectl get pods -A
# Toont ALLEEN pods die nog niet gereed zijn. Op een gezonde cluster: niets.
kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded
# No resources foundElke node hoort Ready te zijn en de kolom VERSION hoort overeen te komen met de hierboven ingestelde Kubernetes-versie.
kubectl get pods -A toont alle systeempods, veel om na te lopen. Het tweede commando draait het om: het laat alleen zien wat niet Running of Completed heeft bereikt. No resources found is het antwoord dat je wilt. Geef de CNI en de cloud-controller vlak na het uitrollen een minuut voordat je iets in die lijst als fout beschouwt.
Volgende stappen
- Dashboard-setup: monitor je cluster
- Registratie: verbind met het kubehz-dashboard
- KubeOne-gids: geavanceerde KubeOne-configuratie
Documentstatus
| Aspect | Detail |
|---|---|
| Status | actief |
| Laatst gecontroleerd | 2026-09-05 |