Sign in and request access¶

How you sign in to kubelatch, what to ask an administrator for before you can work, and where to see the permissions you already have.

Before you start¶

You need an account. Ask for one from the team that administers kubelatch at your company (usually platform): they'll give you the URL and an invitation link, which you may not even need if you sign in with your company account: your first sign-in may create the account, or let you ask for one (Your first sign-in with your company account).

The link grants direct access, so it must reach you over a secure channel, not open email or a public chat.

The first time: the invitation link¶

The link has the form <kubelatch-url>/account-link#kli_.... Open it and you'll see Welcome, Nuria (with your own name) and three facts to check: your Login, Signs in with (the ways open to your account: your company's provider, GitHub or Password) and Valid until, with the reminder that it works only once.

1. If your kubelatch signs in with your company's identity provider, there's a Link with {name} and sign in button, where {name} is the name your administrators gave the provider (Google, Microsoft, Okta…). You sign in there, and that identity gets linked to your kubelatch account.
2. If it signs in with GitHub, there's a Link with GitHub and sign in button. You authorize the App and your GitHub account gets linked to your kubelatch account. With both, the page shows both buttons: either will do.
3. If your account can use a password, there's a form to set it, with a Password requirements list that ticks itself as you meet each one: at least 12 characters, not your login, and both fields match. Save and sign in waits until all three are met, and saving the password signs you in.

The invitation link expires after 72 hours and only works once. If you already used it or it expired, you'll see Link expired or already used: ask for a new one. The page removes the token from the address bar as soon as it loads, so reloading it shows The link arrived incomplete: open the link again from the message you received. A reset link (after forgetting your password) expires after 24 hours, and its page is titled Reset password.

The next times: how you sign in¶

How you sign in depends on how your kubelatch is set up:

• With your company account: if your kubelatch has your company's identity provider configured, the login screen offers Sign in with {name}. You sign in on the provider's page, usually with the session you already have open there, and come back signed in. Only addresses in your company's e-mail domains get in, with whatever two-factor the provider asks for.
• With GitHub: if your organization has a GitHub App configured, the login screen offers Sign in with GitHub, under Sign in with {name} when both are on. Only active members of that organization can sign in, with whatever two-factor requirement the organization itself enforces.
• With login and password: if neither is configured, you see a form with Login and Password, and the Sign in button.

With your company account or GitHub, Sign in with a password, at the foot of the page, opens a step of its own for the accounts an administrator allowed a password (break-glass accounts). Back to {name} sign-in, Back to GitHub sign-in or Back to {name} or GitHub sign-in, depending on what your kubelatch offers, returns from it.

If the login page says Could not load the sign-in methods. Reload the page., do that.

Five wrong passwords in a row lock the account for 15 minutes. Wait, or ask an administrator to set you a new password. If you forgot it, there's no self-service reset: ask an administrator for a reset link.

The sign-in page has a language selector in its top right corner: see Interface language.

Your first sign-in with your company account¶

The first time you use Sign in with {name}, kubelatch looks for the account with the e-mail address your provider vouches for and links the two: there's no link to open. From then on, that identity is how you get in. Your administrators can limit this or turn it off: if kubelatch doesn't find the account they created for you, use the invitation link.

If no account has your address, one of two things happens:

• Your company's domain has a rule. kubelatch creates your account there and then, puts you in a group, and you land in Home with that group's permissions. Your login is the part of your address before the @, in lower case.
• It hasn't. You land on Ask to join, which shows the address you signed in with. Write a Reason if you like (it's optional) and click Send request. The page then says Request pending, with the date it expires if nobody decides, 30 days later. Once an administrator approves it, sign in again and you're in. If they deny it, the page says Request denied, with who to ask if you think it's a mistake; you can ask again.

To see how your request stands, sign in again with Sign in with {name}. If the page adds "kubelatch is at its limit of people; an administrator will have to free a seat or extend the edition.", you can still send the request: it waits until there's a seat.

If kubelatch can't sign you in at all, the login page says why. The usual case is "That {name} account isn't in a domain this kubelatch accepts. Did you pick a personal account?": you probably chose your personal account in the provider's account picker. Try another account takes you back to that picker; Ask to join has it too, in case you signed in with the wrong account. Every other message, with what to do about it, is in Errors.

Your first steps in Home¶

Until you hold a permission and have made your first request, Home shows the card Your connection with three steps to your first kubectl, each ticked once it's done:

