mirrors
/
tailscale
mirror of https://github.com/tailscale/tailscale.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
tailscale/k8s-operator/api.md

27 KiB
Raw Blame History

API Reference

Packages

tailscale.com/v1alpha1

Resource Types

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/1236/kubernetes-operator#deploying-exit-nodes-and-subnet-routers-on-kubernetes-using-connector-custom-resource

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.

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/1018/acls/#auto-approvers-for-routes-and-exit-nodes.
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.		 Pattern: ^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$
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 node should
expose to tailnet. If unset, none are exposed.
https://tailscale.com/kb/1019/subnets/
exitNode boolean ExitNode defines whether the Connector node should act as a
Tailscale exit node. Defaults to false.
https://tailscale.com/kb/1103/exit-nodes

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

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/tailscale, but the official images are also
available at ghcr.io/tailscale/tailscale. 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.
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 by the operator.
By default the operator:
- sets 'privileged: true' for the init container
- set NET_ADMIN capability for tailscale container for proxies that
are created for Services or Connector.
https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#security-context

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. NB: Clusters where Pods get assigned IPv6 addresses only are currently not supported.

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.

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<br /> environment variables in the container and any service environment<br />variables. If a variable cannot be resolved, the reference in the input<br />string will be unchanged. Double are reduced to a single, which
allows for escaping the (VAR_NAME) syntax: i.e. "(VAR_NAME)" will<br />produce the string literal "(VAR_NAME)". Escaped references will never
be expanded, regardless of whether the variable exists or not. Defaults
to "".

Hostname

Underlying type: string

Validation:

  • Pattern: ^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$
  • Type: string

Appears in:

Image

Appears in:

Field Description Default Validation
repo string Repo defaults to tailscale/k8s-nameserver.
tag string Tag defaults to operator's own tag.

Metrics

Appears in:

Field Description Default Validation
enable boolean Setting enable to true will make the proxy serve Tailscale metrics
at :9001/debug/metrics.
Defaults to false.

Name

Underlying type: string

Validation:

  • Pattern: ^[-._a-zA-Z][-._a-zA-Z0-9]*$
  • Type: string

Appears in:

Nameserver

Appears in:

Field Description Default Validation
image Image Nameserver image.

NameserverStatus

Appears in:

Field Description Default Validation
ip string IP is the ClusterIP of the Service fronting the deployed ts.net nameserver.
Currently you must manually update your cluster DNS config to add
this address as a stub nameserver for ts.net for cluster workloads to be
able to resolve MagicDNS names associated with egress or Ingress
proxies.
The IP address will change if you delete and recreate the DNSConfig.

Pod

Appears in:

Field Description Default Validation
labels object (keys:string, values:string) Labels that will be added to the proxy Pod.
Any labels specified here will be merged with the default labels
applied to the Pod by the Tailscale Kubernetes operator.
Label keys and values must be valid Kubernetes label keys and values.
https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set
annotations object (keys:string, values:string) Annotations that will be added to the proxy Pod.
Any annotations specified here will be merged with the default
annotations applied to the Pod by the Tailscale Kubernetes operator.
Annotations must be valid Kubernetes annotations.
https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/#syntax-and-character-set
affinity Affinity Proxy Pod's affinity rules.
By default, the Tailscale Kubernetes operator does not apply any affinity rules.
https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#affinity
tailscaleContainer Container Configuration for the proxy container running tailscale.
tailscaleInitContainer Container Configuration for the proxy init container that enables forwarding.
securityContext PodSecurityContext Proxy Pod's security context.
By default Tailscale Kubernetes operator does not apply any Pod
security context.
https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#security-context-2
imagePullSecrets LocalObjectReference array Proxy Pod's image pull Secrets.
https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec
nodeName string Proxy Pod's node name.
https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling
nodeSelector object (keys:string, values:string) Proxy Pod's node selector.
By default Tailscale Kubernetes operator does not apply any node
selector.
https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling
tolerations Toleration array Proxy Pod's tolerations.
By default Tailscale Kubernetes operator does not apply any
tolerations.
https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling

