Agentsleutels

Een agentsleutel is een aanmelding voor een machine: een AI-agent, een CI-job of een script. De sleutel werkt met de kubehz-API, met kubectl op je gehoste clusters en spaces, en met de MCP-server. Hij bestaat uit een client-ID en een client-secret. Hij gebruikt nooit je wachtwoord, en elke sleutel verloopt.

Een AI-app zoals Claude of ChatGPT kan ook zonder sleutel namens jou handelen. Zie Een app namens jezelf verbinden.

Een sleutel aanmaken

Je hebt de rol Owner of Admin in de tenant nodig. Een tenant kan hooguit 25 actieve sleutels hebben.

1. Open in het dashboard Toegang → Agentsleutels.
2. Klik op Nieuwe agentsleutel.
3. Typ bij Naam een naam van hooguit 64 tekens, bijvoorbeeld ci-agent.
4. Kies bij Rol Lezer, Bewerker of Beheerder.
5. Kies bij Bereik Gekozen clusters en spaces of Hele tenant.
6. Als je Gekozen clusters en spaces hebt gekozen, vink je de clusters en spaces aan die de sleutel mag bereiken.
7. Typ bij Verloopt na (dagen) een getal van 1 tot 90. De standaard is 30.
8. Optioneel: typ bij Maandelijkse uitgavenlimiet in euro (optioneel) een limiet.
9. Klik op Sleutel aanmaken.
10. Als er een aanmeldvenster opent, bevestig je met je tweede factor.
11. Kopieer het Client-secret en het blok Omgeving voor lo kubehz token. kubehz toont het secret alleen deze ene keer.
12. Klik op Ik heb het opgeslagen.

Rol

Rol	In de kubehz-API	In clusters en spaces
Lezer	Leest clusters en spaces	Leest, zonder secrets
Bewerker	Maakt ook clusters en spaces aan, wijzigt en verwijdert ze	Leest en schrijft de meeste resources
Beheerder	Zoals Bewerker. Leest ook het auditlog en de facturatie, en kan het Hetzner Cloud-token koppelen	Volledige controle, ook over secrets en RBAC

Bereik

• Gekozen clusters en spaces is de standaard. De sleutel bereikt alleen de clusters en spaces die je aanvinkt, hooguit 50 van elk. Hij bereikt ook wat hij zelf aanmaakt. Vink je niets aan, dan bereikt de sleutel alleen wat hij zelf aanmaakt.
• Hele tenant: de sleutel bereikt alle clusters en spaces van de tenant, ook die iemand later aanmaakt.

Uitgavenlimiet

De limiet telt de kosten van de clusters en spaces die de sleutel heeft aangemaakt, per kalendermaand (UTC). Als de kosten de limiet bereiken, kan de sleutel geen cluster of space meer aanmaken, geen looptijd verlengen en geen cluster wijzigen. Wat al draait, blijft draaien en kost geld, tot iemand het verwijdert of de looptijd afloopt. De limiet stopt dus nieuwe uitgaven. Het is geen harde grens.

• De telling gebruikt de volle prijs, zonder gratis tegoed en zonder korting.
• De telling kan tot een uur achterlopen.
• De telling begint op de 1e van elke maand (UTC) opnieuw.
• De limiet ligt tussen 1 en 100.000 euro. Laat het veld leeg voor geen limiet.

De sleutel met kubectl gebruiken

De agent-kubeconfig werkt op gehoste clusters en op spaces. Een zelfgehost cluster heeft zijn eigen RBAC. De sleutel bereikt het alleen via de kubehz-API.

Je hebt lo nodig, de CLI van lok8s, op de machine waarop kubectl draait.

1. Open de pagina van het gehoste cluster of de space.
2. Klik op Agent-kubeconfig downloaden.
3. Sla het bestand op als agent.kubeconfig.
4. Stel de vier variabelen uit het blok Omgeving voor lo kubehz token in.
5. Start kubectl met het bestand.

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

