Add docs for ExternalName services

docs/faq.md

@@ -50,7 +50,7 @@ As stated in the README, we are currently looking for stable maintainers for tho
 
 ### Which Kubernetes objects are supported?
 
-Services exposed via `type=LoadBalancer` and for the hostnames defined in Ingress objects as well as headless hostPort services. An initial effort to support type `NodePort` was started as of May 2018 and it is in progress at the time of writing.
+Services exposed via `type=LoadBalancer`, `type=ExternalName` and for the hostnames defined in Ingress objects as well as headless hostPort services. An initial effort to support type `NodePort` was started as of May 2018 and it is in progress at the time of writing.
 
 ### How do I specify a DNS name for my Kubernetes objects?
 
@@ -160,13 +160,13 @@ CNAMEs cannot co-exist with other records, therefore you can use the `--txt-pref
 
 You need to add either https://www.googleapis.com/auth/ndev.clouddns.readwrite or https://www.googleapis.com/auth/cloud-platform on your instance group's scope.
 
-### What metrics can I get from ExternalDNS and what do they mean?  
+### What metrics can I get from ExternalDNS and what do they mean?
 
 ExternalDNS exposes 2 types of metrics: Sources and Registry errors.
 
 `Source`s are mostly Kubernetes API objects. Examples of `source` errors may be connection errors to the Kubernetes API server itself or missing RBAC permissions. It can also stem from incompatible configuration in the objects itself like invalid characters, processing a broken fqdnTemplate, etc.
 
-`Registry` errors are mostly Provider errors, unless there's some coding flaw in the registry package. Provider errors often arise due to accessing their APIs due to network or missing cloud-provider permissions when reading records. When applying a changeset, errors will arise if the changeset applied is incompatible with the current state.  
+`Registry` errors are mostly Provider errors, unless there's some coding flaw in the registry package. Provider errors often arise due to accessing their APIs due to network or missing cloud-provider permissions when reading records. When applying a changeset, errors will arise if the changeset applied is incompatible with the current state.
 
 In case of an increased error count, you could correlate them with the `http_request_duration_seconds{handler="instrumented_http"}` metric which should show increased numbers for status codes 4xx (permissions, configuration, invalid changeset) or 5xx (apiserver down).
 

docs/tutorials/externalname.md

@@ -0,0 +1,76 @@
+# Setting up ExternalDNS for ExternalName Services
+
+This tutorial describes how to setup ExternalDNS for usage in conjunction with an ExternalName service.
+
+## Usecases
+
+The main use cases that inspired this feature is the necessity for having a subdomain pointing to an external domain. In this scenario, it makes sense for the subdomain to have a CNAME record pointing to the external domain.
+
+## Setup
+
+### External DNS
+```yaml
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  name: external-dns
+spec:
+  strategy:
+    type: Recreate
+  template:
+    spec:
+      containers:
+      - name: external-dns
+        image: registry.opensource.zalan.do/teapot/external-dns:latest
+        args:
+        - --debug
+        - --source=service
+        - --source=ingress
+        - --namespace=dev
+        - --domain-filter=example.org.
+        - --provider=aws
+        - --registry=txt
+        - --txt-owner-id=dev.example.org
+```
+
+### ExternalName Service
+
+```yaml
+kind: Service
+apiVersion: v1
+metadata:
+  name: aws-service
+  annotations:
+    external-dns.alpha.kubernetes.io/hostname: tenant1.example.org,tenant2.example.org
+spec:
+  type: ExternalName
+  externalName: aws.external.com
+```
+
+This will create 2 CNAME records pointing to `aws.example.org`:
+```
+tenant1.example.org
+tenant2.example.org
+```
+
+### ExternalName Service with an IP address
+
+If `externalName` is an IP address, External DNS will create A records instead of CNAME.
+
+```yaml
+kind: Service
+apiVersion: v1
+metadata:
+  name: aws-service
+  annotations:
+    external-dns.alpha.kubernetes.io/hostname: tenant1.example.org,tenant2.example.org
+spec:
+  type: ExternalName
+  externalName: 111.111.111.111
+```
+
+This will create 2 A records pointing to `111.111.111.111`:
+```
+tenant1.example.org
+tenant2.example.org
+```