1. Install the CLI and sign in, marked Recommended until it's done: the login command to copy, Download kubelatch, and "No browser? Add --device." (The CLI). It's done once you've signed in with the CLI, even if that session has expired since; it then says when, and from which computer.
2. Have a permission: done while you hold an active one, which it names, with its group when it comes from one. With none, in Pro it offers Ask for access, which opens the request form, with "The form tells you who decides." (Ask for access); in Free it says whom to ask: the contact your administrators set up or, without one, the oldest administrator. An administrator sees Grant it to yourself in Permissions instead.
3. Try kubectl: with a permission, a command to copy through the context of its cluster, kubectl --context kubelatch-<cluster> get pods -n <namespace> for the namespace of your first permission or kubectl --context kubelatch-<cluster> get nodes when it covers the whole cluster, and "You will see it in Recent activity.". It's done once a request of yours has gone through kubelatch.

Once you hold a permission and a request of yours has gone through, the card goes away, even if you work with a downloaded kubeconfig and never signed in with the CLI. From then on, the line under the title of Home says how you work:

• With a CLI session: Connected from alice-laptop, until when the session lasts, with Sign out and Connect an agent.
• Without one, with a credential: Working with "work laptop", your last request, and CLI not signed in — Sign in with the CLI. That link opens the login command, Download kubelatch and Connect an agent.
• With neither, say because your session ended and your credential is new: CLI not signed in — Sign in with the CLI alone.

What to ask an administrator for¶

Signing in isn't enough: without permissions you can't issue a useful credential. Tell your administrator exactly:

• Which cluster you need.
• Which tier:
  • viewer: read-only.
  • developer: also creates and modifies workloads.
  • debugger: an add-on to the above: exec, attach, port-forward and ephemeral containers.
  • secrets-reader: an add-on: reads secrets.
  • admin: everything within the namespace, including roles and bindings.
  • cluster-admin: the whole cluster, at most 8 h, only for emergencies.
• Which scope: a specific namespace, or the whole cluster if the tier allows it.

For example: "I need developer and debugger in the apps namespace of the prod cluster." The detail of each tier is in System roles.

The administrator grants the permission from Permissions (full guide). You can't grant it to yourself. In Pro you ask for it from kubelatch itself, with the cluster, the role, where and for how long already chosen: Ask for access.

See your access¶

Sign in and go to Home. What ends in the next seven days comes first, day by day, in Your week (Your week). Under it, My clusters has a row per cluster where you hold a permission, with how many clusters and permissions you hold beside its title:

• The clusters where something ends within the week come first, open, the nearest end on top. A line, the rest, A to Z, separates them from the others, which arrive folded. With a single cluster, it's open.
• Each row gives the cluster's id and name, your strongest role there and where (with "+2" when you hold more), and when the nearest of those permissions ends. Click the row to fold or unfold it.
• Beside it, the context to copy (kubelatch-<cluster>), New kubeconfig…, which issues a credential for that cluster alone (Get a credential), and in Pro Ask for more, which opens the request form on that cluster (Ask for access).
• Unfolded, one line per permission: the role, where (the namespace's name, or whole cluster), until when, and why: direct, by request (a link to the request it came from, with who approved it), or via and the group you're a member of, for example via Backend. Copy command at the end of the line copies a command that tries it, kubectl --context kubelatch-<cluster> get pods -n <namespace>, or get nodes for the whole cluster. In Pro, a permission with an end also offers Ask for an extension, or Ask for more when it comes from a group or a set (Extensions).
• From 8 clusters, Filter clusters… finds one by its id or its name.

Click the role to see what it allows and the Kubernetes group the cluster recognizes you by (see Check your identity). A permission that doesn't expire says Never. One through a group lasts as long as your membership and the group's permission both do. On a phone each line takes two rows.

A permission on a namespace doesn't cover -A (--all-namespaces): kubectl get pods -A gets 403, while kubectl get pods -n <namespace> works. If My clusters says You have no active permission., you don't have permissions yet: you won't be able to issue a credential until an administrator grants you at least one. That card then comes before the steps and the login command. Ask for access there opens the request form in Pro; in Free it leads to the contact your administrators have set up, and if they set none, it tells you to ask an administrator.

If you use AI agents, the approvals waiting for your decision show on Home too, in Pending, above Your week, with Review (AI agents).

With at least one active permission, continue to Get a credential.