Ključi za agente

Ključ za agenta je prijava za stroj: agenta umetne inteligence, opravilo CI ali skripto. Ključ deluje z API-jem kubehz, s kubectl na tvojih gostovanih gručah in prostorih ter s strežnikom MCP. Sestavljata ga ID odjemalca in skrivnost odjemalca. Nikoli ne potrebuje tvojega gesla in vsak ključ poteče.

Aplikacija UI, kot sta Claude ali ChatGPT, lahko deluje v tvojem imenu tudi brez ključa. Glej Poveži aplikacijo v svojem imenu.

Ustvari ključ

Potrebuješ vlogo Owner ali Admin v najemniku. Najemnik ima lahko največ 25 aktivnih ključev.

1. Na nadzorni plošči odpri Dostop → Ključi za agente.
2. Klikni Nov ključ za agenta.
3. V polje Ime vpiši ime z največ 64 znaki, na primer ci-agent.
4. Pod Vloga izberi Pregledovalec, Urejevalec ali Skrbnik.
5. Pod Doseg izberi Izbrane gruče in prostori ali Ves najemnik.
6. Če si izbral Izbrane gruče in prostori, označi gruče in prostore, ki jih ključ doseže.
7. V polje Poteče po (dneh) vpiši število od 1 do 90. Privzeto je 30.
8. Neobvezno: v polje Mesečna omejitev porabe v evrih (neobvezno) vpiši omejitev.
9. Klikni Ustvari ključ.
10. Če se odpre okno za prijavo, potrdi s svojim drugim faktorjem.
11. Kopiraj Skrivnost odjemalca in blok Okolje za lo kubehz token. kubehz skrivnost pokaže samo tokrat.
12. Klikni Shranil sem jo.

Vloga

Vloga	V API-ju kubehz	V gručah in prostorih
Pregledovalec	Bere gruče in prostore	Bere, brez skrivnosti
Urejevalec	Poleg tega ustvarja, spreminja in briše gruče in prostore	Bere in piše večino virov
Skrbnik	Kot Urejevalec. Poleg tega bere revizijski dnevnik in obračun ter lahko poveže žeton Hetzner Cloud	Poln nadzor, tudi nad skrivnostmi in RBAC

Doseg

• Izbrane gruče in prostori je privzeta izbira. Ključ doseže le gruče in prostore, ki jih označiš, največ 50 vsake vrste. Doseže tudi to, kar ustvari sam. Če ne označiš ničesar, ključ doseže le to, kar ustvari sam.
• Ves najemnik: ključ doseže vse gruče in prostore najemnika, tudi tiste, ki jih kdo ustvari pozneje.

Omejitev porabe

Omejitev šteje stroške gruč in prostorov, ki jih je ključ ustvaril, na koledarski mesec (UTC). Ko stroški dosežejo omejitev, ključ ne more ustvariti gruče ali prostora, podaljšati zakupa ali spremeniti gruče. Kar že teče, teče naprej in stane, dokler tega kdo ne izbriše ali dokler se zakup ne konča. Omejitev torej ustavi novo porabo. Ni trda meja.

• Štetje uporablja polno ceno, brez brezplačne kvote in brez popusta.
• Štetje lahko zaostaja do ene ure.
• Štetje se začne znova 1. v vsakem mesecu (UTC).
• Omejitev je od 1 do 100.000 evrov. Pusti polje prazno, če ne želiš omejitve.

Uporabi ključ s kubectl

Kubeconfig za agenta deluje na gostovanih gručah in na prostorih. Gruča, ki jo gostiš sam, ima svoj RBAC. Ključ jo doseže le prek API-ja kubehz.

Na stroju, ki poganja kubectl, potrebuješ lo, CLI orodja lok8s.

1. Odpri stran gostovane gruče ali prostora.
2. Klikni Prenesi kubeconfig za agenta.
3. Datoteko shrani kot agent.kubeconfig.
4. Nastavi štiri spremenljivke iz bloka Okolje za lo kubehz token.
5. Zaženi kubectl z datoteko.

export KUBEHZ_AGENT_CLIENT_ID='...'
export KUBEHZ_AGENT_CLIENT_SECRET='...'
export KUBEHZ_AGENT_TOKEN_URL='https://id.kubehz.cloud/oauth/v2/token'
export KUBEHZ_AGENT_SCOPE='...'
kubectl --kubeconfig agent.kubeconfig get pods

