Document SafeDNS provider

README.md

@@ -52,6 +52,7 @@ ExternalDNS' allows you to keep selected zones (via `--domain-filter`) synchroni
 * [Akamai Edge DNS](https://learn.akamai.com/en-us/products/cloud_security/edge_dns.html)
 * [GoDaddy](https://www.godaddy.com)
 * [Gandi](https://www.gandi.net)
+* [UKFast SafeDNS](https://my.ukfast.co.uk/safedns/)
 
 From this release, ExternalDNS can become aware of the records it is managing (enabled via `--registry=txt`), therefore ExternalDNS can safely manage non-empty hosted zones. We strongly encourage you to use `v0.5` (or greater) with `--registry=txt` enabled and `--txt-owner-id` set to a unique value that doesn't change for the lifetime of your cluster. You might also want to run ExternalDNS in a dry run mode (`--dry-run` flag) to see the changes to be submitted to your DNS Provider API.
 
@@ -109,6 +110,7 @@ The following table clarifies the current status of the providers according to t
 | UltraDNS | Alpha | |
 | GoDaddy | Alpha | |
 | Gandi | Alpha | @packi |
+| SafeDNS | Alpha | @assureddt |
 
 ## Kubernetes version compatibility
 
@@ -171,6 +173,7 @@ The following tutorials are provided:
 * [UltraDNS](docs/tutorials/ultradns.md)
 * [GoDaddy](docs/tutorials/godaddy.md)
 * [Gandi](docs/tutorials/gandi.md)
+* [SafeDNS](docs/tutorials/safedns.md)
 
 ### Running Locally
 

docs/tutorials/UKFast_SafeDNS.md

@@ -0,0 +1,210 @@
+# Setting up ExternalDNS for Services on UKFast's SafeDNS
+
+This tutorial describes how to setup ExternalDNS for usage within a Kubernetes cluster using SafeDNS.
+
+Make sure to use **>=0.11.0** version of ExternalDNS for this tutorial.
+
+## Managing DNS with SafeDNS
+
+If you want to learn about how to use the SafeDNS service read the following tutorials:
+To learn more about the use of SafeDNS in general, see the following page:
+
+[UKFast's SafeDNS documentation](https://docs.ukfast.co.uk/domains/safedns/index.html).
+
+## Creating SafeDNS credentials
+
+Generate a fresh API token for use with ExternalDNS, following the instructions
+at the UKFast developer [Getting-Started](https://developers.ukfast.io/getting-started)
+page. You will need to grant read/write access to the SafeDNS API. No access to
+any other UKFast service is required.
+
+The environment variable `SAFEDNS_TOKEN` must have a value of this token to run
+ExternalDNS with SafeDNS integration.
+
+## Deploy ExternalDNS
+
+Connect your `kubectl` client to the cluster you want to test ExternalDNS with.
+Then apply one of the following manifests file to deploy ExternalDNS.
+
+### Manifest (for clusters without RBAC enabled)
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: external-dns
+spec:
+  strategy:
+    type: Recreate
+  selector:
+    matchLabels:
+      app: external-dns
+  template:
+    metadata:
+      labels:
+        app: external-dns
+    spec:
+      containers:
+      - name: external-dns
+        # You will need to check what the latest version is yourself:
+        # https://github.com/kubernetes-sigs/external-dns/releases
+        image: k8s.gcr.io/external-dns/external-dns:vX.Y.Z
+        args:
+        - --source=service # ingress is also possible
+        # (optional) limit to only example.com domains; change to match the
+        # zone created above.
+        - --domain-filter=example.com
+        - --provider=safedns
+        env:
+        - name: SAFEDNS_TOKEN
+          value: "SAFEDNSTOKENSAFEDNSTOKEN"
+```
+
+### Manifest (for clusters with RBAC enabled)
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: external-dns
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: external-dns
+rules:
+- apiGroups: [""]
+  resources: ["services","endpoints","pods"]
+  verbs: ["get","watch","list"]
+- apiGroups: ["extensions","networking.k8s.io"]
+  resources: ["ingresses"]
+  verbs: ["get","watch","list"]
+- apiGroups: [""]
+  resources: ["nodes"]
+  verbs: ["list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: external-dns-viewer
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: external-dns
+subjects:
+- kind: ServiceAccount
+  name: external-dns
+  namespace: default
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: external-dns
+spec:
+  strategy:
+    type: Recreate
+  selector:
+    matchLabels:
+      app: external-dns
+  template:
+    metadata:
+      labels:
+        app: external-dns
+    spec:
+      serviceAccountName: external-dns
+      containers:
+      - name: external-dns
+        image: k8s.gcr.io/external-dns/external-dns:v0.11.0
+        args:
+        - --source=service # ingress is also possible
+        # (optional) limit to only example.com domains; change to match the
+        # zone created above.
+        - --domain-filter=example.com
+        - --provider=safedns
+        env:
+        - name: SAFEDNS_TOKEN
+          value: "SAFEDNSTOKENSAFEDNSTOKEN"
+```
+
+## Deploying an Nginx Service
+
+Create a service file called 'nginx.yaml' with the following contents:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx
+spec:
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - image: nginx
+        name: nginx
+        ports:
+        - containerPort: 80
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: nginx
+  annotations:
+    external-dns.alpha.kubernetes.io/hostname: my-app.example.com
+spec:
+  selector:
+    app: nginx
+  type: LoadBalancer
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 80
+```
+
+Note the annotation on the service; use a hostname that matches the domain
+filter specified above.
+
+ExternalDNS uses this annotation to determine what services should be registered
+with DNS. Removing the annotation will cause ExternalDNS to remove the
+corresponding DNS records.
+
+Create the deployment and service:
+
+```console
+$ kubectl create -f nginx.yaml
+```
+
+Depending where you run your service it can take a little while for your cloud
+provider to create an external IP for the service.
+
+Once the service has an external IP assigned, ExternalDNS will notice the new
+service IP address and synchronize the SafeDNS records.
+
+## Verifying SafeDNS records
+
+Check your [SafeDNS UI](https://my.ukfast.co.uk/safedns/index.php) and select
+the appropriate domain to view the records for your SafeDNS zone.
+
+This should show the external IP address of the service as the A record for your
+domain.
+
+Alternatively, you can perform a DNS lookup for the hostname specified:
+```console
+$ dig +short my-app.example.com
+an.ip.addr.ess
+```
+
+## Cleanup
+
+Now that we have verified that ExternalDNS will automatically manage SafeDNS
+records, we can delete the tutorial's example:
+
+```
+$ kubectl delete service -f nginx.yaml
+$ kubectl delete service -f externaldns.yaml
+```