Registracija

Registriraj svoj cluster z lastnim gostovanjem na platformi kubehz za vpogled prek nadzorne plošče.

Registracija in prevzem sta polovici enega samega rokovanja:

1. Registracija (CLI): najavi cluster platformi kubehz. Cluster se ustvari s stanjem V nastajanju in še ni vezan na noben račun.
2. Prevzem (nadzorna plošča): dokažeš, da je cluster tvoj. Običajni dokaz je ključ za prevzem, ki ga lo naloži v tvoj projekt Hetzner Cloud; delujeta tudi koda za prevzem ali nonce, ki ga agent vrne v heartbeatu. Cluster se pripne tvojemu tenantu. Glej Prevzem.

Predpogoji

• Delujoč Kubernetes cluster, vzpostavljen z lok8s
• kubectl, konfiguriran in povezan s tvojim clustrom
• Račun kubehz (potreben za prevzem, ne za registracijo)

Konfiguracija

Dodaj blok kubehz v svojo cluster.lok8s.yaml:

spec:
  kubehz:
    # self | hosted | shared
    hosting: self
    # 'managed' odklene funkcije za upravljanje (Supporter+)
    access: registered
    # cronjob (heartbeat samo za branje) | operator (paket managed, pogled v živo)
    agent: cronjob
    apiUrl: https://api.kubehz.cloud

apiUrl mora biti HTTPS: CLI zavrne končne točke z navadnim HTTP. Neobvezni ključi (connectHcloudToken, upgrades, maintenanceWindow, space) so navedeni v poglavju Prvi cluster.

Ravni dostopa

Raven	Kaj vidi kubehz	Strošek
none	Nič: brez povezave	Brezplačno
registered	Vozlišča, različica K8s, zdravje komponent, potek certifikatov, razpoložljivost	Brezplačno (do 2 clustrov)
managed	Vse iz registered, dodatno podatki za upravljanje, na katerih temeljijo politike samodejnega okrevanja, nadzor kapacitet in upravljanje želenega stanja (nadgradnje/skaliranje)	Naročnina Supporter ali višja

Registriraj

Registracija se samodejno izvede med lo provision (kadar access ni none). Kadar koli jo lahko izvedeš tudi ročno:

lo kubehz register

Zahtevo na POST /api/clusters/register na nastavljeni apiUrl pošlje CLI s tvojega računalnika; v tvoj cluster se nič ne namesti. Kaj pošlje, je odvisno od tega, kaj imaš v lupini:

V tvoji lupini	Kaj se zgodi	Kako prevzameš
HCLOUD_TOKEN (običajni primer po lo provision)	API ustvari ključ za prevzem, lo pa njegov javni del naloži v tvoj projekt Hetzner Cloud kot kubehz-claim-<domena>. Ponovni zagon ključ zamenja.	Na strani za prevzem prilepiš prstni odtis ključa. Noben žeton ne zapusti tvojega računalnika.
KUBEHZ_TOKEN (API žeton clusters:write iz nadzorne plošče, Dostop → API žetoni)	Cluster se registrira neposredno na tvoj tenant. S connectHcloudToken: true v specifikaciji lo platformi preda tudi tvoj Hetzner žeton, samo prek HTTPS.	Ni kaj prevzeti: cluster je že tvoj.
nič od tega	lo pošlje domeno in prstni odtis MD5 SSH ključa iz tvojega opisnika ponudnika.	Koda za prevzem od heartbeat agenta ali prstni odtis, če ta ključ obstaja v tvojem projektu Hetzner.

Na običajni poti CLI izpiše prstni odtis, s katerim prevzameš cluster:

kubehz: cluster 'example.com' registered (pending). Claim key 'kubehz-claim-example.com' uploaded to your Hetzner Cloud account.
kubehz: claim it with the fingerprint ALONE — dashboard /claim (SSH fingerprint tab), or:
  curl -X POST https://api.kubehz.cloud/api/claims/verify -H 'Authorization: Bearer <khzt_ token (clusters:write)>' \
       -H 'Content-Type: application/json' -d '{"fingerprint":"..."}'
  fingerprint: aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99   (also visible in Hetzner Console -> Security -> SSH keys)

Prstni odtis identificira javni ključ. Ni skrivnost in ne razkriva ničesar o tvojih zasebnih ključih.

Cluster ima zdaj stanje V nastajanju: ni vezan na noben račun in ni viden nikomur, dokler ga ne prevzameš. Neprevzete registracije se samodejno izbrišejo po 30 dneh; kadar koli se lahko preprosto znova registriraš.

Prevzemi svoj cluster

Registracija sama clustra ne pripne nikomur. Pojdi v nadzorno ploščo in ga prevzemi: prilepi prstni odtis ključa za prevzem ali uporabi enega od drugih dokazov. Vodnik po korakih najdeš v poglavju Prevzem.

Heartbeati

Zdravje clustra na nadzorni plošči prihaja iz agenta v clustru, v namespace kubehz-system. Z agent: cronjob (privzeto) je to lahek CronJob z imenom kubehz-heartbeat, ki vsakih 5 minut na API kubehz pošlje (POST):

