Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

k8s-operator/apis/v1alpha1: update DNSConfig CRD description #11971

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+80 −18
Open

k8s-operator/apis/v1alpha1: update DNSConfig CRD description #11971

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
9 changes: 9 additions & 0 deletions cmd/k8s-operator/deploy/crds/tailscale.com_dnsconfigs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: IPv6 only clusters are currently not supported.'
type: object
required:
- spec
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand Down
5 changes: 1 addition & 4 deletions cmd/k8s-operator/deploy/examples/dnsconfig.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,4 @@ kind: DNSConfig
metadata:
name: ts-dns
spec:
nameserver:
image:
repo: tailscale/k8s-nameserver
tag: unstable-v1.65
nameserver: {}
9 changes: 9 additions & 0 deletions cmd/k8s-operator/deploy/manifests/operator.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,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: IPv6 only clusters 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'
Expand All @@ -192,21 +193,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'
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
required:
- nameserver
type: object
status:
description: Status describes the status of the DNSConfig. This is set and managed by the Tailscale operator.
properties:
conditions:
items:
Expand Down Expand Up @@ -241,8 +248,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
Expand Down
28 changes: 14 additions & 14 deletions k8s-operator/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -269,7 +269,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: IPv6 only clusters are currently not supported.

<table>
<thead>
Expand Down Expand Up @@ -301,14 +301,14 @@ ConnectorCondition contains condition information for a Connector.
<td><b><a href="#dnsconfigspec">spec</a></b></td>
<td>object</td>
<td>
<br/>
Spec describes the desired DNS configuration. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status<br/>
</td>
<td>true</td>
</tr><tr>
<td><b><a href="#dnsconfigstatus">status</a></b></td>
<td>object</td>
<td>
<br/>
Status describes the status of the DNSConfig. This is set and managed by the Tailscale operator.<br/>
</td>
<td>false</td>
</tr></tbody>
Expand All @@ -320,7 +320,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

<table>
<thead>
Expand All @@ -335,7 +335,7 @@ ConnectorCondition contains condition information for a Connector.
<td><b><a href="#dnsconfigspecnameserver">nameserver</a></b></td>
<td>object</td>
<td>
<br/>
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.<br/>
</td>
<td>true</td>
</tr></tbody>
Expand All @@ -347,7 +347,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.

<table>
<thead>
Expand All @@ -362,7 +362,7 @@ ConnectorCondition contains condition information for a Connector.
<td><b><a href="#dnsconfigspecnameserverimage">image</a></b></td>
<td>object</td>
<td>
<br/>
Nameserver image.<br/>
</td>
<td>false</td>
</tr></tbody>
Expand All @@ -374,7 +374,7 @@ ConnectorCondition contains condition information for a Connector.




Nameserver image.

<table>
<thead>
Expand All @@ -389,14 +389,14 @@ ConnectorCondition contains condition information for a Connector.
<td><b>repo</b></td>
<td>string</td>
<td>
<br/>
Repo defaults to tailscale/k8s-nameserver.<br/>
</td>
<td>false</td>
</tr><tr>
<td><b>tag</b></td>
<td>string</td>
<td>
<br/>
Tag defaults to operator's own tag.<br/>
</td>
<td>false</td>
</tr></tbody>
Expand All @@ -408,7 +408,7 @@ ConnectorCondition contains condition information for a Connector.




Status describes the status of the DNSConfig. This is set and managed by the Tailscale operator.

<table>
<thead>
Expand All @@ -430,7 +430,7 @@ ConnectorCondition contains condition information for a Connector.
<td><b><a href="#dnsconfigstatusnameserver">nameserver</a></b></td>
<td>object</td>
<td>
<br/>
Nameserver describes the status of nameserver cluster resources.<br/>
</td>
<td>false</td>
</tr></tbody>
Expand Down Expand Up @@ -508,7 +508,7 @@ ConnectorCondition contains condition information for a Connector.




Nameserver describes the status of nameserver cluster resources.

<table>
<thead>
Expand All @@ -523,7 +523,7 @@ ConnectorCondition contains condition information for a Connector.
<td><b>ip</b></td>
<td>string</td>
<td>
<br/>
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.<br/>
</td>
<td>false</td>
</tr></tbody>
Expand Down
47 changes: 47 additions & 0 deletions k8s-operator/apis/v1alpha1/types_tsdnsconfig.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: IPv6 only clusters 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"`
}
Expand All @@ -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"`
}
Expand All @@ -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`