Customize the Kubernetes operator and resources it manages

Cluster resource customization using ProxyClass Custom Resource

Tailscale operator v1.60 and later provides the ability to customize the configuration of cluster resources created by the operator using ProxyClass Custom Resource Definition.

You can specify cluster resource configuration for custom labels and resource requests using a ProxyClass Custom Resource.

You can then:

• Apply configuration from a particular ProxyClass to cluster resources created for a tailscale Ingress or Service using a tailscale.com/proxy-class=<proxy-class-name> label on the Ingress or Service.

• Apply configuration from a particular ProxyClass to cluster resources created for a Connector using connector.spec.proxyClass field.

The following example demonstrates how to use a ProxyClass that specifies custom labels and node selector that should get applied to Pods for a tailscale Ingress, a cluster egress proxy and a Connector:

1. Create a ProxyClass resource:

   apiVersion: tailscale.com/v1alpha1
   kind: ProxyClass
   metadata:
     name: prod
   spec:
     statefulSet:
       pod:
         labels:
           team: eng
           environment: prod
         nodeSelector:
           beta.kubernetes.io/os: "linux"
   

2. Create a tailscale Ingress with tailscale.com/proxy-class=prod label:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: my-app
     labels:
       tailscale.com/proxy-class: "prod"
   spec:
     rules:
     ...
     ingressClassName: tailscale
   

3. Create a cluster egress Service with a tailscale.com/proxy-class=prod label:

   apiVersion: v1
   kind: Service
   metadata:
     annotations:
       tailscale.com/tailnet-ip: <tailnet-ip>
     labels:
       tailscale.com/proxy-class: "prod"
     name: my-tailnet-service
   spec:
   

4. Create a Connector that refers to the 'prod' ProxyClass:

   apiVersion: tailscale.com/v1alpha1
   kind: Connector
   metadata:
     name: prod
   spec:
     proxyClass: prod
     ...
   

You can find all available ProxyClass configuration options on GitHub →

Cluster egress and cluster ingress proxy configuration

Configuration options in this section apply to both cluster egress and cluster ingress (configured through a Service or Ingress) proxies.

Customizing tags

Currently, cluster ingress and cluster egress proxies join your tailnet as separate Tailscale devices tagged by one or more tags.

The Tailscale operator must be a tag owner of all the proxy tags: if you want to tag a proxy device with tag:foo,tag:bar, the tagOwners section of the tailnet policy file must list tag:k8s-operator as one of the owners of both tag:foo and tag:bar.

Default tags

By default, a proxy device joins your tailnet tagged with the tag tag:k8s. You can modify the default tag or tags when installing the operator.

If you install the operator with Helm, you can use .proxyConfig.defaultTags in the Helm values file.

If you install the operator with static manifests, you can set the PROXY_TAGS environment variable in the deployment manifest.

Multiple tags must be passed as a comma separated string, that is, tag:foo,tag:bar.

Tags for individual proxies

To override the default tags for an individual proxy device, you can set tailscale.com/tags annotation on the Service or Ingress resource, used to tell the operator to create the proxy, to a comma separated list of the desired tags.

For example, setting tailscale.com/tags = "tag:foo,tag:bar" will result in the proxy device having the tags tag:foo and tag:bar.

Using custom machine names

Cluster ingress and egress proxies support overriding the hostname they announce while registering with Tailscale. For Services, you can set a custom hostname using a tailscale.com/hostname annotation. For Ingresses, you can set a custom hostname using the .spec.tls.hosts field (only the first value will be used).

Note that this only sets a custom operating system (OS) hostname reported by the device. The actual machine name will differ if a device is on the network with the same name.

Machine names are subject to the constraints of DNS: they can be up to 63 characters long, must start and end with a letter, and consist of only letters, numbers, and -.