Het bestand bevat geen secret. kubectl start lo kubehz token, dat met de sleutel een token ophaalt. lo bewaart het token tot vijf minuten voor het verloopt, zodat een kubectl-aanroep geen nieuwe aanmelding kost.

De sleutel met de API gebruiken

lo kubehz token --format token geeft alleen het token uit:

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

Zonder lo gebruik je de OAuth-client-credentials-grant:

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 toont de rol, het bereik en de vervaldatum van de sleutel, en zijn uitgaven deze maand met zijn limiet. Voor een sleutel met Gekozen clusters en spaces toont het ook de clusters en spaces die de sleutel bereikt.

Looptijd: wat een agent aanmaakt, eindigt vanzelf

Een space of een gehost cluster dat een agentsleutel aanmaakt, heeft altijd een looptijd. De looptijd is twee uur, of het aantal uren dat het aanmaken noemt (leaseHours, 1 tot 720). Als de looptijd afloopt, verwijdert kubehz de space of het cluster. Zo kan een agent die stopt of het vergeet, geen cluster achterlaten dat draait en geld kost.

• Om de looptijd te verlengen, stuurt de agent PATCH /api/spaces/{id}/lease of PATCH /api/clusters/{id}/lease met {"hours": 24}. Het nieuwe einde ligt 24 uur vanaf nu.
• Verleng de looptijd voor ze afloopt. Na het einde weigert kubehz elke wijziging, ook een verlenging (LEASE_ENDED). Je kunt de space of het cluster nog lezen of verwijderen. kubehz verwijdert het binnen enkele minuten.
• Een agentsleutel kan een looptijd niet verwijderen. Een persoon met de rol Owner of Admin kan dat wel. Voor een space klik je op de pagina op Looptijd verwijderen. Voor een gehost cluster stuur je {"hours": null} naar de API.
• Wie als persoon een looptijd instelt of het einde vervroegt, bevestigt met de tweede factor. Om een looptijd te verlengen of te verwijderen is geen tweede factor nodig.
• Een looptijd van meer dan zes uur krijgt één e-mail, ongeveer een uur voor het einde. De e-mail gaat naar de owner van de tenant. Om hem te stoppen, zet je in Instellingen → Meldingen de melding Looptijd loopt bijna af uit.
• Een zelfgehost cluster heeft nooit een looptijd. kubehz beëindigt niets wat op je eigen Hetzner-account draait.

Op de pagina van een space met een looptijd toont de kaart Looptijd het einde. Om een nieuw einde in te stellen, typ je de uren bij Uren vanaf nu en klik je daarna op Looptijd verlengen.

Wat een sleutel niet kan

• Agentsleutels of API-tokens aanmaken, leden beheren, of AI-apps aan- of uitzetten.
• Een looptijd verwijderen.
• Met de rol Lezer: een cluster of een space wijzigen.
• Met de rol Lezer of Bewerker: het auditlog of de facturatie lezen, of het Hetzner Cloud-token koppelen.
• Met Gekozen clusters en spaces: andere clusters en spaces zien, of gegevens van de hele tenant lezen, bijvoorbeeld de kosten.
• kubectl gebruiken op een zelfgehost cluster.

Een sleutel intrekken

1. Open Toegang → Agentsleutels.
2. Klik in de rij van de sleutel op Intrekken.
3. Klik in het dialoogvenster op Intrekken.

De kubehz-API weigert de sleutel direct. Ook de MCP-server weigert hem, omdat elke toolaanroep via de API gaat. Een token dat de agent al heeft, werkt op clusters en spaces tot het verloopt, hooguit 12 uur. Je kunt een intrekking niet ongedaan maken.

Een sleutel eindigt ook op zijn vervaldatum. De lijst waarschuwt 14 dagen voor het einde, en nog eens 3 dagen ervoor.