• različico Kubernetesa
• imena, stanje in vloge vozlišč
• zdravje komponent kontrolne ravnine
• potek certifikatov

Agent teče z RBAC samo za branje in utrjenim varnostnim kontekstom ter pošilja izključno izhodne zahteve: platforma kubehz se nikoli ne povezuje v tvoj cluster.

Namesti ga s CLI. Ta upodobi manifeste agenta, ki pridejo z lok8s (URL API-ja, tvojo domeno in lastnika heartbeata vstavi namesto tebe), in jih uveljavi s tvojo kubeconfig:

# najprej si oglej upodobljene manifeste, brez uveljavitve
lo kubehz deploy --dry-run

lo kubehz deploy

Ob prvem zagonu agent ustvari svojo skrivnost identitete, se sam registrira in začne pošiljati utrip. Vse možnosti: vodič lok8s kubehz Platform. Dokler agent ni nameščen, je tvoj cluster v nadzorni plošči prikazan kot Disconnected (registracija in prevzem delujeta tudi brez njega).

Način operator (paket managed)

Z agent: operator ukaz lo kubehz deploy ob CronJob namesti dolgo tekoči kubehz-agent in mu preda heartbeat. Ta opazuje cluster in ob vsaki spremembi pošlje koristni tovor po shemi 2. Vse, kar pošilja, so metapodatki; imena in vsebina delovnih obremenitev clustra nikoli ne zapustijo, razen če to izrecno vklopiš.

Polje	Kaj nosi
schema, clusterId, timestamp	2, ID tvojega clustra, čas utripa.
agent	version in mode (operator) agenta.
kubernetes.version	Različica API strežnika.
nodes[]	Za vsako vozlišče: name, status, ready, roles, instanceType, kubeletVersion in capacity (cpu, memory).
components[]	name in status komponent kontrolne ravnine.
workloads.pods	Število podov po fazah: total, running, pending, failed, succeeded, unknown. deployments (total, unavailable), kadar je vklopljen informer za aplikacije.
events[]	Nedavni dogodki tipa Warning: reason, kind, count, lastSeen.
actions[]	Napredek dejanj želenega stanja, ki jih je izvedel agent: type (scale, upgrade, heal), target, status, detail, revision.
machineIssues[]	Napake machine-controllerja: pool, machine, reason, message, since.
inventory	Kaj je namestil lok8s, iz objekta ClusterInventory, ki ga je zapisal tvoj lo: lok8sVersion, kind, provider, kubernetesVersion, specHash, renderedAt in addons[] (name, chartVersion, appVersion, category, source). Nikoli vrednosti chartov ali poverilnice.
pools[], desired, certificates	Rezervirano za opažene nabore workerjev, potrditev želenega stanja in potek certifikatov.

Samo na izrecno željo. Imena namespaceov se privzeto ne poročajo. Na agentu nastavi KUBEHZ_REPORT_NAMESPACES=true, da dodaš workloads.pods.byNamespace (število podov po namespaceih) ter polji namespace in note (sporočilo dogodka) pri dogodkih. Če spremenljivke ne nastaviš, teh ključev ni v nobenem utripu.

DPA ta polja imenuje heartbeat metapodatki.

Odpravljanje težav

# Stanje registracije, kot ga vidi CLI (potrebuje KUBEHZ_TOKEN)
lo kubehz status

# Je heartbeat CronJob na mestu?
kubectl -n kubehz-system get cronjob kubehz-heartbeat

# Dnevniki zadnjih heartbeat zagonov
kubectl -n kubehz-system logs -l app=kubehz-heartbeat

# Ponovno zaženi registracijo (varno ponovljivo)
lo kubehz register

# Agent je izgubil skrivnost identitete (namespace znova ustvarjen, cluster obnovljen):
# ustvari novo za isti registrirani cluster (potrebuje KUBEHZ_TOKEN)
lo kubehz re-enroll

Če je cluster registriran, a ga na tvoji nadzorni plošči ni, najverjetneje še ni prevzet; glej Prevzem.

Odjava

Za odstranitev clustra iz registra kubehz:

lo kubehz deregister

To odstrani vnos clustra pri kubehz in umakne ključ za prevzem iz tvojega projekta Hetzner. V tvojem clustru se nič ne spremeni; še naprej deluje neodvisno. Če želiš odstraniti tudi agenta, izbriši namespace kubehz-system in njegov RBAC na ravni clustra (glej Migracijo).

KUBEHZ_TOKEN

lo kubehz deregister, lo kubehz status in lo kubehz re-enroll berejo register clustrov tvojega tenanta, zato zahtevajo KUBEHZ_TOKEN: API žeton clusters:write, ustvarjen v nadzorni plošči pod Dostop → API žetoni. Registracija sama nikoli ne potrebuje žetona.

Naslednji koraki

• Prevzem: dokaži lastništvo in pripni cluster svojemu računu
• Nadzorna plošča: uporaba nadzorne plošče
• KubeOne: vodnik za orodje za vzpostavitev
• Gostovana vzpostavitev: alternativa z gostovano kontrolno ravnino

---

Status dokumenta

Vidik	Podrobnost
Stanje	aktivno
Nazadnje pregledano	2026-09-05