{"slug":"use-multiple-tailnets-for-devices-running-on-kubernetes","title":"Use multiple tailnets for devices running on Kubernetes","tags":["tailscale","containers","devices"],"agent_summary":"Last validated: Mar 6, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Use multiple tailnets for devices running on Kubernetes\r\n\r\nLast validated: Mar 6, 2026\r\n\r\nUsing multiple tailnets with a single operator deploymentis currently [in alpha](https://tailscale.com/docs/reference/tailscale-release-stages#alpha).\r\n\r\nWhen deploying the Tailscale operator's [custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources), you may want workloads to not only be\r\nable to communicate across clusters, but also across tailnets. For operator versions 1.96 and later you can now use the\r\n`Tailnet` custom resource definition to specify which tailnet should be used by `ProxyGroup`, `Connector` and `Recorder`\r\ninstances.\r\n\r\n## [Prerequisites](https://tailscale.com/docs/features/kubernetes-operator/how-to/multi-tailnet\\#prerequisites)\r\n\r\nBefore you begin, you will need access to multiple tailnets. This can either be through separate logins or managed by\r\na single organization. For more information on managing multiple tailnets within a single organization, refer to the\r\ndocumentation for [managing multiple tailnets](https://tailscale.com/docs/features/kubernetes-operator/how-to/multi-tailnet).\r\n\r\nEach tailnet you wish to expose requires the appropriate `tagOwners` set in your ACL policy file for the Kubernetes\r\noperator:\r\n\r\n```json\r\n\"tagOwners\": {\r\n\t\"tag:k8s-operator\": [],\r\n\t\"tag:k8s\": [\"tag:k8s-operator\"],\r\n}\r\n```\r\n\r\nIf you're using different tags to the default `tag:k8s-operator`, use those in place of the example given\r\nabove.\r\n\r\nFinally, each tailnet requires an [OAuth client](https://tailscale.com/docs/features/oauth-clients) that can be used by the operator to generate\r\nauth keys for workloads. Before attempting to create a `Tailnet` resource, create a new OAuth client in the\r\n[Trust credentials](https://login.tailscale.com/admin/settings/trust-credentials) page of the admin console for the tailnet you wish to provide\r\naccess to. Create the client with `Devices Core`, `Auth Keys`, `Services` write scopes, and the tag `tag:k8s-operator`.\r\n\r\n## [Creating a Tailnet resource](https://tailscale.com/docs/features/kubernetes-operator/how-to/multi-tailnet\\#creating-a-tailnet-resource)\r\n\r\nEach `Tailnet` resource references a set of OAuth credentials that must be stored as a Kubernetes `Secret` within the\r\nsame namespace as the operator.\r\n\r\nOnce you have the client id and secret, create a `Secret` resource:\r\n\r\n```yaml\r\napiVersion: v1\r\nkind: Secret\r\nmetadata:\r\n name: example-tailnet\r\n namespace: tailscale\r\nstringData:\r\n client_id: \"\"\r\n client_secret: \"\"\r\n```\r\n\r\nIf you deployed the Kubernetes operator into a different namespace, use the name of that namespace instead of\r\n`tailscale`.\r\n\r\nNext, create a `Tailnet` resource that references the secret containing the OAuth credentials:\r\n\r\n```yaml\r\napiVersion: tailscale.com/v1alpha\r\nkind: Tailnet\r\nmetadata:\r\n name: example-tailnet\r\nspec:\r\n credentials:\r\n secretName: example-tailnet\r\n```\r\n\r\n`Tailnet` resources are cluster-scoped and do not require a value in the `namespace` field.\r\n\r\nOnce deployed, the operator will perform checks that ensure the specified credentials exist and have access to the\r\nTailscale API. If successful, the `Tailnet` resource will transition into the `TailnetReady` state, and can be used\r\nby other resources. Use the `kubectl get tailnet` command to view the status of your tailnet.\r\n\r\n## [Choosing a Tailnet](https://tailscale.com/docs/features/kubernetes-operator/how-to/multi-tailnet\\#choosing-a-tailnet)\r\n\r\nOnce you have one or more `Tailnet` resources in your cluster, you can create `ProxyGroup`, `Connector` and `Recorder`\r\nresources that connect to that tailnet using the `spec.tailnet` field. This field is immutable, with a blank tailnet\r\ndenoting that the resource should use the tailnet that the operator was originally configured with.\r\n\r\nBelow are some basic examples of how to configure these resources to use a specific tailnet:\r\n\r\n```yaml\r\napiVersion: tailscale.com/v1alpha1\r\nkind: Connector\r\nmetadata:\r\n\tname: example-connector\r\nspec:\r\n\treplicas: 3\r\n\ttailnet: example-tailnet\r\n\texitNode: true\r\n```\r\n\r\nFor more information on `Connector` resources, refer to the [subnet routers and exit nodes](https://tailscale.com/docs/features/kubernetes-operator/how-to/connector) documentation.\r\n\r\n```yaml\r\napiVersion: tailscale.com/v1alpha1\r\nkind: Recorder\r\nmetadata:\r\n\tname: example-recorder\r\nspec:\r\n\treplicas: 3\r\n\ttailnet: example-tailnet\r\n\tstorage: {}\r\n```\r\n\r\nFor more information on `Recorder` resources, refer to the [recorder nodes](https://tailscale.com/docs/features/kubernetes-operator/how-to/tsrecorder) documentation.\r\n\r\n```yaml\r\napiVersion: tailscale.com/v1alpha1\r\nkind: ProxyGroup\r\nmetadata:\r\n\tname: example-proxygroup\r\nspec:\r\n\treplicas: 3\r\n\ttailnet: example-tailnet\r\n\ttype: kube-apiserver\r\n```\r\n\r\nFor more information on `ProxyGroup` resources, refer to the [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) documentation and\r\ntheir relevant sections on using `ProxyGroup` resources.\r\n\r\nOnce started and ready, your devices should appear across your tailnets in the respective [Machines](https://login.tailscale.com/admin/machines)\r\npages of your tailnets.\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":"

Use multiple tailnets for devices running on Kubernetes

\n

Last validated: Mar 6, 2026

\n

Using multiple tailnets with a single operator deploymentis currently in alpha.

\n

When deploying the Tailscale operator's custom resources, you may want workloads to not only be\r\nable to communicate across clusters, but also across tailnets. For operator versions 1.96 and later you can now use the\r\nTailnet custom resource definition to specify which tailnet should be used by ProxyGroup, Connector and Recorder\r\ninstances.

\n

Prerequisites

\n

Before you begin, you will need access to multiple tailnets. This can either be through separate logins or managed by\r\na single organization. For more information on managing multiple tailnets within a single organization, refer to the\r\ndocumentation for managing multiple tailnets.

\n

Each tailnet you wish to expose requires the appropriate tagOwners set in your ACL policy file for the Kubernetes\r\noperator:

\n
\"tagOwners\": {\r\n\t\"tag:k8s-operator\": [],\r\n\t\"tag:k8s\": [\"tag:k8s-operator\"],\r\n}\n
\n

If you're using different tags to the default tag:k8s-operator, use those in place of the example given\r\nabove.

\n

Finally, each tailnet requires an OAuth client that can be used by the operator to generate\r\nauth keys for workloads. Before attempting to create a Tailnet resource, create a new OAuth client in the\r\nTrust credentials page of the admin console for the tailnet you wish to provide\r\naccess to. Create the client with Devices Core, Auth Keys, Services write scopes, and the tag tag:k8s-operator.

\n

Creating a Tailnet resource

\n

Each Tailnet resource references a set of OAuth credentials that must be stored as a Kubernetes Secret within the\r\nsame namespace as the operator.

\n

Once you have the client id and secret, create a Secret resource:

\n
apiVersion: v1\r\nkind: Secret\r\nmetadata:\r\n  name: example-tailnet\r\n  namespace: tailscale\r\nstringData:\r\n  client_id: \"<CLIENT_ID>\"\r\n  client_secret: \"<CLIENT_SECRET>\"\n
\n

If you deployed the Kubernetes operator into a different namespace, use the name of that namespace instead of\r\ntailscale.

\n

Next, create a Tailnet resource that references the secret containing the OAuth credentials:

\n
apiVersion: tailscale.com/v1alpha\r\nkind: Tailnet\r\nmetadata:\r\n  name: example-tailnet\r\nspec:\r\n  credentials:\r\n    secretName: example-tailnet\n
\n

Tailnet resources are cluster-scoped and do not require a value in the namespace field.

\n

Once deployed, the operator will perform checks that ensure the specified credentials exist and have access to the\r\nTailscale API. If successful, the Tailnet resource will transition into the TailnetReady state, and can be used\r\nby other resources. Use the kubectl get tailnet command to view the status of your tailnet.

\n

Choosing a Tailnet

\n

Once you have one or more Tailnet resources in your cluster, you can create ProxyGroup, Connector and Recorder\r\nresources that connect to that tailnet using the spec.tailnet field. This field is immutable, with a blank tailnet\r\ndenoting that the resource should use the tailnet that the operator was originally configured with.

\n

Below are some basic examples of how to configure these resources to use a specific tailnet:

\n
apiVersion: tailscale.com/v1alpha1\r\nkind: Connector\r\nmetadata:\r\n\tname: example-connector\r\nspec:\r\n\treplicas: 3\r\n\ttailnet: example-tailnet\r\n\texitNode: true\n
\n

For more information on Connector resources, refer to the subnet routers and exit nodes documentation.

\n
apiVersion: tailscale.com/v1alpha1\r\nkind: Recorder\r\nmetadata:\r\n\tname: example-recorder\r\nspec:\r\n\treplicas: 3\r\n\ttailnet: example-tailnet\r\n\tstorage: {}\n
\n

For more information on Recorder resources, refer to the recorder nodes documentation.

\n
apiVersion: tailscale.com/v1alpha1\r\nkind: ProxyGroup\r\nmetadata:\r\n\tname: example-proxygroup\r\nspec:\r\n\treplicas: 3\r\n\ttailnet: example-tailnet\r\n\ttype: kube-apiserver\n
\n

For more information on ProxyGroup resources, refer to the ingress or egress documentation and\r\ntheir relevant sections on using ProxyGroup resources.

\n

Once started and ready, your devices should appear across your tailnets in the respective Machines\r\npages of your tailnets.

\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}