sigs.k8s.io/external-dns@v0.14.1/docs/contributing/sources-and-providers.md (about)

     1  # Sources and Providers
     2  
     3  ExternalDNS supports swapping out endpoint **sources** and DNS **providers** and both sides are pluggable. There currently exist three sources and four provider implementations.
     4  
     5  ### Sources
     6  
     7  Sources are an abstraction over any kind of source of desired Endpoints, e.g.:
     8  * a list of Service objects from Kubernetes
     9  * a random list for testing purposes
    10  * an aggregated list of multiple nested sources
    11  
    12  The `Source` interface has a single method called `Endpoints` that should return all desired Endpoint objects as a flat list.
    13  
    14  ```go
    15  type Source interface {
    16  	Endpoints() ([]*endpoint.Endpoint, error)
    17  }
    18  ```
    19  
    20  All sources live in package `source`.
    21  
    22  * `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.
    23  * `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.
    24  * `IstioGatewaySource`: collects all Istio Gateways and returns them as Endpoint objects. The desired DNS name corresponds to the hosts listed within the servers spec of each Gateway object.
    25  * `ContourIngressRouteSource`: collects all Contour IngressRoutes and returns them as Endpoint objects. The desired DNS name corresponds to the `virtualhost.fqdn` listed within the spec of each IngressRoute object.
    26  * `FakeSource`: returns a random list of Endpoints for the purpose of testing providers without having access to a Kubernetes cluster.
    27  * `ConnectorSource`: returns a list of Endpoint objects which are served by a tcp server configured through `connector-source-server` flag.
    28  * `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.
    29  * `EmptySource`: returns an empty list of Endpoint objects for the purpose of testing and cleaning out entries.
    30  
    31  ### Providers
    32  
    33  Providers are an abstraction over any kind of sink for desired Endpoints, e.g.:
    34  * storing them in Google Cloud DNS
    35  * printing them to stdout for testing purposes
    36  * fanning out to multiple nested providers
    37  
    38  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.
    39  
    40  ```go
    41  type Provider interface {
    42  	Records() ([]*endpoint.Endpoint, error)
    43  	ApplyChanges(changes *plan.Changes) error
    44  }
    45  ```
    46  
    47  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.
    48  
    49  All providers live in package `provider`.
    50  
    51  * `GoogleProvider`: returns and creates DNS records in Google Cloud DNS
    52  * `AWSProvider`: returns and creates DNS records in AWS Route 53
    53  * `AzureProvider`: returns and creates DNS records in Azure DNS
    54  * `InMemoryProvider`: Keeps a list of records in local memory
    55  
    56  ### Usage
    57  
    58  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.