Set up the Kubernetes API server over Tailscale

This topic describes how to set up the Tailscale API server proxy in auth mode. In this mode, the proxy impersonates the caller's Tailscale identity when forwarding requests to the Kubernetes API server. This lets you use standard Kubernetes RBAC. For details on how impersonation works, refer to Configure authentication and authorization.

Prerequisites

Before you begin, complete the following:

• Install the Tailscale Kubernetes Operator.
• Enable HTTPS for your tailnet.
• Ensure your access control policies permit devices to access the proxy on port 443 over TCP.

For example, if your operator uses tag:k8s-operator, permit access for devices tagged with tag:engineering:

"grants": [
  {
    "src": ["tag:engineering"],
    "dst": ["tag:k8s-operator"],
    "ip": ["tcp:443"]
  }
]

Deploy a high-availability proxy with ProxyGroup

For production, deploy the API server proxy as a dedicated ProxyGroup. This separates the proxy lifecycle from the operator and provides multiple replicas.

Enable impersonation RBAC

The ProxyGroup pods need Kubernetes RBAC permissions to impersonate users and groups when proxying requests. If you haven't already enabled the in-process proxy, set allowImpersonation to provision the required RBAC:

helm upgrade tailscale-operator tailscale/tailscale-operator \
  --namespace=tailscale \
  --set-string apiServerProxyConfig.allowImpersonation="true" \
  --reuse-values

Configure access control

Ensure your access control policies permit access on both port 80 and 443:

"grants": [
  {
    "src": ["tag:engineering"],
    "dst": ["tag:k8s"],
    "ip": ["tcp:80", "tcp:443"]
  }
]

Configure auto-approvers to let the ProxyGroup advertise Tailscale Services:

"autoApprovers": {
  "services": {
    "svc:*": ["tag:k8s"]
  }
}

Create the ProxyGroup

Create a ProxyGroup resource with spec.type: kube-apiserver:

apiVersion: tailscale.com/v1alpha1
kind: ProxyGroup
metadata:
  name: my-cluster
spec:
  type: kube-apiserver
  replicas: 2
  kubeAPIServer:
    mode: auth

Wait for the ProxyGroup to become ready:

kubectl wait proxygroup my-cluster --for=condition=ProxyGroupReady=true

Configure kubeconfig

After the ProxyGroup is ready, get the proxy URL from the ProxyGroup status:

kubectl get proxygroup my-cluster

NAME         STATUS            URL                                 TYPE             AGE
my-cluster   ProxyGroupReady   https://my-cluster.tailxyz.ts.net   kube-apiserver   31s

Use the Tailscale CLI to configure kubectl to connect through the proxy:

tailscale configure kubeconfig https://my-cluster.tailxyz.ts.net

The hostname defaults to the ProxyGroup name, but you can customize it using spec.kubeAPIServer.hostname.

Configure Kubernetes RBAC

The proxy impersonates the caller's Tailscale identity, but Kubernetes won't grant any permissions by default. You need to create Kubernetes RBAC bindings to grant access.

For example, to grant your Tailscale user read-only access to the cluster:

kubectl create clusterrolebinding my-user-view \
  --user="alice@example.com" \
  --clusterrole=view

Or to grant all devices tagged with tag:engineering read-only access:

kubectl create clusterrolebinding engineering-view \
  --group="tag:engineering" \
  --clusterrole=view

For more advanced configurations using grants and group impersonation, refer to Configure authentication and authorization.

Further exploration

• Configure authentication and authorization for API server access.
• Run the API server proxy in noauth mode to bypass authentication.
• Record kubectl sessions for auditing and compliance.