Prevzem

S prevzemom dokažeš, da je registrirani cluster tvoj, in ga pripneš svojemu računu kubehz.

Registracija cluster zgolj najavi: ustvari se s stanjem V nastajanju in ne pripada nikomur. Katero koli domeno bi lahko najavil kdor koli, zato lastništvo potrebuje dokaz. Stran Prevzem na nadzorni plošči ponuja tri dokaze, četrta pot pa prevzem povsem preskoči:

Dokaz	Kaj potrebuje	Kdaj ga uporabiš
Ključ za prevzem (zavihek prstni odtis)	Prstni odtis, ki ga je izpisal lo kubehz register.	Običajni primer: vzpostavil si s HCLOUD_TOKEN v lupini.
Koda za prevzem	Nameščen heartbeat agent.	Kateri koli cluster, kateri koli ponudnik; projekt Hetzner ni udeležen.
Prek agenta (nonce)	Nameščen heartbeat agent in en ukaz lo.	Tako ali tako si v CLI in želiš, da nadzorna plošča opazuje, kako agent potrdi.
Neposreden pripis	KUBEHZ_TOKEN v lupini ob registraciji.	CI in avtomatizacija. Cluster se registrira naravnost na tvoj tenant; ni kaj prevzeti.

Možnost 1: ključ za prevzem (običajno)

Kadar je nastavljen HCLOUD_TOKEN, lo kubehz register od API-ja zahteva ključ za prevzem in njegov javni del naloži v tvoj projekt Hetzner Cloud pod imenom kubehz-claim-<domena>. Ta ključ lahko ima samo lastnik projekta, zato je dokaz njegov prstni odtis. Nikjer ne prilepiš nobenega žetona.

1. Odpri nadzorno ploščo na app.kubehz.cloud in se prijavi
2. Pojdi na stran Prevzem (Claim) in izberi zavihek Prstni odtis SSH
3. Prilepi prstni odtis iz izpisa CLI: MD5:aa:bb:cc:… ali gola oblika aa:bb:cc:… (sprejeti sta obe)
4. Klikni Prevzemi Cluster

kubehz prstni odtis primerja s ključem za prevzem, ki ga je ustvaril za ta cluster. Ob uspehu se cluster pripne tvojemu tenantu in odpre se njegova stran s podrobnostmi. Isto preverjanje je na voljo tudi iz skripta:

curl -X POST https://api.kubehz.cloud/api/claims/verify \
  -H "Authorization: Bearer $KUBEHZ_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"fingerprint":"aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99"}'

Če izgubiš izpis CLI, je prstni odtis naveden v Hetzner Console pod Security → SSH keys. Ponovni zagon lo kubehz register ključ zamenja in izpiše nov prstni odtis.

Podedovano: ključ za vzpostavitev

Cluster, registriran brez HCLOUD_TOKEN, se najavi s prstnim odtisom MD5 SSH ključa iz tvojega opisnika ponudnika (sshPublicKey). Če ta ključ obstaja v tvojem projektu Hetzner Cloud, ga isti zavihek s prstnim odtisom sprejme. Kadar koli ga lahko znova izračunaš:

# ključ, ki ga v tvojem opisniku ponudnika navaja sshPublicKey
ssh-keygen -E md5 -lf ~/.ssh/id_ed25519.pub

Možnost 2: koda za prevzem

Zahteva nameščen heartbeat agent: kodo ustvari ob prvem zagonu. Če lo kubehz claim-code ne izpiše ničesar, se agent še ni zagnal.

Agent ob prvem zagonu v tvojem clustru ustvari enkratno kodo za prevzem. Izpiši jo z lo kubehz claim-code (usmerjen na ta cluster). Potem je prevzem en sam prilepek:

1. Odpri nadzorno ploščo na app.kubehz.cloud in se prijavi
2. Pojdi na stran Prevzem (Claim) in izberi zavihek Koda za prevzem
3. Prilepi kodo za prevzem in končano. Cluster se pripne tvojemu tenantu in odpre se njegova stran s podrobnostmi.

Nekaj lastnosti, ki jih je vredno poznati:

