{"slug":"kubernetes-operator","title":"Kubernetes operator","tags":["tailscale","containers"],"agent_summary":"Last validated: Jan 5, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Kubernetes operator\r\n\r\nLast validated: Jan 5, 2026\r\n\r\nTailscale Kubernetes Operatoris available for [all plans](https://tailscale.com/pricing).\r\n\r\nThe [Tailscale Kubernetes Operator](https://github.com/tailscale/tailscale/blob/main/cmd/k8s-operator/deploy/manifests/operator.yaml) lets you:\r\n\r\n- [Access the Kubernetes control plane using an API server proxy](https://tailscale.com/docs/features/kubernetes-operator/how-to/api-server-proxy)\r\n- [Expose a tailnet service to your Kubernetes cluster (cluster egress)](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-egress)\r\n- [Expose a cluster workload to your tailnet (cluster ingress)](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-ingress)\r\n- [Expose a cluster workload to another cluster (cross-cluster connectivity)](https://tailscale.com/docs/features/kubernetes-operator/how-to/cross-cluster)\r\n- [Expose a cloud service to your tailnet](https://tailscale.com/docs/features/kubernetes-operator/how-to/cloud-services)\r\n- [Deploy exit nodes and subnet routers](https://tailscale.com/docs/features/kubernetes-operator/how-to/connector)\r\n- [Deploy app connector](https://tailscale.com/docs/features/kubernetes-operator/how-to/app-connector)\r\n- [Deploy `tsrecorder`](https://tailscale.com/docs/features/kubernetes-operator/how-to/tsrecorder)\r\n- [Expose multi-cluster applications to internal users](https://tailscale.com/docs/features/kubernetes-operator/how-to/multi-cluster-ingress)\r\n- [Manage multi-cluster deployments with ArgoCD](https://tailscale.com/docs/solutions/manage-multi-cluster-kubernetes-deployments-argocd)\r\n\r\n## [Setting up the Kubernetes operator](https://tailscale.com/docs/features/kubernetes-operator\\#setting-up-the-kubernetes-operator)\r\n\r\n### [Prerequisites](https://tailscale.com/docs/features/kubernetes-operator\\#prerequisites)\r\n\r\nTailscale Kubernetes Operator must be configured with [OAuth client credentials](https://tailscale.com/docs/features/oauth-clients#setting-up-an-oauth-client). The operator uses these credentials to manage devices by using the [Tailscale API](https://tailscale.com/docs/reference/tailscale-api) and to create [auth keys](https://tailscale.com/docs/features/access-control/auth-keys) for itself and the devices it manages.\r\n\r\n1. In your [tailnet policy file](https://tailscale.com/docs/features/access-control/acls), create the [tags](https://tailscale.com/docs/features/tags)`tag:k8s-operator` and `tag:k8s`, and make `tag:k8s-operator` an owner of `tag:k8s`. If you want your `Services` to be exposed with tags other than the default `tag:k8s`, create those as well and make `tag:k8s-operator` an owner.\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```json\r\n\"tagOwners\": {\r\n \"tag:k8s-operator\": [],\r\n \"tag:k8s\": [\"tag:k8s-operator\"],\r\n}\r\n```\r\n\r\n\r\n\r\n\r\n\r\nYou can use the [visual policy editor](https://tailscale.com/docs/features/visual-editor) to manage your tailnet policy file. Refer to the [visual editor reference](https://tailscale.com/docs/reference/visual-editor) for guidance on using the visual editor.\r\n\r\n2. [Create an OAuth client](https://tailscale.com/docs/features/oauth-clients#setting-up-an-oauth-client) in the [Trust credentials](https://login.tailscale.com/admin/settings/trust-credentials) page of the admin console. Create the client with `Devices Core`, `Auth Keys`, `Services` write scopes, and the tag `tag:k8s-operator`.\r\n\r\n\r\n### [Installation](https://tailscale.com/docs/features/kubernetes-operator\\#installation)\r\n\r\nA default operator installation creates:\r\n\r\n- A `\"tailscale\"``Namespace`.\r\n- An `\"operator\"``Deployment`.\r\n- Role-based access control (RBAC) for the operator.\r\n- A `\"tailscale\"``IngressClass`.\r\n- `ProxyClass`, `Connector`, `ProxyGroup`, `DNSConfig`, `Recorder` Custom Resource Definitions (CRDs).\r\n\r\nThere are two ways to install the Tailscale Kubernetes Operator: using [Helm](https://tailscale.com/docs/features/kubernetes-operator#helm) or applying [static manifests with `kubectl`](https://tailscale.com/docs/features/kubernetes-operator#static-manifests).\r\n\r\n#### [Helm](https://tailscale.com/docs/features/kubernetes-operator\\#helm)\r\n\r\nTailscale Kubernetes Operator's Helm charts are available from two chart repositories.\r\n\r\nThe `https://pkgs.tailscale.com/helmcharts` repository contains well-tested charts for [stable Tailscale versions](https://tailscale.com/docs/reference/tailscale-client-versions).\r\n\r\nHelm charts and container images for a new stable Tailscale version are released a few days after the official release. This is done to avoid releasing image\r\nversions with potential bugs in the core Linux client or core libraries.\r\n\r\nThe `https://pkgs.tailscale.com/unstable/helmcharts` repository contains charts with the very latest changes, published in between official releases.\r\n\r\nThe charts in both repositories are different versions of the same chart and you can upgrade from one to the other.\r\n\r\nTo install the latest Kubernetes Tailscale operator from `https://pkgs.tailscale.com/helmcharts` in `tailscale` namespace:\r\n\r\n1. Add `https://pkgs.tailscale.com/helmcharts` to your local Helm repositories:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nhelm repo add tailscale https://pkgs.tailscale.com/helmcharts\r\n```\r\n\r\n2. Update your local Helm cache:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nhelm repo update\r\n```\r\n\r\n3. Install the operator passing the OAuth client credentials that you created earlier:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nhelm upgrade \\\r\n --install \\\r\n tailscale-operator \\\r\n tailscale/tailscale-operator \\\r\n --namespace=tailscale \\\r\n --create-namespace \\\r\n --set-string oauth.clientId=\"\" \\\r\n --set-string oauth.clientSecret=\"\" \\\r\n --wait\r\n```\r\n\r\n\r\n#### [Static manifests with `kubectl`](https://tailscale.com/docs/features/kubernetes-operator\\#static-manifests-with-kubectl)\r\n\r\n1. Download the Tailscale Kubernetes Operator [manifest file](https://github.com/tailscale/tailscale/blob/main/cmd/k8s-operator/deploy/manifests/operator.yaml) from the [`tailscale/tailscale`](https://github.com/tailscale/tailscale) repository.\r\n\r\n2. Edit your version of the manifest file:\r\n\r\n\r\n1. Find `# SET CLIENT ID HERE` and replace it with your OAuth client ID.\r\n2. Find `# SET CLIENT SECRET HERE` and replace it with your OAuth client secret. The OAuth client secret is case-sensitive.\r\n\r\nFor both the client ID and secret, quote the value, to avoid any potential YAML misinterpretation of unquoted strings. For example, use:\r\n\r\n```yaml\r\nclient_id: \"k123456CNTRL\"\r\nclient_secret: \"tskey-client-k123456CNTRL-abcdef\"\r\n```\r\n\r\ninstead of:\r\n\r\n```yaml\r\nclient_id: k123456CNTRL\r\nclient_secret: tskey-client-k123456CNTRL-abcdef\r\n```\r\n\r\n3. Apply the edited file to your Kubernetes cluster:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nkubectl apply -f manifest.yaml\r\n```\r\n\r\n\r\n### [Installation with workload identity federation](https://tailscale.com/docs/features/kubernetes-operator\\#installation-with-workload-identity-federation)\r\n\r\nWorkload identity federationis currently [in beta](https://tailscale.com/docs/reference/tailscale-release-stages#beta).\r\n\r\nTailscale supports [workload identity federation](https://tailscale.com/docs/features/workload-identity-federation) for authenticating to a tailnet using provider-native identity tokens. The operator can leverage its ServiceAccount token as an OIDC identity and authenticate without requiring a long-lived OAuth client secret.\r\n\r\n#### [Prerequisites](https://tailscale.com/docs/features/kubernetes-operator\\#prerequisites-1)\r\n\r\n- The Kubernetes cluster's OIDC discovery endpoints must be publicly accessible. Bind the `\"unauthenticated\"` group to the `\"system:service-account-issuer-discovery\"``ClusterRole` to allow unauthenticated access:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nkubectl create clusterrolebinding oidc-discovery \\\r\n --clusterrole=system:service-account-issuer-discovery \\\r\n --group=system:unauthenticated\r\n```\r\n\r\n\r\n#### [Helm](https://tailscale.com/docs/features/kubernetes-operator\\#helm-1)\r\n\r\n1. Get your cluster's issuer:\r\n\r\n\r\n\r\nThe following command has a `jq` dependency. You may need to install `jq` on your device.\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nISSUER=\"$(kubectl get --raw /.well-known/openid-configuration | jq '.issuer')\"\r\n```\r\n\r\n2. [Configure a federated identity in the admin console](https://tailscale.com/docs/features/workload-identity-federation#configure-federated-identities-in-the-admin-console) using:\r\n - Set the **Issuer** to **Custom issuer**.\r\n - Set the **Issuer URL** to the value of `$ISSUER` from the previous step.\r\n - Set the **Subject** to `system:serviceaccount:tailscale:operator`.\r\n - Leave the **Audience** field blank.\r\n - Set `Devices Core` and `Auth Keys` and `Services` write scopes.\r\n - And the tag `tag:k8s-operator`.\r\n3. Add `https://pkgs.tailscale.com/helmcharts` to your local Helm repositories:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nhelm repo add tailscale https://pkgs.tailscale.com/helmcharts\r\n```\r\n\r\n4. Update your local Helm cache:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nhelm repo update\r\n```\r\n\r\n5. Install the operator passing the OAuth client details that you created earlier:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\nhelm upgrade \\\r\n --install \\\r\n tailscale-operator \\\r\n tailscale/tailscale-operator \\\r\n --namespace=tailscale \\\r\n --create-namespace \\\r\n --set-string oauth.clientId=\"\" \\\r\n --set-string oauth.audience=\"\" \\\r\n --wait\r\n```\r\n\r\n\r\n### [Validation](https://tailscale.com/docs/features/kubernetes-operator\\#validation)\r\n\r\nVerify that the Tailscale operator has joined your tailnet. Open the [Machines](https://login.tailscale.com/admin/machines) page of the admin console and look for a node named `tailscale-operator` (or your customized hostname) tagged with the `tag:k8s-operator` tag. It may take some time for the operator to join your tailnet as the container image downloads and the Pod starts.\r\n\r\n### [(Optional) Pre-creating a `ProxyGroup`](https://tailscale.com/docs/features/kubernetes-operator\\#optional-pre-creating-a-proxygroup)\r\n\r\nWhen a user configures an [ingress](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-ingress) or [egress](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-egress) proxy, the default mode for the operator is to create a tailnet device deployed as a `StatefulSet` with a single `Pod`.\r\n\r\nThis model has a few caveats:\r\n\r\n- a single `Pod` means that there will be some downtime during proxy upgrades, cluster upgrades, etc\r\n\r\n- a `Pod` per proxy may not be feasible for large installations (high resource consumption)\r\n\r\n\r\nTailscale Kubernetes Operator 1.76 and later provides the ability to pre-create a multi-replica `ProxyGroup`. [Ingress](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-ingress) and [egress](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-egress) can then be exposed redundantly by using the `ProxyGroup`.\r\n\r\nTo create a `ProxyGroup` with three replicas for Tailscale egress `Service`s:\r\n\r\n1. Apply the following manifest:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```yaml\r\napiVersion: tailscale.com/v1alpha1\r\nkind: ProxyGroup\r\nmetadata:\r\n name: ts-proxies\r\nspec:\r\n type: egress\r\n replicas: 3\r\n```\r\n\r\n2. (Optional) Wait for the `ProxyGroup` to become ready:\r\n\r\n\r\n```shell\r\nkubectl wait proxygroup ts-proxies --for=condition=ProxyGroupReady=true\r\n```\r\n\r\nFor the above `ProxyGroup` the operator creates a `StatefulSet` with three replicas, each of which is a tailnet device.\r\n\r\nEgress `Service`s can now refer to the newly created `ProxyGroup`. Refer to [Configure an egress `Service` using `ProxyGroup`](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-egress).\r\n\r\nYou can find [all available `ProxyGroup` configuration options on GitHub →](https://github.com/tailscale/tailscale/blob/main/k8s-operator/api.md#proxygroup)\r\n\r\n## [Supported versions](https://tailscale.com/docs/features/kubernetes-operator\\#supported-versions)\r\n\r\n### [Operator and proxies](https://tailscale.com/docs/features/kubernetes-operator\\#operator-and-proxies)\r\n\r\nTailscale recommends that you use the same version for the operator and the proxies, because majority of our tests run against the same versions.\r\n\r\nThe operator supports proxies running a Tailscale version up to four minor versions earlier than the operator's version.\r\nThe operator does not support proxies running a Tailscale version later than the operator's version.\r\n\r\n### [Kubernetes versions](https://tailscale.com/docs/features/kubernetes-operator\\#kubernetes-versions)\r\n\r\nThe earliest supported version of Kubernetes is v1.23.0.\r\n\r\n## [CNI compatibility](https://tailscale.com/docs/features/kubernetes-operator\\#cni-compatibility)\r\n\r\nThe operator creates proxies that configure custom routing and forwarding rules in each proxy `Pod`'s network namespace only.\r\nBecause the proxying is implemented in the proxy `Pod`'s namespace, the routing and firewall configuration on the `Node` (for example, using iptables, eBPF, or any other mechanism) doesn't affect the proxies.\r\nThis means that the proxies work with most CNI configurations out of the box.\r\n\r\n## [TLS certificates and renewal](https://tailscale.com/docs/features/kubernetes-operator\\#tls-certificates-and-renewal)\r\n\r\nThe operator automatically provisions TLS certificates for Tailscale Ingress and API server proxy services. Certificates are valid for 90 days, and typically renew two-thirds through their validity period. Certificates only renew if there is traffic to the service. If a certificate expires, the next request to the service will trigger a renewal.\r\n\r\n## [EKS Fargate](https://tailscale.com/docs/features/kubernetes-operator\\#eks-fargate)\r\n\r\nOn [EKS Fargate](https://docs.aws.amazon.com/eks/latest/userguide/fargate.html), currently the only supported operator features are [Tailscale `Ingress`](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-ingress#ingress-resource) and [Tailscale API server proxy](https://tailscale.com/docs/features/kubernetes-operator/how-to/api-server-proxy).\r\n[Tailscale ingress `Service`s](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-ingress#ingress-service), [Tailscale egress `Service`s](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-egress) and the [`Connector`](https://tailscale.com/docs/features/kubernetes-operator/how-to/connector) configurations currently contain [privileged containers](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) and containers with [CAP\\_NET\\_ADMIN](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/).\r\nThis is not supported on EKS Fargate.\r\n\r\n### [Cilium in kube-proxy replacement mode](https://tailscale.com/docs/features/kubernetes-operator\\#cilium-in-kube-proxy-replacement-mode)\r\n\r\nYou must enable [bypassing socket load balancer in Pods' namespaces](https://docs.cilium.io/en/stable/network/kubernetes/kubeproxy-free/#socket-loadbalancer-bypass-in-pod-namespace) if you run Cilium in [kube-proxy replacement mode](https://docs.cilium.io/en/stable/network/kubernetes/kubeproxy-free) and want to do one or more of the following:\r\n\r\n- Expose a Kubernetes `Service` to your tailnet as a [Tailscale LoadBalancer `Service`](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-ingress#loadbalancerclass).\r\n- Expose a Kubernetes `Service` to your tailnet using [`tailscale.com/expose` annotation](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-ingress).\r\n- Expose a Service CIDR range by using [`Connector`](https://tailscale.com/docs/features/kubernetes-operator/how-to/connector).\r\n\r\nThis is needed because when Cilium runs in kube-proxy replacement mode with the socket load balancing in `Pod`s' namespaces enabled, connections from `Pod`s to `ClusterIP`s go over a TCP socket (instead of going out via `Pod`s' `veth` devices) and thus bypasses [Tailscale firewall rules](https://tailscale.com/docs/reference/netfilter-modes) that are attached to [netfilter hooks](https://www.netfilter.org/).\r\n\r\nIf you encounter bandwidth issues while using Cilium, use the `--devices` flag to explicitly specify which network interfaces Cilium should monitor for the maximum transmission unit (MTU). This prevents Cilium from defaulting to the MTU of the `tailscale0` interface and instead ensures it uses the MTU of a physical interface on the host.\r\n\r\n## [Customization](https://tailscale.com/docs/features/kubernetes-operator\\#customization)\r\n\r\n[Customize the operator and resources it manages](https://tailscale.com/docs/features/kubernetes-operator/how-to/customize).\r\n\r\n## [Troubleshooting](https://tailscale.com/docs/features/kubernetes-operator\\#troubleshooting)\r\n\r\n[Troubleshoot the operator and resources it manages](https://tailscale.com/docs/reference/troubleshooting/containers/kubernetes-operator).\r\n\r\n## [Limitations](https://tailscale.com/docs/features/kubernetes-operator\\#limitations)\r\n\r\n- There are no dashboards or metrics. We are interested to hear what metrics you would find useful — do [reach out](https://github.com/tailscale/tailscale/issues/new/choose).\r\n- The container images, charts or manifests are not signed. _We are working on this._\r\n- The static manifests are currently only available from the [`tailscale/tailscale`](https://github.com/tailscale/tailscale) codebase. _We are working to improve this flow._\r\n- Using the operator on [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift) is currently not supported.\r\n\r\n## [Glossary](https://tailscale.com/docs/features/kubernetes-operator\\#glossary)\r\n\r\n**Proxy**\r\n\r\nIn the context of this document, a proxy is the Tailscale node deployed for each user-configured component that the operator manages (such as a [`Tailscale Ingress`](https://tailscale.com/docs/features/kubernetes-operator/how-to/cluster-ingress#ingress-resource) or a [`Connector`](https://tailscale.com/docs/features/kubernetes-operator/how-to/connector)).\r\nThe proxy is deployed as a `StatefulSet` in the operator's namespace (defaults to `tailscale`).\r\nThe `StatefulSet`s name is prefixed by a portion of the configured component's name.\r\n\r\nIf you need to reliably refer to the proxy's `StatefulSet`, you can use label selectors.\r\nFor example, to find `StatefulSet` for a Tailscale `Ingress` resource named `ts-ingress` in `prod` namespace , you can run:\r\n\r\n```shell\r\nkubectl get statefulset \\\r\n --namespace tailscale \\\r\n --selector=\"tailscale.com/managed=true,tailscale.com/parent-resource-type=ingress,tailscale.com/parent-resource=ts-ingress,tailscale.com/parent-resource-ns=prod\"\r\n```\r\n\r\nThe `tailscale.com/parent-resource` label is set to `svc` for a `Service` and to `connector` for a `Connector`.\r\nThe `tailscale.com` labels are also propagated to the `Pod`.\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":"

Kubernetes operator

\n

Last validated: Jan 5, 2026

\n

Tailscale Kubernetes Operatoris available for all plans.

\n

The Tailscale Kubernetes Operator lets you:

\n\n

Setting up the Kubernetes operator

\n

Prerequisites

\n

Tailscale Kubernetes Operator must be configured with OAuth client credentials. The operator uses these credentials to manage devices by using the Tailscale API and to create auth keys for itself and the devices it manages.

\n
    \n
  1. In your tailnet policy file, create the tagstag:k8s-operator and tag:k8s, and make tag:k8s-operator an owner of tag:k8s. If you want your Services to be exposed with tags other than the default tag:k8s, create those as well and make tag:k8s-operator an owner.
    2. \n
\n
\"tagOwners\": {\r\n     \"tag:k8s-operator\": [],\r\n     \"tag:k8s\": [\"tag:k8s-operator\"],\r\n}\n
\n

You can use the visual policy editor to manage your tailnet policy file. Refer to the visual editor reference for guidance on using the visual editor.

\n
    \n
  1. Create an OAuth client in the Trust credentials page of the admin console. Create the client with Devices Core, Auth Keys, Services write scopes, and the tag tag:k8s-operator.
    2. \n
\n

Installation

\n

A default operator installation creates:

\n
    \n
  • A \"tailscale\"``Namespace.
    • \n
  • An \"operator\"``Deployment.
    • \n
  • Role-based access control (RBAC) for the operator.
    • \n
  • A \"tailscale\"``IngressClass.
    • \n
  • ProxyClass, Connector, ProxyGroup, DNSConfig, Recorder Custom Resource Definitions (CRDs).
    • \n
\n

There are two ways to install the Tailscale Kubernetes Operator: using Helm or applying static manifests with kubectl.

\n

Helm

\n

Tailscale Kubernetes Operator's Helm charts are available from two chart repositories.

\n

The https://pkgs.tailscale.com/helmcharts repository contains well-tested charts for stable Tailscale versions.

\n

Helm charts and container images for a new stable Tailscale version are released a few days after the official release. This is done to avoid releasing image\r\nversions with potential bugs in the core Linux client or core libraries.

\n

The https://pkgs.tailscale.com/unstable/helmcharts repository contains charts with the very latest changes, published in between official releases.

\n

The charts in both repositories are different versions of the same chart and you can upgrade from one to the other.

\n

To install the latest Kubernetes Tailscale operator from https://pkgs.tailscale.com/helmcharts in tailscale namespace:

\n
    \n
  1. Add https://pkgs.tailscale.com/helmcharts to your local Helm repositories:
    2. \n
\n
helm repo add tailscale https://pkgs.tailscale.com/helmcharts\n
\n
    \n
  1. Update your local Helm cache:
    2. \n
\n
helm repo update\n
\n
    \n
  1. Install the operator passing the OAuth client credentials that you created earlier:
    2. \n
\n
helm upgrade \\\r\n     --install \\\r\n     tailscale-operator \\\r\n     tailscale/tailscale-operator \\\r\n     --namespace=tailscale \\\r\n     --create-namespace \\\r\n     --set-string oauth.clientId=\"<OAauth client ID>\" \\\r\n     --set-string oauth.clientSecret=\"<OAuth client secret>\" \\\r\n     --wait\n
\n

Static manifests with kubectl

\n
    \n
  1. \n

    Download the Tailscale Kubernetes Operator manifest file from the tailscale/tailscale repository.

    \n
    2. \n
  2. \n

    Edit your version of the manifest file:

    \n
    3. \n
  3. \n

    Find # SET CLIENT ID HERE and replace it with your OAuth client ID.

    \n
    4. \n
  4. \n

    Find # SET CLIENT SECRET HERE and replace it with your OAuth client secret. The OAuth client secret is case-sensitive.

    \n
    5. \n
\n

For both the client ID and secret, quote the value, to avoid any potential YAML misinterpretation of unquoted strings. For example, use:

\n
client_id: \"k123456CNTRL\"\r\nclient_secret: \"tskey-client-k123456CNTRL-abcdef\"\n
\n

instead of:

\n
client_id: k123456CNTRL\r\nclient_secret: tskey-client-k123456CNTRL-abcdef\n
\n
    \n
  1. Apply the edited file to your Kubernetes cluster:
    2. \n
\n
kubectl apply -f manifest.yaml\n
\n

Installation with workload identity federation

\n

Workload identity federationis currently in beta.

\n

Tailscale supports workload identity federation for authenticating to a tailnet using provider-native identity tokens. The operator can leverage its ServiceAccount token as an OIDC identity and authenticate without requiring a long-lived OAuth client secret.

\n

Prerequisites

\n
    \n
  • The Kubernetes cluster's OIDC discovery endpoints must be publicly accessible. Bind the \"unauthenticated\" group to the \"system:service-account-issuer-discovery\"``ClusterRole to allow unauthenticated access:
    • \n
\n
kubectl create clusterrolebinding oidc-discovery \\\r\n    --clusterrole=system:service-account-issuer-discovery \\\r\n    --group=system:unauthenticated\n
\n

Helm

\n
    \n
  1. Get your cluster's issuer:
    2. \n
\n

The following command has a jq dependency. You may need to install jq on your device.

\n
ISSUER=\"$(kubectl get --raw /.well-known/openid-configuration | jq '.issuer')\"\n
\n
    \n
  1. Configure a federated identity in the admin console using:\n
      \n
    • Set the Issuer to Custom issuer.
      • \n
    • Set the Issuer URL to the value of $ISSUER from the previous step.
      • \n
    • Set the Subject to system:serviceaccount:tailscale:operator.
      • \n
    • Leave the Audience field blank.
      • \n
    • Set Devices Core and Auth Keys and Services write scopes.
      • \n
    • And the tag tag:k8s-operator.
      • \n
    \n
    2. \n
  2. Add https://pkgs.tailscale.com/helmcharts to your local Helm repositories:
    3. \n
\n
helm repo add tailscale https://pkgs.tailscale.com/helmcharts\n
\n
    \n
  1. Update your local Helm cache:
    2. \n
\n
helm repo update\n
\n
    \n
  1. Install the operator passing the OAuth client details that you created earlier:
    2. \n
\n
helm upgrade \\\r\n     --install \\\r\n     tailscale-operator \\\r\n     tailscale/tailscale-operator \\\r\n     --namespace=tailscale \\\r\n     --create-namespace \\\r\n     --set-string oauth.clientId=\"<OAauth client ID>\" \\\r\n     --set-string oauth.audience=\"<OAuth client audience>\" \\\r\n     --wait\n
\n

Validation

\n

Verify that the Tailscale operator has joined your tailnet. Open the Machines page of the admin console and look for a node named tailscale-operator (or your customized hostname) tagged with the tag:k8s-operator tag. It may take some time for the operator to join your tailnet as the container image downloads and the Pod starts.

\n

(Optional) Pre-creating a ProxyGroup

\n

When a user configures an ingress or egress proxy, the default mode for the operator is to create a tailnet device deployed as a StatefulSet with a single Pod.

\n

This model has a few caveats:

\n
    \n
  • \n

    a single Pod means that there will be some downtime during proxy upgrades, cluster upgrades, etc

    \n
    • \n
  • \n

    a Pod per proxy may not be feasible for large installations (high resource consumption)

    \n
    • \n
\n

Tailscale Kubernetes Operator 1.76 and later provides the ability to pre-create a multi-replica ProxyGroup. Ingress and egress can then be exposed redundantly by using the ProxyGroup.

\n

To create a ProxyGroup with three replicas for Tailscale egress Services:

\n
    \n
  1. Apply the following manifest:
    2. \n
\n
apiVersion: tailscale.com/v1alpha1\r\nkind: ProxyGroup\r\nmetadata:\r\n     name: ts-proxies\r\nspec:\r\n     type: egress\r\n     replicas: 3\n
\n
    \n
  1. (Optional) Wait for the ProxyGroup to become ready:
    2. \n
\n
kubectl wait proxygroup ts-proxies --for=condition=ProxyGroupReady=true\n
\n

For the above ProxyGroup the operator creates a StatefulSet with three replicas, each of which is a tailnet device.

\n

Egress Services can now refer to the newly created ProxyGroup. Refer to Configure an egress Service using ProxyGroup.

\n

You can find all available ProxyGroup configuration options on GitHub →

\n

Supported versions

\n

Operator and proxies

\n

Tailscale recommends that you use the same version for the operator and the proxies, because majority of our tests run against the same versions.

\n

The operator supports proxies running a Tailscale version up to four minor versions earlier than the operator's version.\r\nThe operator does not support proxies running a Tailscale version later than the operator's version.

\n

Kubernetes versions

\n

The earliest supported version of Kubernetes is v1.23.0.

\n

CNI compatibility

\n

The operator creates proxies that configure custom routing and forwarding rules in each proxy Pod's network namespace only.\r\nBecause the proxying is implemented in the proxy Pod's namespace, the routing and firewall configuration on the Node (for example, using iptables, eBPF, or any other mechanism) doesn't affect the proxies.\r\nThis means that the proxies work with most CNI configurations out of the box.

\n

TLS certificates and renewal

\n

The operator automatically provisions TLS certificates for Tailscale Ingress and API server proxy services. Certificates are valid for 90 days, and typically renew two-thirds through their validity period. Certificates only renew if there is traffic to the service. If a certificate expires, the next request to the service will trigger a renewal.

\n

EKS Fargate

\n

On EKS Fargate, currently the only supported operator features are Tailscale Ingress and Tailscale API server proxy.\r\nTailscale ingress Services, Tailscale egress Services and the Connector configurations currently contain privileged containers and containers with CAP_NET_ADMIN.\r\nThis is not supported on EKS Fargate.

\n

Cilium in kube-proxy replacement mode

\n

You must enable bypassing socket load balancer in Pods' namespaces if you run Cilium in kube-proxy replacement mode and want to do one or more of the following:

\n\n

This is needed because when Cilium runs in kube-proxy replacement mode with the socket load balancing in Pods' namespaces enabled, connections from Pods to ClusterIPs go over a TCP socket (instead of going out via Pods' veth devices) and thus bypasses Tailscale firewall rules that are attached to netfilter hooks.

