From 733f6a834ca97e57f5624c0b4c4b37566a68dd1d Mon Sep 17 00:00:00 2001 From: Rick Henry Date: Fri, 8 Oct 2021 09:54:06 +0100 Subject: [PATCH] Document SafeDNS provider --- README.md | 3 + docs/tutorials/UKFast_SafeDNS.md | 210 +++++++++++++++++++++++++++++++ 2 files changed, 213 insertions(+) create mode 100644 docs/tutorials/UKFast_SafeDNS.md diff --git a/README.md b/README.md index a9b7d8cdb..d91b60cba 100644 --- a/README.md +++ b/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 diff --git a/docs/tutorials/UKFast_SafeDNS.md b/docs/tutorials/UKFast_SafeDNS.md new file mode 100644 index 000000000..742c1fdd6 --- /dev/null +++ b/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 +```