docs: explain the concept behind sources and providers (#226)

* docs(contributing): explain the concept behind sources and providers

* docs(contributing): we don't filter Services by type

README.md

@@ -124,6 +124,8 @@ Have a look at [the milestones](https://github.com/kubernetes-incubator/external
 
 We encourage you to get involved with ExternalDNS, as users as well as contributors. Read the [contributing guidelines](CONTRIBUTING.md) and have a look at [the contributing docs](docs/contributing/getting-started.md) to learn about building the project, the project structure, and the purpose of each package.
 
+For an overview on how to write new Sources and Providers check out [Sources and Providers](docs/contributing/sources-and-providers.md).
+
 Feel free to reach out to us on the [Kubernetes slack](http://slack.k8s.io) in the #sig-network channel.
 
 ## Heritage

docs/contributing/sources-and-providers.md

@@ -0,0 +1,53 @@
+# Sources and Providers
+
+ExternalDNS supports swapping out endpoint **sources** and DNS **providers** and both sides are pluggable. There currently exist three sources and four provider implementations.
+
+### Sources
+
+Sources are an abstraction over any kind of source of desired Endpoints, e.g.:
+* a list of Service objects from Kubernetes
+* a random list for testing purposes
+* an aggregated list of multiple nested sources
+
+The `Source` interface has a single method called `Endpoints` that should return all desired Endpoint objects as a flat list.
+
+```go
+type Source interface {
+	Endpoints() ([]*endpoint.Endpoint, error)
+}
+```
+
+All sources live in package `source`.
+
+* `ServiceSource`: collects all Services that have an external IP and returns them as Endpoint objects. The desired DNS name corresponds to an annotation set on the Service or is compiled from the Service attributes via the FQDN Go template string.
+* `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.
+
+### Providers
+
+Providers are an abstraction over any kind of sink for desired Endpoints, e.g.:
+* storing them in Google CloudDNS
+* printing them to stdout for testing purposes
+* fanning out to multiple nested providers
+
+The `Provider` interface has two methods: `Records` and `ApplyChanges`. `Records` should return all currently existing DNS records converted to Endpoint objects as a flat list. Upon receiving a change set (via an object of `plan.Changes`), `ApplyChanges` should translate these to the provider specific actions in order to persist them in the provider's storage.
+
+```go
+type Provider interface {
+	Records() ([]*endpoint.Endpoint, error)
+	ApplyChanges(changes *plan.Changes) error
+}
+```
+
+The interface tries to be generic and assumes a flat list of records for both functions. However, many providers scope records into zones. Therefore, the provider implementation has to do some extra work to return that flat list. For instance, the AWS provider fetches the list of all hosted zones before it can return or apply the list of records. If the provider has no concept of zones or if it makes sense to cache the list of hosted zones it is happily allowed to do so. Furthermore, the provider should respect the `--domain-filter` flag to limit the affected records by a domain suffix. For instance, the AWS provider filters out all hosted zones that doesn't match that domain filter.
+
+All providers live in package `provider`.
+
+* `GoogleProvider`: returns and creates DNS records in Google CloudDNS
+* `AWSProvider`: returns and creates DNS records in AWS Route 53
+* `AzureProvider`: returns and creates DNS records in Azure DNS
+* `InMemoryProvider`: Keeps a list of records in local memory
+
+### Usage
+
+You can choose any combination of sources and providers on the command line. Given a cluster on AWS you would most likely want to use the Service and Ingress Source in combination with the AWS provider. `Service` + `InMemory` is useful for testing your service collecting functionality, whereas `Fake` + `Google` is useful for testing that the Google provider behaves correctly, etc.