From d70e4bcf14d1309083dc6c1823dfd15ddb485d76 Mon Sep 17 00:00:00 2001 From: DavidSpek Date: Fri, 29 Jul 2022 15:38:16 +0200 Subject: [PATCH] Add Plural to READMEs Signed-off-by: DavidSpek --- README.md | 3 + docs/tutorials/plural.md | 197 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 200 insertions(+) create mode 100644 docs/tutorials/plural.md diff --git a/README.md b/README.md index ab011b9a9..532828a87 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,7 @@ ExternalDNS allows you to keep selected zones (via `--domain-filter`) synchroniz * [IBM Cloud DNS](https://www.ibm.com/cloud/dns) * [TencentCloud PrivateDNS](https://cloud.tencent.com/product/privatedns) * [TencentCloud DNSPod](https://cloud.tencent.com/product/cns) +* [Plural](https://www.plural.sh/) 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. @@ -118,6 +119,7 @@ The following table clarifies the current status of the providers according to t | SafeDNS | Alpha | @assureddt | | IBMCloud | Alpha | @hughhuangzh | | TencentCloud | Alpha | @Hyzhou | +| Plural | Alpha | @michaeljguarino | ## Kubernetes version compatibility @@ -187,6 +189,7 @@ The following tutorials are provided: * [IBM Cloud](docs/tutorials/ibmcloud.md) * [Nodes as source](docs/tutorials/nodes.md) * [TencentCloud](docs/tutorials/tencentcloud.md) +* [Plural](docs/tutorials/plural.md) ### Running Locally diff --git a/docs/tutorials/plural.md b/docs/tutorials/plural.md new file mode 100644 index 000000000..c8f77c0b7 --- /dev/null +++ b/docs/tutorials/plural.md @@ -0,0 +1,197 @@ +# Setting up ExternalDNS for Services on Plural + +This tutorial describes how to setup ExternalDNS for usage within a Kubernetes cluster using Plural DNS. + +Make sure to use **>=0.12.3** version of ExternalDNS for this tutorial. + +## Creating Plural Credentials + +A secret containing the a Plural access token is needed for this provider. You can get a token for your user [here](https://app.plural.sh/profile/tokens). + +To create the secret you can run `kubectl create secret generic plural-env --from-literal=PLURAL_ACCESS_TOKEN=`. + +## 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 + image: k8s.gcr.io/external-dns/external-dns:v0.7.6 + args: + - --source=service # ingress is also possible + - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone created above. + - --provider=plural + - --plural-cluster=example-plural-cluster + - --plural-provider=aws # gcp, azure, equinix and kind are also possible + env: + - name: PLURAL_ACCESS_TOKEN + valueFrom: + secretKeyRef: + key: PLURAL_ACCESS_TOKEN + name: plural-env + - name: PLURAL_ENDPOINT # (optional) use an alternative endpoint for Plural; defaults to https://app.plural.sh + value: https://app.plural.sh +``` + +### 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", "watch"] +--- +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: + containers: + - name: external-dns + image: k8s.gcr.io/external-dns/external-dns:v0.7.6 + args: + - --source=service # ingress is also possible + - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone created above. + - --provider=plural + - --plural-cluster=example-plural-cluster + - --plural-provider=aws # gcp, azure, equinix and kind are also possible + env: + - name: PLURAL_ACCESS_TOKEN + valueFrom: + secretKeyRef: + key: PLURAL_ACCESS_TOKEN + name: plural-env + - name: PLURAL_ENDPOINT # (optional) use an alternative endpoint for Plural; defaults to https://app.plural.sh + value: https://app.plural.sh +``` + +## 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: example.com +spec: + selector: + app: nginx + type: LoadBalancer + ports: + - protocol: TCP + port: 80 + targetPort: 80 +``` + +Note the annotation on the service; use the same hostname as the Plural DNS zone created above. The annotation may also be a subdomain +of the DNS zone (e.g. 'www.example.com'). + +By setting the TTL annotation on the service, you have to pass a valid TTL, which must be 120 or above. +This annotation is optional, if you won't set it, it will be 1 (automatic) which is 300. + +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: + +``` +$ 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 Plural DNS records. + +## Verifying Plural DNS records + +Check your [Plural domain overview](https://app.plural.sh/account/domains) to view the domains associated with your Plural account. There you can view the records for each domain. + +The records should show the external IP address of the service as the A record for your domain. + +## Cleanup + +Now that we have verified that ExternalDNS will automatically manage Plural DNS records, we can delete the tutorial's example: + +``` +$ kubectl delete -f nginx.yaml +$ kubectl delete -f externaldns.yaml