Remote shell over Tailscale (beta)

Coming soon: beta by waitlist

Coming soon: the remote shell over Tailscale is under development and will open first as a closed beta, through a waitlist. This page describes how it will work and may change before release. Today, for a shell, use the pod and node shell and the Bastion.

• Feature page and waitlist
• Pod and node shell
• Bastion

How it works

• In the cluster: the kubepier-shell Deployment (1 replica) in the kubepier-shell namespace, with Tailscale in userspace mode and Tailscale SSH on. No privileges, no hostNetwork, PodSecurity restricted profile.
• In your tailnet: the pod shows up as a tagged machine (tag:kubepier-shell), named kp-<client>-<cluster> in MagicDNS.
• On your device: the Tailscale app connected to the same tailnet and an SSH client. There is no SSH key: Tailscale SSH authenticates by Tailscale identity and the ACL.
• Kubepier installs, shows the status (online, version, RBAC profile), generates the connection commands and revokes. It does not sit in the middle of the SSH session.

Before you start

• An organization on Pro or Team, with you as an admin.
• A Tailscale tailnet of your own and admin access to the Tailscale admin console. On the Personal (free) plan, Tailscale SSH covers up to 5 hosts (5 clusters with the shell).
• The cluster must reach the internet on port 443 (Tailscale coordination servers and DERP relays). If egress goes through a firewall, allow the Tailscale domains; UDP 41641 is optional and lowers latency.
• The cluster credential in Kubepier must be able to create a namespace, Deployment, Secret, ServiceAccount, Role and RoleBinding (or ClusterRoleBinding, depending on the RBAC profile). Without it, the wizard offers the YAML for you to apply with kubectl.

1. Prepare your tailnet

In the Tailscale admin console, under Access controls, add the tag, the group of people who may connect, and the network and SSH rules. Example:

{
  "tagOwners": {
    // Only your tailnet admins can create machines with this tag.
    "tag:kubepier-shell": ["autogroup:admin"]
  },
  "groups": {
    // Who can open the shell (emails in YOUR tailnet).
    "group:kubepier-shell": ["you@yourcompany.com"]
  },
  "grants": [
    // Only port 22 (Tailscale SSH) on the pod, only for the group.
    { "src": ["group:kubepier-shell"], "dst": ["tag:kubepier-shell"], "ip": ["tcp:22"] }
  ],
  "ssh": [
    {
      // "check" asks for a fresh Tailscale login every 12 hours.
      "action": "check",
      "checkPeriod": "12h",
      "src": ["group:kubepier-shell"],
      "dst": ["tag:kubepier-shell"],
      "users": ["kubepier"]
    }
  ]
}

With "check", Tailscale asks for a fresh browser login once the checkPeriod passes. Use "accept" to skip that. The "kubepier" user is the non-root user inside the pod.

Then, under Settings › Keys, generate a one-off (non-reusable), pre-approved auth key tagged tag:kubepier-shell, with a short expiry (1 day is enough). In the next beta phase, Kubepier will be able to mint this key itself with an OAuth client from your tailnet.

2. Install it in the cluster from Kubepier

• Open Shell in the side menu (web or desktop) and pick the cluster.
• Paste the auth key. It goes straight into a Secret in your cluster and is not stored by Kubepier.
• Pick the RBAC profile: read-only (view), operations in chosen namespaces, cluster admin, or no API access (network only). Cluster admin asks you to type the cluster name to confirm.
• Review the summary (namespace, image, profile, tailnet name) and click Install. The screen shows each step until the machine is online in your tailnet.
• If Kubepier cannot apply it, or the web cannot reach the cluster: use Download YAML and apply it with kubectl apply -f.

3a. Connect from an iPhone or iPad (iOS)

• Install the Tailscale app from the App Store and sign in to your tailnet. Allow the Tailscale VPN when iOS asks.
• Install an SSH client: Termius, Blink Shell or another of your choice.
• Create a host with the address kp-<client>-<cluster>.<your-tailnet>.ts.net (or the 100.x IP shown in the Tailscale app), port 22, user kubepier, no password and no key.
• Connect. If the rule is "check" and your login has expired, the terminal shows a link: open it, sign in to Tailscale and the session continues.
• On the Kubepier Shell screen, Connect from phone will show a QR code with this address so you do not have to type it.
• Alternative without an SSH client: the SSH console in the Tailscale admin console (Machines › SSH to machine), in beta and for tailnet admins only.

3b. Connect from Android