• Neodvisna od ponudnika: koda deluje brez kakršnega koli projekta Hetzner, za kateri koli cluster.
• Porabi se ob uporabi: koda prevzame natanko en cluster, enkrat.
• Brez orakla: napačna, potekla ali že uporabljena koda vse vrnejo isti odgovor »not found« (ni najdeno); stran za prevzem ne razkrije, za katero od tega gre. Če tvoja koda ne deluje več, uporabi zgornji ključ za prevzem.
• Ustvarjena enkrat: agent kodo ustvari ob prvem zagonu in je nikoli ne zamenja; lo kubehz claim-code do porabe izpisuje isto kodo.

Možnost 3: prek agenta (nonce)

Tudi ta potrebuje heartbeat agent. Tu skrivnost ustvari nadzorna plošča, tvoj cluster pa jo vrne:

1. Na strani Prevzem izberi Prek agenta. Nadzorna plošča ustvari izzivni nonce (khzn_…) in čaka.

2. S CLI ga postavi v svoj cluster:

   lo kubehz claim --nonce khzn_...

3. Agent nonce vrne v naslednjem heartbeatu. Nadzorna plošča ga vidi in cluster pripne tvojemu tenantu.

Nonce je enkraten in kratkotrajen; če stran poteče, ustvari novega.

Možnost 4: brez prevzema

S KUBEHZ_TOKEN v lupini (API žeton clusters:write iz nadzorne plošče, Dostop → API žetoni) lo kubehz register cluster registrira neposredno na tvoj tenant. Takoj se pojavi na tvojem seznamu clustrov; koraka prevzema ni. To je pot za CI. Žeton hrani v shrambi skrivnosti, nikoli v specifikaciji.

Varnostne opombe

• Prstni odtis je javna informacija: identificira javni ključ, a se z njim ni mogoče izdajati zate. Ključ za prevzem deluje, ker ima ključ, ki ga je kubehz ustvaril za tvoj cluster, lahko samo tvoj projekt Hetzner.
• Platforma se nikoli ne povezuje v tvoj cluster. Podatki o zdravju tečejo izključno izhodno, prek heartbeat agenta.
• Če preverjanje ne uspe, nadzorna plošča to sporoči (»Claim verification failed«) in nič se ne pripne.

Po prevzemu

• Cluster zapusti stanje V nastajanju in se takoj pojavi na tvojem seznamu clustrov
• Podrobnosti o zdravju (vozlišča, zdravje komponent, potek certifikatov) se napolnijo s prihajajočimi heartbeati, osveženo vsakih 5 minut
• Connected pomeni, da je bil heartbeat prejet v zadnjih 15 minutah; nadzorna plošča iz zgodovine heartbeatov izpelje tudi 30-dnevno razpoložljivost

Odpravljanje težav

Simptom	Rešitev
Prstni odtis ni sprejet	Uporabi prstni odtis, ki ga je izpisal lo kubehz register, ali ga preberi v Hetzner Console (Security → SSH keys, ključ kubehz-claim-<domena>). Znova zaženi lo kubehz register z nastavljenim HCLOUD_TOKEN, da ustvariš svež ključ
Koda za prevzem »not found« (ni najdena)	Kode so enkratne in potečejo skupaj z registracijo. Uporabi ključ za prevzem
Stran »Prek agenta« kar čaka	Agent od takrat, ko si postavil nonce, ni poslal utripa. Preveri kubectl -n kubehz-system get cronjob kubehz-heartbeat, nato ustvari nov nonce
Ključa pri Hetznerju ni	lo kubehz register ključa za prevzem ni mogel naložiti. Preveri, da ima HCLOUD_TOKEN na projektu dovoljenje Read & Write, nato ga znova zaženi
Cluster še ni registriran	Najprej zaženi lo kubehz register. Glej Registracijo

Naslednji koraki

• Nadzorna plošča: kaj lahko vidiš in narediš po prevzemu
• Registracija: polovica rokovanja na strani CLI
• Cenik: kaj pokriva brezplačni paket

---

Status dokumenta

Vidik	Podrobnost
Stanje	aktivno
Nazadnje pregledano	2026-09-05