Accounts and recovery¶

What to do when someone is locked out of kubelatch, and when everyone is. Covers break-glass accounts and native cluster access for when kubelatch is down.

How people sign in¶

Switching modes doesn't touch accounts: each one is linked separately with its own linking link. Bots never sign in: they only have credentials (Users and bots).

Without GitHub there's no two-factor and no automatic offboarding: see Security model.

Account rules¶

• Passwords: 12 to 128 characters, different from the login, no composition rules. Stored with argon2id. Each person changes their own in Mi cuenta by giving the current one; that closes their other sessions. That change also allows 10 attempts per minute per account.
• Sessions: a signed cookie valid for 12 h. All sessions close instantly on signing out, on a password change, on using a reset or linking link, on unlinking GitHub, on disabling the account, or on pressing Cerrar sesiones (Close sessions).
• Lockout: 5 consecutive failures lock the account for 15 minutes (the fifth already responds 429). In addition, each IP (or each /64 on IPv6) gets 10 attempts per minute. Every attempt is logged in the control-plane audit log with the IP.
• Last admin: kubelatch won't let you remove the role, disable, unlink, or unmark as break-glass the last admin who can still sign in.

Break-glass accounts¶

A break-glass account keeps its password when GitHub is enabled. It's for signing in when GitHub is down or the App has been uninstalled. It can only be marked from the CLI. The commands use $MGMT_KUBECONFIG, the path to the management cluster's kubeconfig (see Install).

# mark an existing account
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch user set-break-glass <login>
# remove the mark
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch user set-break-glass <login> --off
# create a new break-glass account
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch user create rescate --admin --break-glass

Keep at least one, with its password in the organization's secrets manager. Don't use it day to day: it has no two-factor. In Usuarios (Users) it carries the emergencia (emergency) label, and it signs in from Cuenta de emergencia (contraseña) (Break-glass account (password)) on the login page. If you link it to GitHub and the person leaves the organization, it loses access like any other account.

When a person is locked out¶

When nobody can sign in¶

The binary's CLI is the rescue path. It runs with the same configuration as the server, applies pending migrations, and logs what it does in the control-plane audit log with no actor. Always use it with the management cluster's explicit kubeconfig.

1. New password for an existing admin. This also unlocks them, closes their sessions, and voids their pending links. It doesn't re-enable a disabled account.

   kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch user set-password admin
   

2. With GitHub enabled, that password only works if the account is a break-glass account. The CLI warns if it isn't. Mark it:

   kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch user set-break-glass admin
   

3. If the only admin is disabled, or there isn't one, create another and re-enable the first one from Usuarios:

   kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch user create rescate --admin --break-glass
   

Without a terminal (a runner, a script), use --password-stdin with kubectl exec -i. Exactly one trailing newline is stripped: a password that ends in a newline should be passed with two.

printf '%s' '<long password>' | kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -i deploy/kubelatch -- /kubelatch user set-password admin --password-stdin

With two replicas it doesn't matter which one runs it: the CLI talks directly to Postgres and there's no need to stop the server.

If the pod won't start (Postgres down, broken configuration), the problem isn't accounts. Check the logs and the pod's status:

kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch logs deploy/kubelatch
kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch describe pod

Native emergency access¶

kubelatch sits on the path of every request people make, but it is never the only way into a cluster, and workloads don't depend on it. Before going to production, set up and test native administrator access:

• Managed clusters: the cloud provider's identity (aws eks update-kubeconfig, gcloud container clusters get-credentials, az aks get-credentials) with the platform administrator role, in the organization's identity manager and with MFA.
• Self-managed: the administrator kubeconfig (kubeadm: /etc/kubernetes/admin.conf; k3s: /etc/rancher/k3s/k3s.yaml; Talos: talosctl kubeconfig) in a vault with audited access, or SSH to a control-plane node.

That access is for repairing kubelatch (for example, re-applying the bootstrap), acting when kubelatch is down, and doing what kubelatch doesn't allow: protected namespaces, nodes, --as. Its use is logged in the cluster's native audit log, not kubelatch's: review it with the same discipline.

When kubelatch is working, prefer a cluster-admin permission for at most 8 h, which does get audited: Grant permissions.

If the encryption key is lost¶

Without KUBELATCH_ENCRYPTION_KEY, everyone has to sign in again and every cluster's tokens have to be pasted back in. Passwords, klt_ credentials, permissions, and the audit log aren't affected. The procedure is in Upgrades and backups.