ProxyClass

ProxyClass describes a set of configuration parameters that can be applied to proxy resources created by the Tailscale Kubernetes operator. To apply a given ProxyClass to resources created for a tailscale Ingress or Service, use tailscale.com/proxy-class= label. To apply a given ProxyClass to resources created for a Connector, use connector.spec.proxyClass field. ProxyClass is a cluster scoped resource. More info: https://tailscale.com/kb/1236/kubernetes-operator#cluster-resource-customization-using-proxyclass-custom-resource.

Appears in:

Field Description Default Validation
apiVersion string tailscale.com/v1alpha1
kind string ProxyClass
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 ProxyClassSpec Specification of the desired state of the ProxyClass resource.
https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
status ProxyClassStatus Status of the ProxyClass. This is set and managed automatically.
https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

ProxyClassList

Field Description Default Validation
apiVersion string tailscale.com/v1alpha1
kind string ProxyClassList
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 ProxyClass array

ProxyClassSpec

Appears in:

Field Description Default Validation
statefulSet StatefulSet Configuration parameters for the proxy's StatefulSet. Tailscale
Kubernetes operator deploys a StatefulSet for each of the user
configured proxies (Tailscale Ingress, Tailscale Service, Connector).
metrics Metrics Configuration for proxy metrics. Metrics are currently not supported
for egress proxies and for Ingress proxies that have been configured
with tailscale.com/experimental-forward-cluster-traffic-via-ingress
annotation. Note that the metrics are currently considered unstable
and will likely change in breaking ways in the future - we only
recommend that you use those for debugging purposes.
tailscale TailscaleConfig TailscaleConfig contains options to configure the tailscale-specific
parameters of proxies.

ProxyClassStatus

Appears in:

Field Description Default Validation
conditions Condition array List of status conditions to indicate the status of the ProxyClass.
Known condition types are ProxyClassReady.

Route

Underlying type: string

Validation:

  • Format: cidr
  • Type: string

Appears in:

Routes

Underlying type: Route

Validation:

  • Format: cidr
  • MinItems: 1
  • Type: string

Appears in:

StatefulSet

Appears in:

Field Description Default Validation
labels object (keys:string, values:string) Labels that will be added to the StatefulSet created for the proxy.
Any labels specified here will be merged with the default labels
applied to the StatefulSet by the Tailscale Kubernetes operator as
well as any other labels that might have been applied by other
actors.
Label keys and values must be valid Kubernetes label keys and values.
https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set
annotations object (keys:string, values:string) Annotations that will be added to the StatefulSet created for the proxy.
Any Annotations specified here will be merged with the default annotations
applied to the StatefulSet by the Tailscale Kubernetes operator as
well as any other annotations that might have been applied by other
actors.
Annotations must be valid Kubernetes annotations.
https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/#syntax-and-character-set
pod Pod Configuration for the proxy Pod.

SubnetRouter

SubnetRouter defines subnet routes that should be exposed to tailnet via a Connector node.

Appears in:

Field Description Default Validation
advertiseRoutes Routes AdvertiseRoutes refer to CIDRs that the subnet router should make
available. Route values must be strings that represent a valid IPv4
or IPv6 CIDR range. Values can be Tailscale 4via6 subnet routes.
https://tailscale.com/kb/1201/4via6-subnets/		 Format: cidr
MinItems: 1
Type: string

Tag

Underlying type: string

Validation:

  • Pattern: ^tag:[a-zA-Z][a-zA-Z0-9-]*$
  • Type: string

Appears in:

Tags

Underlying type: Tag

Validation:

  • Pattern: ^tag:[a-zA-Z][a-zA-Z0-9-]*$
  • Type: string

Appears in:

TailscaleConfig

Appears in:

Field Description Default Validation
acceptRoutes boolean AcceptRoutes can be set to true to make the proxy instance accept
routes advertized by other nodes on the tailnet, such as subnet
routes.
This is equivalent of passing --accept-routes flag to a tailscale Linux client.
https://tailscale.com/kb/1019/subnets#use-your-subnet-routes-from-other-machines
Defaults to false.