diff --git a/cmd/k8s-operator/deploy/crds/tailscale.com_dnsconfigs.yaml b/cmd/k8s-operator/deploy/crds/tailscale.com_dnsconfigs.yaml index 083c587b2..ad4977bb5 100644 --- a/cmd/k8s-operator/deploy/crds/tailscale.com_dnsconfigs.yaml +++ b/cmd/k8s-operator/deploy/crds/tailscale.com_dnsconfigs.yaml @@ -23,6 +23,7 @@ spec: name: v1alpha1 schema: openAPIV3Schema: + description: '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.' type: object required: - spec @@ -36,21 +37,27 @@ spec: metadata: type: object spec: + description: 'Spec describes the desired DNS configuration. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status' type: object required: - nameserver properties: nameserver: + description: 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. type: object properties: image: + description: Nameserver image. type: object properties: repo: + description: Repo defaults to tailscale/k8s-nameserver. type: string tag: + description: Tag defaults to operator's own tag. type: string status: + description: Status describes the status of the DNSConfig. This is set and managed by the Tailscale operator. type: object properties: conditions: @@ -86,9 +93,11 @@ spec: - type x-kubernetes-list-type: map nameserver: + description: Nameserver describes the status of nameserver cluster resources. type: object properties: ip: + description: 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. type: string served: true storage: true diff --git a/cmd/k8s-operator/deploy/examples/dnsconfig.yaml b/cmd/k8s-operator/deploy/examples/dnsconfig.yaml index eae6486db..ca9bf0f24 100644 --- a/cmd/k8s-operator/deploy/examples/dnsconfig.yaml +++ b/cmd/k8s-operator/deploy/examples/dnsconfig.yaml @@ -3,7 +3,4 @@ kind: DNSConfig metadata: name: ts-dns spec: - nameserver: - image: - repo: tailscale/k8s-nameserver - tag: unstable-v1.65 + nameserver: {} diff --git a/cmd/k8s-operator/deploy/manifests/operator.yaml b/cmd/k8s-operator/deploy/manifests/operator.yaml index 3f5fe4951..d637d2d46 100644 --- a/cmd/k8s-operator/deploy/manifests/operator.yaml +++ b/cmd/k8s-operator/deploy/manifests/operator.yaml @@ -190,6 +190,7 @@ spec: name: v1alpha1 schema: openAPIV3Schema: + description: '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.' properties: apiVersion: description: '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' @@ -200,14 +201,19 @@ spec: metadata: type: object spec: + description: 'Spec describes the desired DNS configuration. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status' properties: nameserver: + description: 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. properties: image: + description: Nameserver image. properties: repo: + description: Repo defaults to tailscale/k8s-nameserver. type: string tag: + description: Tag defaults to operator's own tag. type: string type: object type: object @@ -215,6 +221,7 @@ spec: - nameserver type: object status: + description: Status describes the status of the DNSConfig. This is set and managed by the Tailscale operator. properties: conditions: items: @@ -249,8 +256,10 @@ spec: - type x-kubernetes-list-type: map nameserver: + description: Nameserver describes the status of nameserver cluster resources. properties: ip: + description: 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. type: string type: object type: object diff --git a/k8s-operator/api.md b/k8s-operator/api.md index f15bd3577..0e1b0d8cc 100644 --- a/k8s-operator/api.md +++ b/k8s-operator/api.md @@ -283,7 +283,7 @@ ConnectorCondition contains condition information for a Connector. - +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. @@ -315,14 +315,14 @@ ConnectorCondition contains condition information for a Connector. @@ -334,7 +334,7 @@ ConnectorCondition contains condition information for a Connector. - +Spec describes the desired DNS configuration. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
spec object -
+ Spec describes the desired DNS configuration. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
 true
status object -
+ Status describes the status of the DNSConfig. This is set and managed by the Tailscale operator.
 false
@@ -349,7 +349,7 @@ ConnectorCondition contains condition information for a Connector. @@ -361,7 +361,7 @@ ConnectorCondition contains condition information for a Connector. - +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.
nameserver object -
+ 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.
 true
@@ -376,7 +376,7 @@ ConnectorCondition contains condition information for a Connector. @@ -388,7 +388,7 @@ ConnectorCondition contains condition information for a Connector. - +Nameserver image.
image object -
+ Nameserver image.
 false
@@ -403,14 +403,14 @@ ConnectorCondition contains condition information for a Connector. @@ -422,7 +422,7 @@ ConnectorCondition contains condition information for a Connector. - +Status describes the status of the DNSConfig. This is set and managed by the Tailscale operator.
repo string -
+ Repo defaults to tailscale/k8s-nameserver.
 false
tag string -
+ Tag defaults to operator's own tag.
 false
@@ -444,7 +444,7 @@ ConnectorCondition contains condition information for a Connector. @@ -522,7 +522,7 @@ ConnectorCondition contains condition information for a Connector. - +Nameserver describes the status of nameserver cluster resources.
nameserver object -
+ Nameserver describes the status of nameserver cluster resources.
 false
@@ -537,7 +537,7 @@ ConnectorCondition contains condition information for a Connector. diff --git a/k8s-operator/apis/v1alpha1/types_tsdnsconfig.go b/k8s-operator/apis/v1alpha1/types_tsdnsconfig.go index 62dad3f68..75f5503b2 100644 --- a/k8s-operator/apis/v1alpha1/types_tsdnsconfig.go +++ b/k8s-operator/apis/v1alpha1/types_tsdnsconfig.go @@ -19,12 +19,43 @@ var DNSConfigKind = "DNSConfig" // +kubebuilder:resource:scope=Cluster,shortName=dc // +kubebuilder:printcolumn:name="NameserverIP",type="string",JSONPath=`.status.nameserver.ip`,description="Service IP address of the nameserver" +// 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. type DNSConfig struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` + // Spec describes the desired DNS configuration. + // More info: + // https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status Spec DNSConfigSpec `json:"spec"` + // Status describes the status of the DNSConfig. This is set + // and managed by the Tailscale operator. // +optional Status DNSConfigStatus `json:"status"` } @@ -39,17 +70,24 @@ type DNSConfigList struct { } type DNSConfigSpec struct { + // 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. Nameserver *Nameserver `json:"nameserver"` } type Nameserver struct { + // Nameserver image. // +optional Image *Image `json:"image,omitempty"` } type Image struct { + // Repo defaults to tailscale/k8s-nameserver. // +optional Repo string `json:"repo,omitempty"` + // Tag defaults to operator's own tag. // +optional Tag string `json:"tag,omitempty"` } @@ -59,13 +97,22 @@ type DNSConfigStatus struct { // +listMapKey=type // +optional Conditions []ConnectorCondition `json:"conditions"` + // Nameserver describes the status of nameserver cluster resources. // +optional Nameserver *NameserverStatus `json:"nameserver"` } type NameserverStatus struct { + // 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. // +optional IP string `json:"ip"` } +// NameserverReady is set to True if the nameserver has been successfully +// deployed to cluster. const NameserverReady ConnectorConditionType = `NameserverReady`
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.
 false