Get started
Login
© 2024

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 →

Default ProxyClass

Tailscale v1.74 and later allows specifying a default ProxyClass. Configuration from a default ProxyClass is applied to cluster ingress, cluster egress and ProxyGroup proxies that don't have a ProxyClass explicitly set. You can set a default ProxyClass for the cluster via the proxyConfig.defaultProxyClass Helm value if installing using Helm or via the PROXY_DEFAULT_CLASS environment variable if installing using static manifests.

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.

The API server proxy currently runs as part of the same process as the Kubernetes operator. You can use the available operator configuration options to configure the API server proxy parameters.

Customizing tags

All the proxies that the operator creates are 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:prod,tag:emea, the tagOwners section of the tailnet policy file must list tag:k8s-operator as one of the owners of both tag:prod and tag:emea.

Currently, tags can not be modified after a proxy has been created.

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:prod,tag:emea.

Tags for individual proxies

To override the default tags for an individual proxy created for a Tailscale Service or Ingress, you can set the tailscale.com/tags annotation on the Service or Ingress resource to a comma separated list of the desired tags. For example, setting tailscale.com/tags: "tag:prod,tag:emea" annotation will result in the proxy device having the tags tag:prod and tag:emea.

To override the default tags for the proxy created for a Connector custom resource, you can set tags via the spec.tags field.

See also Common patterns for tag names for best practices around tag names.

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