{"slug":"tailscale-on-kubernetes","title":"Tailscale on Kubernetes","tags":["tailscale","containers"],"agent_summary":"Last validated: Jan 5, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Tailscale on Kubernetes\r\n\r\nLast validated: Jan 5, 2026\r\n\r\nKubernetes is a popular method for deploying, scaling, and managing containerized applications. There are many ways you can use Tailscale with Kubernetes. Examples include for ingress to Kubernetes services, egress to a tailnet, and secure access to the cluster control plane (kube-apiserver). You can run Tailscale inside a Kubernetes Cluster using the [Tailscale Kubernetes Operator](https://tailscale.com/docs/kubernetes#use-the-kubernetes-operator), or as a sidecar, as a proxy, or as a subnet router. This doc shows several common ways.\r\n\r\nTailscale is available as a [Docker image](https://tailscale.com/docs/features/containers/docker).\r\n\r\n## [Prerequisites](https://tailscale.com/docs/kubernetes\\#prerequisites)\r\n\r\nYou can follow the examples in this doc by cloning from GitHub. For example:\r\n\r\n```shell\r\ngh repo clone tailscale/tailscale\r\ncd tailscale/docs/k8s\r\n```\r\n\r\n## [Setup](https://tailscale.com/docs/kubernetes\\#setup)\r\n\r\n1. (Optional) You can choose to use an [auth key](https://tailscale.com/docs/features/access-control/auth-keys) to automate your container logging in\r\nto your tailnet. Create an auth key in the [Keys](https://login.tailscale.com/admin/settings/keys) page of the admin console.\r\nWe recommend using an [ephemeral key](https://tailscale.com/docs/features/ephemeral-nodes) for this purpose, since it will\r\nautomatically clean up devices after they shut down. We also recommend using a\r\n[reusable key](https://tailscale.com/docs/features/access-control/auth-keys#types-of-auth-keys) so when containers are stopped and started they can still connect to\r\nyour tailnet.\r\n![Tailscale's auth key generation page](https://tailscale.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fephemeral-keys.cf911e46.png&w=750&q=75)\r\n\r\nThe **Pre-approved** option will only display in the dialog if [device approval](https://tailscale.com/docs/features/access-control/device-management/device-approval) is enabled in your Tailscale network.\r\n\r\nIf you don't provide the key, you can still authenticate by logging in at the URL provided in logs when using the container image below.\r\n\r\n```yaml\r\napiVersion: v1\r\nkind: Secret\r\nmetadata:\r\n name: tailscale-auth\r\nstringData:\r\n TS_AUTHKEY: tskey-0123456789abcdef\r\n```\r\n\r\n2. Tailscale (v1.16 or later) supports storing state inside a\r\n[Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret).\r\n\r\nConfigure role-based access control (RBAC) to allow the Tailscale pod to read/write the `tailscale` secret.\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nexport SA_NAME=tailscale\r\nexport TS_KUBE_SECRET=tailscale-auth\r\nmake rbac | kubectl apply -f-\r\n```\r\n\r\n\r\n## [Use the Kubernetes operator](https://tailscale.com/docs/kubernetes\\#use-the-kubernetes-operator)\r\n\r\nTailscale also provides the [Tailscale Kubernetes Operator](https://tailscale.com/docs/features/kubernetes-operator). The Kubernetes operator lets you:\r\n\r\n- Expose [services](https://kubernetes.io/docs/concepts/services-networking/service) in your Kubernetes cluster to your Tailscale network (known as a tailnet).\r\n- Securely connect to the [Kubernetes control plane (kube-apiserver)](https://kubernetes.io/docs/concepts/overview/components/#kube-apiserver) by using an API server proxy, with or without authentication.\r\n- Egress from a Kubernetes cluster to an external service in your tailnet.\r\n\r\n## [Sample sidecar](https://tailscale.com/docs/kubernetes\\#sample-sidecar)\r\n\r\nRunning as a sidecar lets you directly expose a Kubernetes pod over Tailscale. This is particularly useful if you do not wish to expose a service on the public internet. This method enables bi-directional connectivity between the pod and other devices in the tailnet. You can use [access control policies](https://tailscale.com/docs/features/access-control) to control traffic flow.\r\n\r\n1. Create and login to the sample nginx pod with a Tailscale sidecar:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nmake sidecar | kubectl apply -f-\r\n# If not using an auth key, authenticate by grabbing the Login URL here:\r\nkubectl logs nginx ts-sidecar\r\n```\r\n\r\n2. Check if you can connect to nginx over Tailscale:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\ncurl http://nginx\r\n```\r\n\r\n\r\n\r\nOr, if you have [MagicDNS](https://tailscale.com/docs/features/magicdns) disabled:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\ncurl \"http://$(tailscale ip -4 nginx)\"\r\n```\r\n\r\n\r\n## [Userspace sidecar](https://tailscale.com/docs/kubernetes\\#userspace-sidecar)\r\n\r\nYou can also run the sidecar in [userspace networking mode](https://tailscale.com/docs/concepts/userspace-networking). The obvious benefit is reducing the amount of permissions Tailscale needs to run. The downside is that for outbound connectivity from the pod to the tailnet you would need to use either the [SOCKS5 proxy or HTTP proxy](https://tailscale.com/docs/concepts/userspace-networking#socks5-vs-http).\r\n\r\n1. Create and login to the sample nginx pod with a Tailscale sidecar:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nmake userspace-sidecar | kubectl apply -f-\r\n# If not using an auth key, authenticate by grabbing the Login URL here:\r\nkubectl logs nginx ts-sidecar\r\n```\r\n\r\n2. Check if you can connect to nginx over Tailscale:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\ncurl http://nginx\r\n```\r\n\r\n\r\n\r\nOr, if you have [MagicDNS](https://tailscale.com/docs/features/magicdns) disabled:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\ncurl \"http://$(tailscale ip -4 nginx)\"\r\n```\r\n\r\n\r\n## [Sample proxy](https://tailscale.com/docs/kubernetes\\#sample-proxy)\r\n\r\nRunning a Tailscale proxy lets you provide inbound connectivity to a Kubernetes Service.\r\n\r\nVisit the [Kubernetes operator ingress](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-ingress) page for details on deploying an ingress proxy using the operator instead.\r\n\r\n1. Provide the `ClusterIP` of the service you want to reach by either:\r\n\r\n**Creating a new deployment**\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nkubectl create deployment nginx --image nginx\r\nkubectl expose deployment nginx --port 80\r\nexport TS_DEST_IP=\"$(kubectl get svc nginx -o=jsonpath='{.spec.clusterIP}')\"\r\n```\r\n\r\n\r\n\r\n**Using an existing service**\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nexport TS_DEST_IP=\"$(kubectl get svc -o=jsonpath='{.spec.clusterIP}')\"\r\n```\r\n\r\n2. Deploy the proxy pod:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nmake proxy | kubectl apply -f-\r\n# If not using an auth key, authenticate by grabbing the Login URL here:\r\nkubectl logs proxy\r\n```\r\n\r\n3. Check if you can connect to nginx over Tailscale:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\ncurl http://proxy\r\n```\r\n\r\n\r\n\r\nOr, if you have [MagicDNS](https://tailscale.com/docs/features/magicdns) disabled:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\ncurl \"http://$(tailscale ip -4 proxy)\"\r\n```\r\n\r\n\r\n## [Subnet router](https://tailscale.com/docs/kubernetes\\#subnet-router)\r\n\r\nRunning a Tailscale [subnet router](https://tailscale.com/docs/features/subnet-routers) lets you access the entire Kubernetes cluster network (assuming NetworkPolicies allow) over Tailscale.\r\n\r\nVisit the [Kubernetes operator subnet routers](https://tailscale.com/docs/features/kubernetes-operator/how-to/connector) page for details on deploying a subnet router using the operator instead.\r\n\r\n1. Identify the Pod/Service CIDRs that cover your Kubernetes cluster. These will vary depending on [which CNI](https://kubernetes.io/docs/concepts/cluster-administration/networking) you are using and on the Cloud Provider you are using. Add these to the `TS_ROUTES` variable as comma-separated values.\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nSERVICE_CIDR=10.20.0.0/16\r\nPOD_CIDR=10.42.0.0/15\r\nexport TS_ROUTES=$SERVICE_CIDR,$POD_CIDR\r\n```\r\n\r\n2. Deploy the subnet-router pod.\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nmake subnet-router | kubectl apply -f-\r\n# If not using an auth key, authenticate by grabbing the Login URL here:\r\nkubectl logs subnet-router\r\n```\r\n\r\n3. In the [Machines](https://login.tailscale.com/admin/machines) page of the admin console, ensure that the routes for the subnet-router are enabled.\r\n\r\n4. Make sure that any client you want to connect from has `--accept-routes` enabled.\r\n\r\n5. Check if you can connect to a `ClusterIP` or a `PodIP` over Tailscale:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\n# Get the Service IP\r\nINTERNAL_IP=\"$(kubectl get svc -o=jsonpath='{.spec.clusterIP}')\"\r\n# or, the Pod IP\r\n# INTERNAL_IP=\"$(kubectl get po -o=jsonpath='{.status.podIP}')\"\r\nINTERNAL_PORT=8080\r\ncurl http://$INTERNAL_IP:$INTERNAL_PORT\r\n```\r\n\r\n\r\n## [(Optional) Add DNS information](https://tailscale.com/docs/kubernetes\\#optional-add-dns-information)\r\n\r\nBy default, we do not set DNS for containers. To enable [MagicDNS](https://tailscale.com/docs/features/magicdns) for a Kubernetes container, you will need to export `TS_ACCEPT_DNS=true` in the environment.\r\n\r\n## [Remove ephemeral nodes from a tailnet](https://tailscale.com/docs/kubernetes\\#remove-ephemeral-nodes-from-a-tailnet)\r\n\r\nWhen an ephemeral node goes offline, it is automatically removed from your tailnet. You can also control ephemeral node removal using the [`tailscale logout`](https://tailscale.com/docs/reference/tailscale-cli#logout) command to either manually force the removal or incorporate the command into the [`tailscaled`](https://tailscale.com/docs/reference/tailscaled) Tailscale daemon. For more information, refer to [Ephemeral nodes](https://tailscale.com/docs/features/ephemeral-nodes#faq).\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

Tailscale on Kubernetes

\n

Last validated: Jan 5, 2026

\n

Kubernetes is a popular method for deploying, scaling, and managing containerized applications. There are many ways you can use Tailscale with Kubernetes. Examples include for ingress to Kubernetes services, egress to a tailnet, and secure access to the cluster control plane (kube-apiserver). You can run Tailscale inside a Kubernetes Cluster using the Tailscale Kubernetes Operator, or as a sidecar, as a proxy, or as a subnet router. This doc shows several common ways.

\n

Tailscale is available as a Docker image.

\n

Prerequisites

\n

You can follow the examples in this doc by cloning from GitHub. For example:

\n
gh repo clone tailscale/tailscale\r\ncd tailscale/docs/k8s\n
\n

Setup

\n
    \n
  1. (Optional) You can choose to use an auth key to automate your container logging in\r\nto your tailnet. Create an auth key in the Keys page of the admin console.\r\nWe recommend using an ephemeral key for this purpose, since it will\r\nautomatically clean up devices after they shut down. We also recommend using a\r\nreusable key so when containers are stopped and started they can still connect to\r\nyour tailnet.\r\n\"Tailscale's
    2. \n
\n

The Pre-approved option will only display in the dialog if device approval is enabled in your Tailscale network.

\n

If you don't provide the key, you can still authenticate by logging in at the URL provided in logs when using the container image below.

\n
apiVersion: v1\r\nkind: Secret\r\nmetadata:\r\n  name: tailscale-auth\r\nstringData:\r\n  TS_AUTHKEY: tskey-0123456789abcdef\n
\n
    \n
  1. Tailscale (v1.16 or later) supports storing state inside a\r\nKubernetes Secret.
    2. \n
\n

Configure role-based access control (RBAC) to allow the Tailscale pod to read/write the tailscale secret.

\n
export SA_NAME=tailscale\r\nexport TS_KUBE_SECRET=tailscale-auth\r\nmake rbac | kubectl apply -f-\n
\n

Use the Kubernetes operator

\n

Tailscale also provides the Tailscale Kubernetes Operator. The Kubernetes operator lets you:

\n
    \n
  • Expose services in your Kubernetes cluster to your Tailscale network (known as a tailnet).
    • \n
  • Securely connect to the Kubernetes control plane (kube-apiserver) by using an API server proxy, with or without authentication.
    • \n
  • Egress from a Kubernetes cluster to an external service in your tailnet.
    • \n
\n

Sample sidecar

\n

Running as a sidecar lets you directly expose a Kubernetes pod over Tailscale. This is particularly useful if you do not wish to expose a service on the public internet. This method enables bi-directional connectivity between the pod and other devices in the tailnet. You can use access control policies to control traffic flow.

\n
    \n
  1. Create and login to the sample nginx pod with a Tailscale sidecar:
    2. \n
\n
make sidecar | kubectl apply -f-\r\n# If not using an auth key, authenticate by grabbing the Login URL here:\r\nkubectl logs nginx ts-sidecar\n
\n
    \n
  1. Check if you can connect to nginx over Tailscale:
    2. \n
\n
curl http://nginx\n
\n

Or, if you have MagicDNS disabled:

\n
curl \"http://$(tailscale ip -4 nginx)\"\n
\n

Userspace sidecar

\n

You can also run the sidecar in userspace networking mode. The obvious benefit is reducing the amount of permissions Tailscale needs to run. The downside is that for outbound connectivity from the pod to the tailnet you would need to use either the SOCKS5 proxy or HTTP proxy.

\n
    \n
  1. Create and login to the sample nginx pod with a Tailscale sidecar:
    2. \n
\n
make userspace-sidecar | kubectl apply -f-\r\n# If not using an auth key, authenticate by grabbing the Login URL here:\r\nkubectl logs nginx ts-sidecar\n
\n
    \n
  1. Check if you can connect to nginx over Tailscale:
    2. \n
\n
curl http://nginx\n
\n

Or, if you have MagicDNS disabled:

\n
curl \"http://$(tailscale ip -4 nginx)\"\n
\n

Sample proxy

\n

Running a Tailscale proxy lets you provide inbound connectivity to a Kubernetes Service.

\n

Visit the Kubernetes operator ingress page for details on deploying an ingress proxy using the operator instead.

\n
    \n
  1. Provide the ClusterIP of the service you want to reach by either:
    2. \n
\n

Creating a new deployment

\n
kubectl create deployment nginx --image nginx\r\nkubectl expose deployment nginx --port 80\r\nexport TS_DEST_IP=\"$(kubectl get svc nginx -o=jsonpath='{.spec.clusterIP}')\"\n
\n

Using an existing service

\n
export TS_DEST_IP=\"$(kubectl get svc <SVC_NAME> -o=jsonpath='{.spec.clusterIP}')\"\n
\n
    \n
  1. Deploy the proxy pod:
    2. \n
\n
make proxy | kubectl apply -f-\r\n# If not using an auth key, authenticate by grabbing the Login URL here:\r\nkubectl logs proxy\n
\n
    \n
  1. Check if you can connect to nginx over Tailscale:
    2. \n
\n
curl http://proxy\n
\n

Or, if you have MagicDNS disabled:

\n
curl \"http://$(tailscale ip -4 proxy)\"\n
\n

Subnet router

\n

Running a Tailscale subnet router lets you access the entire Kubernetes cluster network (assuming NetworkPolicies allow) over Tailscale.

\n

Visit the Kubernetes operator subnet routers page for details on deploying a subnet router using the operator instead.

\n
    \n
  1. Identify the Pod/Service CIDRs that cover your Kubernetes cluster. These will vary depending on which CNI you are using and on the Cloud Provider you are using. Add these to the TS_ROUTES variable as comma-separated values.
    2. \n
\n
SERVICE_CIDR=10.20.0.0/16\r\nPOD_CIDR=10.42.0.0/15\r\nexport TS_ROUTES=$SERVICE_CIDR,$POD_CIDR\n
\n
    \n
  1. Deploy the subnet-router pod.
    2. \n
\n
make subnet-router | kubectl apply -f-\r\n# If not using an auth key, authenticate by grabbing the Login URL here:\r\nkubectl logs subnet-router\n
\n
    \n
  1. \n

    In the Machines page of the admin console, ensure that the routes for the subnet-router are enabled.

    \n
    2. \n
  2. \n

    Make sure that any client you want to connect from has --accept-routes enabled.

    \n
    3. \n
  3. \n

    Check if you can connect to a ClusterIP or a PodIP over Tailscale:

    \n
    4. \n
\n
# Get the Service IP\r\nINTERNAL_IP=\"$(kubectl get svc <SVC_NAME> -o=jsonpath='{.spec.clusterIP}')\"\r\n# or, the Pod IP\r\n# INTERNAL_IP=\"$(kubectl get po <POD_NAME> -o=jsonpath='{.status.podIP}')\"\r\nINTERNAL_PORT=8080\r\ncurl http://$INTERNAL_IP:$INTERNAL_PORT\n
\n

(Optional) Add DNS information

\n

By default, we do not set DNS for containers. To enable MagicDNS for a Kubernetes container, you will need to export TS_ACCEPT_DNS=true in the environment.

\n

Remove ephemeral nodes from a tailnet

\n

When an ephemeral node goes offline, it is automatically removed from your tailnet. You can also control ephemeral node removal using the tailscale logout command to either manually force the removal or incorporate the command into the tailscaled Tailscale daemon. For more information, refer to Ephemeral nodes.

\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}