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

Install the Tailscale Kubernetes Operator

Last validated:

This guide explains setting up the Tailscale Kubernetes Operator in your cluster. You will configure access control tags, create OAuth credentials, and install the operator using Helm or static manifests.

If you prefer not to use OAuth credentials, you can instead install the operator using workload identity federation.

Prerequisites

For known compatibility issues, refer to our compatibility guide.

Before you begin, ensure you have the following:

Configure tags and OAuth credentials

Before installing the operator, you need to create tags and an OAuth client for the operator to use.

  1. In your Access controls, add the following under the tagOwners section:

    "tagOwners": {
  "tag:k8s-operator": [],
  "tag:k8s": ["tag:k8s-operator"],
}

    This will:

    • Create the tags tag:k8s-operator and tag:k8s.
    • Make tag:k8s-operator an owner of tag:k8s (so the operator can manage devices with tag:k8s).

    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.

  2. Create an OAuth client in the Trust credentials page of the admin console. Create the client with write scope for:

    • General/Services (with tag:k8s-operator)
    • Devices/Core (with tag:k8s-operator)
    • Keys/Auth Keys (with tag:k8s-operator)

The operator uses these credentials to manage devices via the Tailscale API and to create auth keys for itself and the devices it manages.

Install the operator

A default operator installation creates:

  • A "tailscale" Namespace.
  • An "operator" Deployment.
  • Role-based access control (RBAC) for the operator.
  • A "tailscale" IngressClass.
  • ProxyClass, Connector, ProxyGroup, DNSConfig, Recorder, Tailnet custom resource definitions (CRDs).

There are two ways to install the Tailscale Kubernetes Operator:

Install using Helm

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

  • The https://pkgs.tailscale.com/helmcharts repository contains well-tested charts for stable Tailscale versions.
  • The https://pkgs.tailscale.com/unstable/helmcharts repository contains charts with the very latest changes, published in between official releases.

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

Helm charts and container images for a new stable Tailscale version are released a few days after the official release.

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

  1. Add https://pkgs.tailscale.com/helmcharts to your local Helm repositories:

    helm repo add tailscale https://pkgs.tailscale.com/helmcharts

  2. Update your local Helm cache:

    helm repo update

  3. Install the operator, passing in the OAuth client credentials that you created earlier:

    helm upgrade \
  --install \
  tailscale-operator \
  tailscale/tailscale-operator \
  --namespace=tailscale \
  --create-namespace \
  --set-string oauth.clientId="<OAuth client ID>" \
  --set-string oauth.clientSecret="<OAuth client secret>" \
  --wait

  4. Validate that the operator has successfully joined your tailnet.

Install using static manifests with kubectl

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

  2. Edit your version of the manifest file:

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

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

    client_id: "k123456CNTRL"
client_secret: "tskey-client-k123456CNTRL-abcdef"

  3. Apply the edited file to your Kubernetes cluster:

    kubectl apply -f operator.yaml

  4. Validate that the operator has successfully joined your tailnet.

Validation

To 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.

Further exploration