Datoteka ne vsebuje skrivnosti. kubectl zažene lo kubehz token, ki s ključem pridobi žeton. lo žeton hrani do pet minut pred njegovim potekom, zato klic kubectl ne stane nove prijave.

Uporabi ključ z API-jem

lo kubehz token --format token izpiše samo žeton:

TOKEN=$(lo kubehz token --format token)
curl -s -H "Authorization: Bearer $TOKEN" https://api.kubehz.cloud/api/agent-keys/self

Brez lo uporabi dodelitev OAuth client credentials:

TOKEN=$(curl -s -u "$KUBEHZ_AGENT_CLIENT_ID:$KUBEHZ_AGENT_CLIENT_SECRET" \
  -d grant_type=client_credentials --data-urlencode "scope=$KUBEHZ_AGENT_SCOPE" \
  "$KUBEHZ_AGENT_TOKEN_URL" | jq -r .access_token)

GET /api/agent-keys/self pokaže vlogo, doseg in potek ključa ter njegovo porabo v tem mesecu z omejitvijo. Za ključ z Izbrane gruče in prostori navede tudi gruče in prostore, ki jih ključ doseže.

Zakup: kar ustvari agent, se konča samo

Prostor ali gostovana gruča, ki jo ustvari ključ za agenta, ima vedno zakup. Zakup traja dve uri ali toliko ur, kot jih navede ustvarjanje (leaseHours, 1 do 720). Ko se zakup konča, kubehz izbriše prostor ali gručo. Tako agent, ki se ustavi ali pozabi, ne more pustiti gruče, ki teče in stane.

• Za podaljšanje zakupa agent pošlje PATCH /api/spaces/{id}/lease ali PATCH /api/clusters/{id}/lease z {"hours": 24}. Novi konec je 24 ur od zdaj.
• Zakup podaljšaj, preden se konča. Po koncu kubehz zavrne vsako spremembo, tudi podaljšanje (LEASE_ENDED). Prostor ali gručo lahko še bereš ali izbrišeš. kubehz ga izbriše v nekaj minutah.
• Ključ za agenta zakupa ne more odstraniti. Oseba z vlogo Owner ali Admin ga lahko. Za prostor klikni Odstrani zakup na njegovi strani. Za gostovano gručo pošlji {"hours": null} v API.
• Oseba, ki nastavi zakup ali premakne njegov konec bližje, potrdi z drugim faktorjem. Za podaljšanje ali odstranitev zakupa drugi faktor ni potreben.
• Zakup, daljši od šestih ur, dobi eno e-poštno sporočilo približno eno uro pred koncem. Sporočilo gre lastniku najemnika. Če ga ne želiš, v Nastavitve → Obvestila izklopi Zakup se kmalu konča.
• Gruča, ki jo gostiš sam, nima nikoli zakupa. kubehz ne konča ničesar, kar teče v tvojem lastnem računu Hetzner.

Na strani prostora z zakupom kartica Zakup pokaže konec. Za nov konec vpiši ure v Ure od zdaj in nato klikni Podaljšaj zakup.

Česa ključ ne more

• Ustvarjati ključev za agente ali API-žetonov, upravljati članov ali vklapljati in izklapljati aplikacij UI.
• Odstraniti zakupa.
• Z vlogo Pregledovalec: spremeniti gruče ali prostora.
• Z vlogo Pregledovalec ali Urejevalec: brati revizijskega dnevnika ali obračuna ali povezati žetona Hetzner Cloud.
• Z Izbrane gruče in prostori: videti drugih gruč in prostorov ali brati podatkov celotnega najemnika, na primer njegovih stroškov.
• Uporabljati kubectl na gruči, ki jo gostiš sam.

Prekliči ključ

1. Odpri Dostop → Ključi za agente.
2. V vrstici ključa klikni Prekliči.
3. V pogovornem oknu klikni Prekliči.

API kubehz ključ takoj zavrne. Zavrne ga tudi strežnik MCP, ker gre vsak klic orodja prek API-ja. Žeton, ki ga agent že ima, v gručah in prostorih deluje do poteka, največ 12 ur. Preklica ne moreš razveljaviti.

Ključ se konča tudi na dan poteka. Seznam opozori 14 dni pred koncem in znova 3 dni pred njim.