Add documentation for CRD source

docs/contributing/crd-source.md

@@ -0,0 +1,104 @@
+# CRD Source
+
+CRD source provides a generic mechanism to manage DNS records in your favourite DNS provider supported by external-dns.
+
+### Details
+
+CRD source watches for a user specified CRD to extract [Endpoints](https://github.com/kubernetes-incubator/external-dns/blob/master/endpoint/endpoint.go) from its `Spec`.
+So users need to create such a CRD and register it to the kubernetes cluster and then create new object(s) of the CRD specifying the Endpoints.
+
+### Registering CRD
+
+Here is typical example of [CRD API type](https://github.com/kubernetes-incubator/external-dns/blob/master/endpoint/endpoint.go) which provides Endpoints to `CRD source`:
+
+```go
+type TTL int64
+type Targets []string
+type ProviderSpecific map[string]string
+
+type Endpoint struct {
+	// The hostname of the DNS record
+	DNSName string `json:"dnsName,omitempty"`
+	// The targets the DNS record points to
+	Targets Targets `json:"targets,omitempty"`
+	// RecordType type of record, e.g. CNAME, A, SRV, TXT etc
+	RecordType string `json:"recordType,omitempty"`
+	// TTL for the record
+	RecordTTL TTL `json:"recordTTL,omitempty"`
+	// Labels stores labels defined for the Endpoint
+	// +optional
+	Labels Labels `json:"labels,omitempty"`
+	// ProviderSpecific stores provider specific config
+	// +optional
+	ProviderSpecific ProviderSpecific `json:"providerSpecific,omitempty"`
+}
+
+type DNSEndpointSpec struct {
+	Endpoints []*Endpoint `json:"endpoints,omitempty"`
+}
+
+type DNSEndpointStatus struct {
+	// The generation observed by the external-dns controller.
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+}
+
+// +genclient
+// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// DNSEndpoint is the CRD wrapper for Endpoint
+// +k8s:openapi-gen=true
+// +kubebuilder:resource:path=dnsendpoints
+// +kubebuilder:subresource:status
+type DNSEndpoint struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   DNSEndpointSpec   `json:"spec,omitempty"`
+	Status DNSEndpointStatus `json:"status,omitempty"`
+}
+
+```
+
+Refer to [kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) to create and register the CRD.
+
+### Usage
+
+One can use CRD source by specifying `--source` flag with `crd` and specifying the ApiVersion and Kind of the CRD with `--crd-source-apiversion` and `crd-source-kind` respectively.
+for e.g:
+
+```
+$ build/external-dns --source crd --crd-source-apiversion externaldns.k8s.io/v1alpha1  --crd-source-kind DNSEndpoint --provider inmemory --once --dry-run
+```
+
+### Creating DNS Records
+
+Create the objects of CRD type by filling in the fields of CRD and DNS record would be created accordingly.
+
+### Example
+
+Here is an example [CRD manifest](crd-source/crd-manifest.yaml) generated by kubebuilder.
+Apply this to register the CRD
+
+```
+$ kubectl apply --validate=false -f docs/contributing/crd-source/crd-manifest.yaml
+customresourcedefinition.apiextensions.k8s.io "dnsendpoints.externaldns.k8s.io" created
+```
+
+Then you can create the dns-endpoint yaml similar to [dnsendpoint-example](crd-source/dnsendpoint-example.yaml)
+
+```
+$ kubectl apply -f docs/contributing/crd-source/dnsendpoint-example.yaml
+dnsendpoint.externaldns.k8s.io "examplednsrecord" created
+```
+
+Run external-dns in dry-mode to see whether external-dns picks up the DNS record from CRD.
+
+```
+$ build/external-dns --source crd --crd-source-apiversion externaldns.k8s.io/v1alpha1  --crd-source-kind DNSEndpoint --provider inmemory --once --dry-run
+INFO[0000] config: {Master: KubeConfig: Sources:[crd] Namespace: AnnotationFilter: FQDNTemplate: CombineFQDNAndAnnotation:false Compatibility: PublishInternal:false PublishHostIP:false ConnectorSourceServer:localhost:8080 Provider:inmemory GoogleProject: DomainFilter:[] ZoneIDFilter:[] AWSZoneType: AWSAssumeRole: AWSMaxChangeCount:4000 AWSEvaluateTargetHealth:true AzureConfigFile:/etc/kubernetes/azure.json AzureResourceGroup: CloudflareProxied:false InfobloxGridHost: InfobloxWapiPort:443 InfobloxWapiUsername:admin InfobloxWapiPassword: InfobloxWapiVersion:2.3.1 InfobloxSSLVerify:true DynCustomerName: DynUsername: DynPassword: DynMinTTLSeconds:0 OCIConfigFile:/etc/kubernetes/oci.yaml InMemoryZones:[] PDNSServer:http://localhost:8081 PDNSAPIKey: PDNSTLSEnabled:false TLSCA: TLSClientCert: TLSClientCertKey: Policy:sync Registry:txt TXTOwnerID:default TXTPrefix: Interval:1m0s Once:true DryRun:true LogFormat:text MetricsAddress::7979 LogLevel:info TXTCacheInterval:0s ExoscaleEndpoint:https://api.exoscale.ch/dns ExoscaleAPIKey: ExoscaleAPISecret: CRDSourceAPIVersion:externaldns.k8s.io/v1alpha1 CRDSourceKind:DNSEndpoint}
+INFO[0000] running in dry-run mode. No changes to DNS records will be made.
+INFO[0000] Connected to cluster at https://192.168.99.100:8443
+INFO[0000] CREATE: foo.bar.com 180 IN A 192.168.99.216
+INFO[0000] CREATE: foo.bar.com 0 IN TXT "heritage=external-dns,external-dns/owner=default"
+```

docs/contributing/crd-source/crd-manifest.yaml

@@ -0,0 +1,60 @@
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  creationTimestamp: null
+  labels:
+    api: externaldns
+    kubebuilder.k8s.io: 1.0.0
+  name: dnsendpoints.externaldns.k8s.io
+spec:
+  group: externaldns.k8s.io
+  names:
+    kind: DNSEndpoint
+    plural: dnsendpoints
+  scope: Namespaced
+  subresources:
+    status: {}
+  validation:
+    openAPIV3Schema:
+      properties:
+        apiVersion:
+          type: string
+        kind:
+          type: string
+        metadata:
+          type: object
+        spec:
+          properties:
+            endpoints:
+              items:
+                properties:
+                  dnsName:
+                    type: string
+                  labels:
+                    type: object
+                  providerSpecific:
+                    type: object
+                  recordTTL:
+                    format: int64
+                    type: integer
+                  recordType:
+                    type: string
+                  targets:
+                    items:
+                      type: string
+                    type: array
+                type: object
+              type: array
+          type: object
+        status:
+          properties:
+            observedGeneration:
+              format: int64
+              type: integer
+          type: object
+  version: v1alpha1
+status:
+  acceptedNames:
+    kind: ""
+    plural: ""
+  conditions: null

docs/contributing/crd-source/dnsendpoint-example.yaml

@@ -0,0 +1,11 @@
+apiVersion: externaldns.k8s.io/v1alpha1
+kind: DNSEndpoint
+metadata:
+  name: examplednsrecord
+spec:
+  endpoints:
+  - dnsName: foo.bar.com
+    recordTTL: 180
+    recordType: A
+    targets:
+    - 192.168.99.216

docs/contributing/sources-and-providers.md

@@ -23,6 +23,7 @@ All sources live in package `source`.
 * `IngressSource`: collects all Ingresses that have an external IP and returns them as Endpoint objects. The desired DNS name corresponds to the host rules defined in the Ingress object.
 * `FakeSource`: returns a random list of Endpoints for the purpose of testing providers without having access to a Kubernetes cluster.
 * `ConnectorSource`: returns a list of Endpoint objects which are served by a tcp server configured through `connector-source-server` flag.
+* `CRDSource`: returns a list of Endpoint objects sourced from the spec of CRD objects. For more details refer to [CRD source](../crd-source.md) documentation.
 
 ### Providers