API Reference
Packages
tailscale.com/v1alpha1
Package v1alpha1 documents the k8s-operator API.
Resource Types
- Connector
- ConnectorList
- DNSConfig
- DNSConfigList
- PeerRelay
- PeerRelayList
- ProxyClass
- ProxyClassList
- ProxyGroup
- ProxyGroupList
- ProxyGroupPolicy
- ProxyGroupPolicyList
- Recorder
- RecorderList
- Tailnet
- TailnetList
APIServerProxyMode
Underlying type: string
Validation:
- Enum: [auth noauth]
- Type: string
Appears in:
AppConnector
AppConnector defines a Tailscale app connector node configured via Connector.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
routes Routes |
Routes are optional preconfigured routes for the domains routed via the app connector. If not set, routes for the domains will be discovered dynamically. If set, the app connector will immediately be able to route traffic using the preconfigured routes, but may also dynamically discover other routes. https://tailscale.com/kb/1332/apps-best-practices#preconfiguration |
Format: cidr MinItems: 1 Type: string |
Connector
Connector defines a Tailscale node that will be deployed in the cluster. The node can be configured to act as a Tailscale subnet router and/or a Tailscale exit node. Connector is a cluster-scoped resource. More info: https://tailscale.com/kb/1441/kubernetes-operator-connector
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
tailscale.com/v1alpha1 |
||
kind string |
Connector |
||
kind string |
Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds |
||
apiVersion string |
APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec ConnectorSpec |
ConnectorSpec describes the desired Tailscale component. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status |
||
status ConnectorStatus |
ConnectorStatus describes the status of the Connector. This is set and managed by the Tailscale operator. |
ConnectorDevice
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
hostname string |
Hostname is the fully qualified domain name of the Connector replica. If MagicDNS is enabled in your tailnet, it is the MagicDNS name of the node. |
||
tailnetIPs string array |
TailnetIPs is the set of tailnet IP addresses (both IPv4 and IPv6) assigned to the Connector replica. |
ConnectorList
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
tailscale.com/v1alpha1 |
||
kind string |
ConnectorList |
||
kind string |
Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds |
||
apiVersion string |
APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources |
||
metadata ListMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
items Connector array |
ConnectorSpec
ConnectorSpec describes a Tailscale node to be deployed in the cluster.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
tags Tags |
Tags that the Tailscale node will be tagged with. Defaults to [tag:k8s]. To autoapprove the subnet routes or exit node defined by a Connector, you can configure Tailscale ACLs to give these tags the necessary permissions. See https://tailscale.com/kb/1337/acl-syntax#autoapprovers. If you specify custom tags here, you must also make the operator an owner of these tags. See https://tailscale.com/kb/1236/kubernetes-operator/#setting-up-the-kubernetes-operator. Tags cannot be changed once a Connector node has been created. Tag values must be in form ^tag:[a-zA-Z][a-zA-Z0-9-]*$. |
Pattern: ^tag:[a-zA-Z][a-zA-Z0-9-]*$ Type: string |
|
hostname Hostname |
Hostname is the tailnet hostname that should be assigned to the Connector node. If unset, hostname defaults to <connector name>-connector. Hostname can contain lower case letters, numbers and dashes, it must not start or end with a dash and must be between 2 and 63 characters long. This field should only be used when creating a connector with an unspecified number of replicas, or a single replica. |
Pattern: ^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$ Type: string |
|
hostnamePrefix HostnamePrefix |
HostnamePrefix specifies the hostname prefix for each replica. Each device will have the integer number from its StatefulSet pod appended to this prefix to form the full hostname. HostnamePrefix can contain lower case letters, numbers and dashes, it must not start with a dash and must be between 1 and 62 characters long. |
Pattern: ^[a-z0-9][a-z0-9-]{0,61}$ Type: string |
|
proxyClass string |
ProxyClass is the name of the ProxyClass custom resource that contains configuration options that should be applied to the resources created for this Connector. If unset, the operator will create resources with the default configuration. |
||
subnetRouter SubnetRouter |
SubnetRouter defines subnet routes that the Connector device should expose to tailnet as a Tailscale subnet router. https://tailscale.com/kb/1019/subnets/ If this field is unset, the device does not get configured as a Tailscale subnet router. This field is mutually exclusive with the appConnector field. |
||
appConnector AppConnector |
AppConnector defines whether the Connector device should act as a Tailscale app connector. A Connector that is configured as an app connector cannot be a subnet router or an exit node. If this field is unset, the Connector does not act as an app connector. Note that you will need to manually configure the permissions and the domains for the app connector via the Admin panel. Note also that the main tested and supported use case of this config option is to deploy an app connector on Kubernetes to access SaaS applications available on the public internet. Using the app connector to expose cluster workloads or other internal workloads to tailnet might work, but this is not a use case that we have tested or optimised for. If you are using the app connector to access SaaS applications because you need a predictable egress IP that can be whitelisted, it is also your responsibility to ensure that cluster traffic from the connector flows via that predictable IP, for example by enforcing that cluster egress traffic is routed via an egress NAT device with a static IP address. https://tailscale.com/kb/1281/app-connectors |
||
exitNode boolean |
ExitNode defines whether the Connector device should act as a Tailscale exit node. Defaults to false. This field is mutually exclusive with the appConnector field. https://tailscale.com/kb/1103/exit-nodes |
||
replicas integer |
Replicas specifies how many devices to create. Set this to enable high availability for app connectors, subnet routers, or exit nodes. https://tailscale.com/kb/1115/high-availability. Defaults to 1. |
Minimum: 0 |
|
tailnet string |
Tailnet specifies the tailnet this Connector should join. If blank, the default tailnet is used. When set, this name must match that of a valid Tailnet resource. This field is immutable and cannot be changed once set. |
ConnectorStatus
ConnectorStatus defines the observed state of the Connector.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
conditions Condition array |
List of status conditions to indicate the status of the Connector. Known condition types are ConnectorReady. |
||
subnetRoutes string |
SubnetRoutes are the routes currently exposed to tailnet via this Connector instance. |
||
isExitNode boolean |
IsExitNode is set to true if the Connector acts as an exit node. | ||
isAppConnector boolean |
IsAppConnector is set to true if the Connector acts as an app connector. | ||
tailnetIPs string array |
TailnetIPs is the set of tailnet IP addresses (both IPv4 and IPv6) assigned to the Connector node. |
||
hostname string |
Hostname is the fully qualified domain name of the Connector node. If MagicDNS is enabled in your tailnet, it is the MagicDNS name of the node. When using multiple replicas, this field will be populated with the first replica's hostname. Use the Hostnames field for the full list of hostnames. |
||
devices ConnectorDevice array |
Devices contains information on each device managed by the Connector resource. |
Container
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
env Env array |
List of environment variables to set in the container. https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#environment-variables Note that environment variables provided here will take precedence over Tailscale-specific environment variables set by the operator, however running proxies with custom values for Tailscale environment variables (i.e TS_USERSPACE) is not recommended and might break in the future. |
||
image string |
Container image name. By default images are pulled from docker.io/tailscale, but the official images are also available at ghcr.io/tailscale. For all uses except on ProxyGroups of type "kube-apiserver", this image must be either tailscale/tailscale, or an equivalent mirror of that image. To apply to ProxyGroups of type "kube-apiserver", this image must be tailscale/k8s-proxy or a mirror of that image. For "tailscale/tailscale"-based proxies, specifying image name here will override any proxy image values specified via the Kubernetes operator's Helm chart values or PROXY_IMAGE env var in the operator Deployment. For "tailscale/k8s-proxy"-based proxies, there is currently no way to configure your own default, and this field is the only way to use a custom image. https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#image |
||
imagePullPolicy PullPolicy |
Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always. https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#image |
Enum: [Always Never IfNotPresent] |
|
resources ResourceRequirements |
Container resource requirements. By default Tailscale Kubernetes operator does not apply any resource requirements. The amount of resources required wil depend on the amount of resources the operator needs to parse, usage patterns and cluster size. https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#resources |
||
securityContext SecurityContext |
Container security context. Security context specified here will override the security context set by the operator. By default the operator sets the Tailscale container and the Tailscale init container to privileged for proxies created for Tailscale ingress and egress Service, Connector and ProxyGroup. You can reduce the permissions of the Tailscale container to cap NET_ADMIN by installing device plugin in your cluster and configuring the proxies tun device to be created by the device plugin, see #10814 (comment) https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#security-context |
||
debug Debug |
Configuration for enabling extra debug information in the container. Not recommended for production use. |
DNSConfig
DNSConfig can be deployed to cluster to make a subset of Tailscale MagicDNS names resolvable by cluster workloads. Use this if: A) you need to refer to tailnet services, exposed to cluster via Tailscale Kubernetes operator egress proxies by the MagicDNS names of those tailnet services (usually because the services run over HTTPS) B) you have exposed a cluster workload to the tailnet using Tailscale Ingress and you also want to refer to the workload from within the cluster over the Ingress's MagicDNS name (usually because you have some callback component that needs to use the same URL as that used by a non-cluster client on tailnet). When a DNSConfig is applied to a cluster, Tailscale Kubernetes operator will deploy a nameserver for ts.net DNS names and automatically populate it with records for any Tailscale egress or Ingress proxies deployed to that cluster. Currently you must manually update your cluster DNS configuration to add the IP address of the deployed nameserver as a ts.net stub nameserver. Instructions for how to do it: https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/#configuration-of-stub-domain-and-upstream-nameserver-using-coredns (for CoreDNS), https://cloud.google.com/kubernetes-engine/docs/how-to/kube-dns (for kube-dns). Tailscale Kubernetes operator will write the address of a Service fronting the nameserver to dsnconfig.status.nameserver.ip. DNSConfig is a singleton - you must not create more than one. NB: if you want cluster workloads to be able to refer to Tailscale Ingress using its MagicDNS name, you must also annotate the Ingress resource with tailscale.com/experimental-forward-cluster-traffic-via-ingress annotation to ensure that the proxy created for the Ingress listens on its Pod IP address.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
tailscale.com/v1alpha1 |
||
kind string |
DNSConfig |
||
kind string |
Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds |
||
apiVersion string |
APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec DNSConfigSpec |
Spec describes the desired DNS configuration. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status |
||
status DNSConfigStatus |
Status describes the status of the DNSConfig. This is set and managed by the Tailscale operator. |
DNSConfigList
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
tailscale.com/v1alpha1 |
||
kind string |
DNSConfigList |
||
kind string |
Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds |
||
apiVersion string |
APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources |
||
metadata ListMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
items DNSConfig array |
DNSConfigSpec
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
nameserver Nameserver |
Configuration for a nameserver that can resolve ts.net DNS names associated with in-cluster proxies for Tailscale egress Services and Tailscale Ingresses. The operator will always deploy this nameserver when a DNSConfig is applied. |
DNSConfigStatus
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
conditions Condition array |
|||
nameserver NameserverStatus |
Nameserver describes the status of nameserver cluster resources. |
Debug
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
enable boolean |
Enable tailscaled's HTTP pprof endpoints at :9001/debug/pprof/ and internal debug metrics endpoint at :9001/debug/metrics, where 9001 is a container port named "debug". The endpoints and their responses may change in backwards incompatible ways in the future, and should not be considered stable. In 1.78.x and 1.80.x, this setting will default to the value of .spec.metrics.enable, and requests to the "metrics" port matching the mux pattern /debug/ will be forwarded to the "debug" port. In 1.82.x, this setting will default to false, and no requests will be proxied. |
Env
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name Name
|
Name of the environment variable. Must be a C_IDENTIFIER. | Pattern: ^[-._a-zA-Z][-._a-zA-Z0-9]*$ Type: string |
|
value string
|
Variable references $(VAR_NAME) are expanded using the previously defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the |