Join us live on August 26 in San Francisco for TailscaleUpTICKETS ON SALE NOW ->

Access the Kubernetes API server over Tailscale

Last validated:

The API server proxy lets you securely access your Kubernetes API server over your tailnet without exposing it to the public internet. It sits between tailnet clients and the Kubernetes API server, forwarding authenticated requests.

The API server proxy supports two authentication modes and can run either in-process within the operator or as a dedicated ProxyGroup.

Session recording: You can record kubectl exec, attach, and debug sessions executed through the API server proxy for audit and compliance. Refer to Record kubectl sessions.

Looking to connect? If the API server proxy is already configured, use tailscale configure kubeconfig <proxy-hostname> to set up kubectl access. You can find the proxy's MagicDNS name in the Machines page of the admin console or ask your cluster administrator. Refer to the setup topic for details.

For information about the set up steps, refer to Set up the Kubernetes API server over Tailscale.

Auth mode (default)

In auth mode, the proxy authenticates incoming requests based on the source Tailscale identity and impersonates that identity when forwarding the request to the Kubernetes API server. This lets you use standard Kubernetes RBAC.

How the proxy determines the Kubernetes identity:

  • User devices: The request is impersonated as the Tailscale user (for example, alice@example.com). If grants define additional Kubernetes groups, those are added as impersonation groups.
  • Tagged devices: The request is impersonated as a user with the node's FQDN, with the node's tags as Kubernetes groups. If grants define additional groups, those take precedence over the tag-based groups.

noauth mode

In noauth mode, the proxy forwards requests to the API server without adding authentication information. This is useful if you use Tailscale only for connectivity and handle authentication through another mechanism.

Use the API server proxy without Tailscale authentication

Use the API server proxy for connectivity only, with external authentication.

In-process proxy

To get started, run the API server proxy in-process within the operator pod. Enable it by setting apiServerProxyConfig.mode when installing the operator with Helm:

helm upgrade --install tailscale-operator tailscale/tailscale-operator \
  --namespace=tailscale \
  --create-namespace \
  --set-string apiServerProxyConfig.mode="true" \
  --wait

The client connects to the operator's tailnet address, and the operator proxies the request to the kube-apiserver.

A diagram showing the in-process API server proxy architecture. A client connects to the operator over the tailnet, and the operator proxies the request to the kube-apiserver inside the Kubernetes cluster.

This configuration means the proxy shares a lifecycle with the operator pod and is limited to a single replica.

Dedicated proxy (ProxyGroup)

For production environments, you can deploy the API server proxy as a dedicated ProxyGroup with spec.type: kube-apiserver. This separates the proxy lifecycle from the operator and provides high availability through multiple replicas.

A diagram showing the dedicated API server proxy architecture. A ProxyGroup StatefulSet with multiple replicas proxies requests from tailnet clients to the kube-apiserver, separate from the operator pod.

The dedicated proxy requires:

  • Impersonation RBAC: The Helm value apiServerProxyConfig.allowImpersonation must be set to provision the Kubernetes RBAC needed for the ProxyGroup pods to impersonate users.
  • Auto-approvers: Your ACL policy must permit the ProxyGroup's tag to advertise Tailscale Services.

Refer to the Set up the Kubernetes API server over Tailscale for full setup instructions, and High availability for the Tailscale Kubernetes Operator for general ProxyGroup configuration.

Limitations

The API server proxy has the following limitations:

  • In-cluster dependency: The proxy runs inside the cluster. If the cluster cannot schedule pods, you may lose access to the API.
  • TLS latency: In-process proxies provision certificates on the first request, which may cause an initial timeout. ProxyGroup deployments avoid this by provisioning certificates before becoming ready.

Further exploration