CLI¶

All the subcommands and flags of the kubelatch binary. The same binary is the server and the account-rescue tool.

kubelatch [serve]
kubelatch user create <login> [--admin] [--break-glass] [--display-name <name>] [--password-stdin]
kubelatch user set-password <login> [--password-stdin]
kubelatch user set-break-glass <login> [--off]
kubelatch version
kubelatch help

How it runs¶

The user subcommands read the same environment variables as the server, with the same rules: they need at least DATABASE_URL, KUBELATCH_BASE_URL and KUBELATCH_ENCRYPTION_KEY. They apply pending migrations, go straight to Postgres, and record the action in control_events with no actor. There's no need to stop the server, and it doesn't matter which replica they run on.

They never talk to GitHub. They validate the GITHUB_* variables like the server (an incomplete block also fails them), but only use their presence, to know whether GitHub login is active.

On Kubernetes, run them inside the pod, always with the management cluster's explicit kubeconfig. The image has no shell: the binary is at /kubelatch.

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

Flags go after the login.

kubelatch and kubelatch serve¶

Starts the server: control plane, proxy, reconciler and background jobs. With no arguments it does the same. It takes no flags: everything is configured with environment variables.

kubelatch serve

Writes JSON logs to standard output. Exits with code 1 if the configuration is invalid or it fails to start. On SIGTERM or Ctrl-C it stops accepting connections, gives in-flight requests 3 s, cuts open streams, and exits within 30 s at most.

kubelatch user create¶

Creates a person with a password. It's how you create the first administrator.

The login accepts only lowercase letters, digits, ., _ and -, 1 to 63 characters. A login is never reused, even if the previous account is disabled. The password must be 12 to 128 characters and different from the login.

kubelatch user create admin --admin
kubelatch user create rescate --admin --break-glass --display-name "Cuenta de rescate"

Output:

user admin created (id 0192…, admin=true, break_glass=false)

With GitHub active and a non-break-glass account, it adds a warning: that password won't work to sign in.

kubelatch user set-password¶

Sets a new password for an existing person. It also unlocks the account, revokes its pending links, and closes all its sessions. It's the rescue path when nobody can sign in.

kubelatch user set-password admin

Output:

password set for admin; account unlocked and sessions closed

With GitHub active, the password only works if the account is break-glass. If it isn't, the command warns about it and suggests kubelatch user set-break-glass.

kubelatch user set-break-glass¶

Marks an existing person as a break-glass account, or unmarks them. It's the only way to do it: neither the interface nor the API can.

kubelatch user set-break-glass admin
kubelatch user set-break-glass admin --off

Output:

break_glass=true for admin

kubelatch refuses to unmark the last administrator who can sign in.

kubelatch version¶

Prints the version the image was built with (dev on a local binary).

kubelatch version

kubelatch help¶

Prints the usage summary. Also responds to -h and --help.

Passwords via standard input¶

Without --password-stdin, the command asks for the password twice through the terminal, without echo. If standard input is not a terminal, it fails and asks you to use --password-stdin.

With --password-stdin, everything that arrives on standard input is the password, minus one trailing newline (\n or \r\n). So echo and printf '%s\n' work as is. A password that ends in a newline is passed with two.

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

Exit codes and errors¶

Common error messages: