Get a kubeconfig

The portal hands out only temporary kubeconfigs, one per request, with the role and the lifetime you choose. pbx-agent makes each one on the node and encrypts it for your browser, so the portal passes it on without being able to read it, and stores none.

In progress: not bookable yet

Built in a lab: on 2026-10-10 a view kubeconfig took 10.7 seconds from the request to the decrypted file and an admin kubeconfig 21 seconds, on a real server; after a revoke, the same token was refused within 11 seconds. Tell me when it opens.

What you need

• A cluster that is ready, or in the middle of an upgrade or a restore. The kubeconfig is made on the node, so pbx-agent must be reporting.
• A browser with JavaScript. The key pair for the request is made in the browser tab.
• For admin: you are a team admin, or a team admin has allowed members to ask for it (below).

Get one

1. On the cluster’s page, open Access.
2. Choose a Role: admin (cluster-admin) or view (read only). The page starts at view. A view kubeconfig uses Kubernetes’ own view role, which cannot list nodes; take admin for anything that needs kubectl get nodes.
3. Choose how long it is Valid for: 10 minutes, 30 minutes, 1, 2, 4, 8, 12 or 24 hours. The default is 1 hour.
4. Choose Get kubeconfig. The request goes to pbx-agent at its next sync, about every 30 seconds.
5. When Download kubeconfig appears, save the file. It is named after the cluster’s DNS label and the role, such as upcheck-prod-admin.kubeconfig.

export KUBECONFIG=~/Downloads/upcheck-prod-admin.kubeconfig
kubectl get nodes

The kubeconfig points at the cluster’s API name on port 6443. Your address must be in the ranges the cluster’s firewall lets in; Change who can reach the API shows how to add it.

What happens underneath

• Your browser makes a key pair for this one request. The private half never leaves the browser tab.
• pbx-agent creates the ServiceAccount pbx-u-<user>-<role> in the namespace pbx-access, bound to cluster-admin or view, and asks Kubernetes for a token with the lifetime you chose.
• It builds the kubeconfig and encrypts it to your browser’s key (ECDH P-256, HKDF-SHA256, AES-256-GCM).
• The portal passes the encrypted file to your browser once and deletes it after delivery or after 5 minutes. A second fetch finds nothing. Your browser decrypts the file and offers it as a download; the decrypted file is never sent anywhere.

The kubeconfig carries a ServiceAccount token, not a client certificate. Kubernetes cannot revoke a certificate, but a token stops working the moment its ServiceAccount is deleted.

While the Kubernetes API is down, during an upgrade’s reboot or a restore, pbx-agent takes only restores and diagnostics. A kubeconfig request waits at the portal; if the API does not come back within 5 minutes, the request expires and you ask again.

Who may ask for which role

• Team admins may ask for admin and view.
• Other team members get view. A team admin can allow them to ask for admin too, under Access → Who may ask for admin access; that applies to every cluster of the team. Bring in your team has the other roles.

In progress Every request for a kubeconfig is mailed to the team’s admins, with who asked; the lab sent no mail. Issued kubeconfigs on the Access page lists who asked, for which role, when, when it was issued, until when it is valid, and whether it was revoked. In the cluster, every action taken with it shows up under the per-person ServiceAccount’s name.

Revoke

• Revoke mine deletes your ServiceAccounts in the cluster. Every kubeconfig issued to you stops working at once.
• A team admin can Revoke one person’s access in the list, or choose Revoke everyone’s.
• In progress Removing someone from the team revokes their access on every cluster of the team (Bring in your team).

A revoke is an operation like the others: pbx-agent deletes the ServiceAccounts at its next sync, and the page lists it under Revocations.

The admin file on the server

k3s writes a permanent admin kubeconfig on the server: /etc/rancher/k3s/k3s.yaml. It is yours, for emergencies, such as an API that the portal cannot issue kubeconfigs for, or a cluster you run without PaaSbox. The portal never reads, copies or stores it. It points at https://127.0.0.1:6443; to use it from your computer, change the server: line to the cluster’s API name. Reaching the file needs root on the server: Get root on the server.

That file does not expire. If it leaks, the only way to make it useless is to replace the cluster’s certificate authority, which k3s supports with k3s certificate rotate-ca. Keep it on the server.

For an agent

In progress An agent asks for a kubeconfig through the REST API or the MCP tools with an API key that has the scope k3s:access. The kubeconfig is sealed to a key pair your agent made, the same way it is sealed to your browser. Give an agent access.

Change who can reach the APILimit port 6443 to the addresses you work from.

Get root on the serverAdd an SSH key through the cluster, or use Hetzner's rescue system.