\n

If you encounter bandwidth issues while using Cilium, use the --devices flag to explicitly specify which network interfaces Cilium should monitor for the maximum transmission unit (MTU). This prevents Cilium from defaulting to the MTU of the tailscale0 interface and instead ensures it uses the MTU of a physical interface on the host.

\n

Customization

\n

Customize the operator and resources it manages.

\n

Troubleshooting

\n

Troubleshoot the operator and resources it manages.

\n

Limitations

\n
    \n
  • There are no dashboards or metrics. We are interested to hear what metrics you would find useful — do reach out.
    • \n
  • The container images, charts or manifests are not signed. We are working on this.
    • \n
  • The static manifests are currently only available from the tailscale/tailscale codebase. We are working to improve this flow.
    • \n
  • Using the operator on OpenShift is currently not supported.
    • \n
\n

Glossary

\n

Proxy

\n

In the context of this document, a proxy is the Tailscale node deployed for each user-configured component that the operator manages (such as a Tailscale Ingress or a Connector).\r\nThe proxy is deployed as a StatefulSet in the operator's namespace (defaults to tailscale).\r\nThe StatefulSets name is prefixed by a portion of the configured component's name.

\n

If you need to reliably refer to the proxy's StatefulSet, you can use label selectors.\r\nFor example, to find StatefulSet for a Tailscale Ingress resource named ts-ingress in prod namespace , you can run:

\n
kubectl get statefulset \\\r\n  --namespace tailscale \\\r\n  --selector=\"tailscale.com/managed=true,tailscale.com/parent-resource-type=ingress,tailscale.com/parent-resource=ts-ingress,tailscale.com/parent-resource-ns=prod\"\n
\n

The tailscale.com/parent-resource label is set to svc for a Service and to connector for a Connector.\r\nThe tailscale.com labels are also propagated to the Pod.

\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}