cmd/k8s-operator,k8s-operator: document tailscale.com Custom Resource Definitions better. (#11665)

Updates tailscale/tailscale#10880

Signed-off-by: Irbe Krumina <irbe@tailscale.com>

cmd/k8s-operator/deploy/crds/tailscale.com_connectors.yaml

@@ -31,6 +31,7 @@ spec:
       name: v1alpha1
       schema:
         openAPIV3Schema:
+          description: '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'
           type: object
           required:
             - spec
@@ -44,7 +45,7 @@ spec:
             metadata:
               type: object
             spec:
-              description: ConnectorSpec describes the desired Tailscale component.
+              description: 'ConnectorSpec describes the desired Tailscale component. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status'
               type: object
               properties:
                 exitNode:

cmd/k8s-operator/deploy/crds/tailscale.com_proxyclasses.yaml

@@ -21,6 +21,7 @@ spec:
       name: v1alpha1
       schema:
         openAPIV3Schema:
+          description: '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=<proxyclass-name> 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.'
           type: object
           required:
             - spec
@@ -34,12 +35,13 @@ spec:
             metadata:
               type: object
             spec:
+              description: Specification of the desired state of the ProxyClass resource. https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
               type: object
               required:
                 - statefulSet
               properties:
                 statefulSet:
-                  description: Proxy's StatefulSet spec.
+                  description: 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).
                   type: object
                   properties:
                     annotations:
@@ -483,6 +485,7 @@ spec:
                                 description: Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string.
                                 type: string
             status:
+              description: 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
               type: object
               properties:
                 conditions:

cmd/k8s-operator/deploy/manifests/operator.yaml

@@ -60,6 +60,7 @@ spec:
           name: v1alpha1
           schema:
             openAPIV3Schema:
+                description: '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'
                 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'
@@ -70,7 +71,7 @@ spec:
                     metadata:
                         type: object
                     spec:
-                        description: ConnectorSpec describes the desired Tailscale component.
+                        description: 'ConnectorSpec describes the desired Tailscale component. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status'
                         properties:
                             exitNode:
                                 description: ExitNode defines whether the Connector node should act as a Tailscale exit node. Defaults to false. https://tailscale.com/kb/1103/exit-nodes
@@ -179,6 +180,7 @@ spec:
           name: v1alpha1
           schema:
             openAPIV3Schema:
+                description: '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=<proxyclass-name> 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.'
                 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'
@@ -189,9 +191,10 @@ spec:
                     metadata:
                         type: object
                     spec:
+                        description: Specification of the desired state of the ProxyClass resource. https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
                         properties:
                             statefulSet:
-                                description: Proxy's StatefulSet spec.
+                                description: 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).
                                 properties:
                                     annotations:
                                         additionalProperties:
@@ -638,6 +641,7 @@ spec:
                             - statefulSet
                         type: object
                     status:
+                        description: 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
                         properties:
                             conditions:
                                 description: List of status conditions to indicate the status of the ProxyClass. Known condition types are `ProxyClassReady`.

k8s-operator/api.md

@@ -23,7 +23,7 @@ Resource Types:
 
 
 
-
+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
 
 <table>
     <thead>
@@ -55,7 +55,7 @@ Resource Types:
         <td><b><a href="#connectorspec">spec</a></b></td>
         <td>object</td>
         <td>
-          ConnectorSpec describes the desired Tailscale component.<br/>
+          ConnectorSpec describes the desired Tailscale component. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status<br/>
           <br/>
             <i>Validations</i>:<li>has(self.subnetRouter) || self.exitNode == true: A Connector needs to be either an exit node or a subnet router, or both.</li>
         </td>
@@ -76,7 +76,7 @@ Resource Types:
 
 
 
-ConnectorSpec describes the desired Tailscale component.
+ConnectorSpec describes the desired Tailscale component. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
 
 <table>
     <thead>
@@ -267,7 +267,7 @@ ConnectorCondition contains condition information for a Connector.
 
 
 
-
+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=<proxyclass-name> 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.
 
 <table>
     <thead>
@@ -299,14 +299,14 @@ ConnectorCondition contains condition information for a Connector.
         <td><b><a href="#proxyclassspec">spec</a></b></td>
         <td>object</td>
         <td>
-          <br/>
+          Specification of the desired state of the ProxyClass resource. 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="#proxyclassstatus">status</a></b></td>
         <td>object</td>
         <td>
-          <br/>
+          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<br/>
         </td>
         <td>false</td>
       </tr></tbody>
@@ -318,7 +318,7 @@ ConnectorCondition contains condition information for a Connector.
 
 
 
-
+Specification of the desired state of the ProxyClass resource. https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
 
 <table>
     <thead>
@@ -333,7 +333,7 @@ ConnectorCondition contains condition information for a Connector.
         <td><b><a href="#proxyclassspecstatefulset">statefulSet</a></b></td>
         <td>object</td>
         <td>
-          Proxy's StatefulSet spec.<br/>
+          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).<br/>
         </td>
         <td>true</td>
       </tr></tbody>
@@ -345,7 +345,7 @@ ConnectorCondition contains condition information for a Connector.
 
 
 
-Proxy's StatefulSet spec.
+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).
 
 <table>
     <thead>
@@ -1638,7 +1638,7 @@ The pod this Toleration is attached to tolerates any taint that matches the trip
 
 
 
-
+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
 
 <table>
     <thead>

k8s-operator/apis/v1alpha1/types_connector.go

@@ -24,11 +24,19 @@ var ConnectorKind = "Connector"
 // +kubebuilder:printcolumn:name="IsExitNode",type="string",JSONPath=`.status.isExitNode`,description="Whether this Connector instance defines an exit node."
 // +kubebuilder:printcolumn:name="Status",type="string",JSONPath=`.status.conditions[?(@.type == "ConnectorReady")].reason`,description="Status of the deployed Connector resources."
 
+// 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
 type Connector struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
 	// ConnectorSpec describes the desired Tailscale component.
+	// More info:
+	// https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
 	Spec ConnectorSpec `json:"spec"`
 
 	// ConnectorStatus describes the status of the Connector. This is set

k8s-operator/apis/v1alpha1/types_proxyclass.go

@@ -17,13 +17,26 @@ var ProxyClassKind = "ProxyClass"
 // +kubebuilder:resource:scope=Cluster
 // +kubebuilder:printcolumn:name="Status",type="string",JSONPath=`.status.conditions[?(@.type == "ProxyClassReady")].reason`,description="Status of the 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=<proxyclass-name> 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.
 type ProxyClass struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
+	// Specification of the desired state of the ProxyClass resource.
+	// https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
 	Spec ProxyClassSpec `json:"spec"`
 
 	// +optional
+	// 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
 	Status ProxyClassStatus `json:"status"`
 }
 
@@ -36,7 +49,9 @@ type ProxyClassList struct {
 }
 
 type ProxyClassSpec struct {
-	// Proxy's StatefulSet spec.
+	// 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).
 	StatefulSet *StatefulSet `json:"statefulSet"`
 }