Prvi cluster
Podroben sprehod skozi konfiguracijsko datoteko cluster.lok8s.yaml.
Predpogoji
- Nameščen lok8s CLI
- Račun Hetzner Cloud z API žetonom
- Par SSH ključev (priporočamo Ed25519)
- Domena, ki jo nadzorujete: iz nje sta izpeljana končna točka API in imena certifikatov (kot
spec.cluster.domain;example.comspodaj je le primer)
Celotna referenca konfiguracije
Prikaži celotno 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:
# OBVEZNO: domena, ki jo nadzoruješ; za ingress in certifikate
domain: example.com
# privzeti namespace za workloade
namespace: default
provider:
name: hetzner
# Stroji v Hetznerjevih lastnih pojmih. Vsak vnos `server` postane en
# `hcloud server create`; njegovi ključi so zastavice hcloud. Če imaš
# raje krajšo specifikacijo, isto vsebino shrani v ločeno datoteko in
# nanjo pokaži s `configRef: hetzner.json`.
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
# obseg zasebnega omrežja
ip-range: 10.0.0.0/16
"#subnets":
- network-zone: eu-central
type: cloud
ip-range: 10.0.0.0/24
server:
# 3 kontrolne ravnine za HA; za dev je dovolj 1
- name: cp-1
type: cpx32
image: ubuntu-24.04
# fsn1, nbg1 ali hel1
location: fsn1
ssh-key: [0]
network: 0
label: lok8s.dev/cluster=my-cluster,lok8s.dev/role=control-plane
- name: cp-2
type: cpx32
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: cpx32
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: cpx32
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: cpx32
image: ubuntu-24.04
location: fsn1
ssh-key: [0]
network: 0
label: lok8s.dev/cluster=my-cluster,lok8s.dev/role=worker
# cluster-infra dodatki, uporabljeni po vrsti
bootstrap:
# CNI (privzeto, če je polje izpuščeno)
- cilium
# Hetzner cloud-controller-manager
- ccm
- cert-manager
- monitoring
kubehz:
# self (vse poganjaš sam) | hosted (kubehz poganja kontrolno ravnino)
# | shared (Space na deljeni kontrolni ravnini, kind: Kubehz)
hosting: self
# none | registered | managed (Supporter+)
access: registered
# cronjob (heartbeat samo za branje) | operator (paket managed, pogled v živo)
agent: cronjob
apiUrl: https://api.kubehz.cloudPrimer za vse strežnike uporablja cpx32 (4 vCPU, 8 GB RAM). Deluje tudi vsak tip z vsaj enakim številom vCPU in vsaj enako količino RAM, ki ga tvoj račun Hetzner ponuja na lokaciji.
Zaloga se razlikuje od računa do računa in se spreminja iz ure v uro: če Hetzner tip zavrne, uporabi drug tip ali drugo lokacijo (fsn1, nbg1 ali hel1).
Ključni razdelki
spec.kubernetes
Nastavi različico Kubernetesa. kubehz ponuja skrbno izbran seznam, vsaka različica je pripeta na popravkovno izdajo. Različica se umakne takoj, ko upstream neha popravljati njeno manjšo različico.
Seznam se spreminja, zato ta stran ne navaja popravkovnih izdaj: API trenutni seznam vrača na GET /api/versions (brez prijave), izbirnik različice v nadzorni plošči pa prikazuje isti seznam. 30. oktobra 2026 je seznam vseboval linijo 1.35.
spec.provider
Kdo zagotavlja stroje. name: hetzner izbere Hetzner Cloud, edinega izvedenega ponudnika. config (ali configRef, pot do datoteke JSON ali YAML ob specifikaciji) je opisnik ponudnika: dostop SSH, ki ga uporablja lok8s (sshUser, sshPrivateKey, sshPublicKey), in po en seznam na Hetznerjev vir (ssh-key, network, server ter po želji volume in load-balancer). Vsak vnos postane en hcloud <vir> create, njegovi ključi pa so zastavice tega ukaza. ssh-key: [0] in network: 0 pri strežniku kažeta na vnose teh seznamov po indeksu.
Oznaka lok8s.dev/role določi, kaj strežnik postane: control-plane ali worker. Tri kontrolne ravnine ti dajo HA; za razvoj je dovolj ena. type je tip Hetzner strežnika, location pa podatkovni center.
Namenski strežniki. Hetznerjev namenski strežnik se istemu opisniku pridruži kot vnos #cloud.root (strežnik Robot, ki ga lok8s znova namesti in vpiše). Obliko najdeš v referenci ponudnikov lok8s.
Opuščena oblika. Starejše specifikacije so nosile spec.ssh, spec.controlPlane in spec.workers. lok8s jih še vedno bere kot rezervo, v novih specifikacijah pa jih ne uporabljaj: dostop SSH in topologijo vozlišč ima v lasti opisnik ponudnika.
spec.bootstrap
Urejen seznam cluster-infra dodatkov (CNI, CCM, cert-manager, monitoring, …), ki se uveljavijo ob vzpostavitvi, preden pristanejo delovne obremenitve. Vsak vnos se uveljavi in počaka na pripravljenost, preden pride na vrsto naslednji. Gola imena se razrešijo v framework dodatke lok8s; vnosi ./pot kažejo na tvoje lastne kustomize imenike. Če je polje izpuščeno, je privzeta vrednost cilium: vsak cluster potrebuje CNI. Celoten seznam najdeš v vodiču za dodatke lok8s.
spec.kubehz
Neobvezna integracija s platformo kubehz. hosting pove, kdo poganja kontrolno ravnino: self (ti, na svojem računu), hosted (kubehz, glej Gostovano) ali shared (Space na kontrolni ravnini, ki si jo pri kubehz deli več strank; ta potrebuje kind: Kubehz). access pove, kaj kubehz vidi: none, registered (zdravje samo za branje) ali managed (doda funkcije za upravljanje: politike samodejnega okrevanja, nadzor kapacitet, upravljanje želenega stanja; zahteva naročnino Supporter ali višjo). Ukrepanje temelji na vleki: znotrajclustrski agent želeno stanje prevzame s platforme in ga uveljavi s poverilnicami tvojega clustra; kubehz nikoli nima dohodnega dostopa.
Ostali ključi so neobvezni:
| Ključ | Pomen |
|---|---|
agent | Kateri znotrajclustrski agent pošilja heartbeat: cronjob (privzeto, samo za branje) ali operator (pogled v živo v paketu managed). |
apiUrl | API kubehz, samo HTTPS. Obvezen, kadar access ni none, ter pri hosted in shared. |
connectHcloudToken | true ob registraciji platformi preda tvoj HCLOUD_TOKEN, samo prek HTTPS, da lahko gostovan cluster vzpostavlja nabore workerjev. Privzeto izklopljeno. |
upgrades | channel: none / patch / minor (kako daleč sme platforma nadgraditi brez vprašanja, privzeto patch) in defer: window / immediate. |
maintenanceWindow | Kdaj sme teči delo, ki ga vodi platforma: daysOfWeek, startTime, durationMinutes, timezone in exclusions (datumi ali obdobja, ki zamrznejo vse). |
space | Samo pri hosting: shared: slug Spacea, prikazno ime name in nodes, za katera se ob vzpostavitvi ustvarijo vstopnice za pridružitev. |
Za celoten model in mejo zaupanja glej Kako deluje, za vklop vidljivosti pa Registracijo.
Shrani datoteko
lo vodi eno mapo na cluster pod clusters/, poimenovano po domeni, in od tam bere cluster.lok8s.yaml. Ustvari mapo, shrani datoteko in nato domeno označi kot aktivno:
mkdir -p clusters/example.com
# zgornjo referenco prilepi v clusters/example.com/cluster.lok8s.yaml
lo use example.comlo use aktivno domeno zapiše v clusters/.active; --domain <domena> ali DOMAIN_NAME jo za en sam ukaz prepišeta.
To uredi pred vzpostavitvijo. Referenca prinaša ograde, ne privzetih vrednosti:
| Polje | Ograda | Kaj mora biti |
|---|---|---|
metadata.name | my-cluster | ime tvoje gruče |
spec.cluster.domain in mapa | example.com | domena, ki jo nadzoruješ (uporabi se za API-končno točko) |
poti SSH v provider.config | ~/.ssh/id_ed25519[.pub] | resnična pot do tvojega ključa, samo če nima privzetega imena Ed25519 |
Daj lok8s svoj Hetznerjev žeton
lo provision ustvari resnično, plačljivo infrastrukturo v tvojem Hetznerjevem računu in se overi z API-žetonom iz zahtev. Izvozi ga v isti lupini, iz katere boš vzpostavljal. Prebere se iz okolja, nikoli iz konfiguracijske datoteke, zato nikoli ne konča v gitu:
export HCLOUD_TOKEN="<tvoj-zeton>"Vzpostavi svoj cluster
Zaženi to iz imenika svojega projekta, z aktivno domeno:
lo provisionVzpostavitev običajno traja 10–15 minut. Kubeconfig se zapiše v .kubeconfig/my-cluster.yaml v projektu, poimenovan po metadata.name. Tvoj ~/.kube/config se ne spremeni.
Zgornja referenčna konfiguracija pri Hetznerju zahteva pet strežnikov (3 za kontrolno ravnino in 2 workerja), ki se obračunavajo po urah po objavljenih cenah Hetznerja za te tipe strežnikov. Nič od tega ni nepovratno: lo destroy kadar koli odstrani vsak strežnik, ki ga je ustvaril lok8s.
Preveri
kubectl še vedno kaže na kontekst, ki si ga uporabljal prej, zato novo gručo izberi izrecno; sicer get nodes odgovarja za tvojo prejšnjo:
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
# Izpiše SAMO pode, ki še niso pripravljeni. Na zdravi gruči ne izpiše ničesar:
kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded
# No resources foundVsak node naj kaže Ready, stolpec VERSION pa naj se ujema z zgoraj nastavljeno različico Kubernetesa.
kubectl get pods -A izpiše vse sistemske pode, kar je veliko za pregled, zato drugi ukaz obrne pogled: pokaže samo tisto, kar ni doseglo stanja Running ali Completed. No resources found je želeni odgovor. Takoj po vzpostavitvi daj CNI in cloud-controllerju minuto, preden karkoli od tega razumeš kot napako.
Naslednji koraki
- Vzpostavitev nadzorne plošče: spremljaj svoj cluster
- Registracija: poveži se z nadzorno ploščo kubehz
- Vodnik za KubeOne: napredna konfiguracija KubeOne
Status dokumenta
| Vidik | Podrobnost |
|---|---|
| Stanje | aktivno |
| Zadnji pregled | 2026-10-30 |