• Install the Tailscale app from Google Play and sign in to your tailnet. Accept the Tailscale VPN.
• Install an SSH client: Termius, JuiceSSH or ConnectBot.
• Create the connection to kubepier@kp-<client>-<cluster>.<your-tailnet>.ts.net, port 22, no password and no key.
• Connect. With a "check" rule, open the login link shown in the terminal.
• If the name does not resolve, turn on MagicDNS in the Tailscale admin console (DNS) or use the machine's 100.x IP.

3c. Connect from Linux

# Install Tailscale (Debian, Ubuntu, Fedora, RHEL, Arch...)
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# Find the Kubepier pod in your tailnet
tailscale status | grep kubepier

# Open the shell (the name is shown on the Kubepier Shell screen)
tailscale ssh kubepier@kp-<client>-<cluster>

# or with the system ssh, by MagicDNS name
ssh kubepier@kp-<client>-<cluster>.<your-tailnet>.ts.net

tailscale ssh uses the system ssh underneath and needs no key. The Kubepier Desktop Shell screen has an Open in terminal button that runs the same command.

3d. Connect from macOS

# With the Tailscale app open and connected (menu bar):
ssh kubepier@kp-<client>-<cluster>.<your-tailnet>.ts.net

# Standalone build or Homebrew CLI only (not the App Store build):
tailscale ssh kubepier@kp-<client>-<cluster>

• Install Tailscale (App Store or the standalone package from the Tailscale site) and connect from the menu bar.
• Open Terminal and use the system ssh. The tailscale ssh command only exists in the standalone build or the open-source CLI (Homebrew); with the App Store build, use ssh.

3e. Connect from Windows

# PowerShell or Windows Terminal, with Tailscale connected (tray icon)
ssh kubepier@kp-<client>-<cluster>.<your-tailnet>.ts.net

# or with the Tailscale CLI
tailscale ssh kubepier@kp-<client>-<cluster>

# The OpenSSH client ships with Windows 10 and 11. If ssh is missing:
# Settings › System › Optional features › OpenSSH Client

• Install Tailscale for Windows, sign in to your tailnet and check the connected tray icon.
• Open PowerShell or Windows Terminal:

PuTTY, Termius or the Kubepier Desktop terminal also work with the same address, user kubepier and no key.

3f. Connect from the browser (optional)

• On Kubepier Web, the Shell screen's Open in browser button opens a terminal in the same pod through the Kubernetes API, without going through Tailscale.
• Same rules as today's pod shell: admins only, counts toward the 3 terminals per person, up to 2 hours per session, audited.

4. Use the shell

# Inside the shell (the RBAC profile chosen at install time)
kubectl get pods -A
kubectl -n <namespace> logs deploy/<app> --tail=100
kubectl -n <namespace> rollout restart deploy/<app>
k9s

# Cluster network, as in the Bastion
nc -vz db.internal 5432
curl -v http://service.internal:8080/health

What kubectl can do depends on the RBAC profile chosen at install time. To change it, use Change profile on the Shell screen.

5. Revoke and uninstall

• Remove one person's access: take them out of the group in your tailnet ACL. It applies immediately to new connections.
• Remove everyone's access to a cluster: Revoke on the Shell screen. Kubepier deletes the Deployment and the Secrets; remove the machine under Machines in the Tailscale admin console (in the OAuth client phase, Kubepier removes it for you).
• Uninstall deletes the kubepier-shell namespace and the RBAC bindings the wizard created, after you type the cluster name.
• Emergency: kubectl delete namespace kubepier-shell turns everything off, even without Kubepier.

Security

• No public ports: the pod only opens outbound connections to Tailscale.
• The auth key is yours, one-off and tagged; after the first login the pod keeps its state in a Secret in the namespace and the key is no longer usable.
• Your tailnet ACL decides who gets in; Kubepier does not create users in your Tailscale.
• Session recording: Kubepier does not record what is typed. Tailscale's own session recording (tsrecorder) is no longer offered to new users; if your company requires recording, tell us when you join the waitlist.
• Kubepier audit: install, profile change, revoke, uninstall and open in browser, with who, when, cluster and profile.

Planned limits

Beta numbers, subject to change before release.

Common errors (expected)

• The pod does not show up in the tailnet: the auth key expired, was already used or has no tag; generate another one and use Replace key.
• "tailnet policy does not permit you to SSH": your user is missing from the ssh rule group, or the kubepier user is missing from "users".
• The name does not resolve on the phone: turn on MagicDNS or use the 100.x IP.
• Slow connection: without outbound UDP, traffic goes through Tailscale DERP relays; allow UDP 41641 if you can.
• Forbidden in kubectl: the chosen RBAC profile does not grant that verb; change the profile.