diff --git a/docs/faq.md b/docs/faq.md index 1c92dd4e6..8f35e0395 100644 --- a/docs/faq.md +++ b/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). diff --git a/docs/tutorials/externalname.md b/docs/tutorials/externalname.md new file mode 100644 index 000000000..6f9e724f7 --- /dev/null +++ b/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 +```