From f33a90f88b4b12f80f1c27e9952e5fe1601692cc Mon Sep 17 00:00:00 2001 From: Edward Lynes Date: Mon, 23 Nov 2020 14:42:31 -0500 Subject: [PATCH] Update documentation update README.md to include akamai provider changes update CHANGEME.md to rename akamai-fastdns refs to akamai-edgedns update Akamai tutorial name and content for updated functionality and tested scenarios. --- CHANGELOG.md | 1 + README.md | 3 +- docs/tutorials/akamai-edgedns.md | 251 +++++++++++++++++++++++++++++++ docs/tutorials/akamai-fastdns.md | 192 ----------------------- 4 files changed, 254 insertions(+), 193 deletions(-) create mode 100644 docs/tutorials/akamai-edgedns.md delete mode 100644 docs/tutorials/akamai-fastdns.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 1c8517c51..3b52a37ad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ - Fix NodePort with externaltrafficpolicy targets duplication @codearky - Update contributing section in README (#1760) @seanmalloy - Option to cache AWS zones list @bpineau +- Refactor, enhance and test Akamai provider and documentation (#1846) @edglynes ## v0.7.3 - 2020-08-05 diff --git a/README.md b/README.md index 16a90bb77..8b2864b1a 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,7 @@ ExternalDNS' current release is `v0.7`. This version allows you to keep selected * [VinylDNS](https://www.vinyldns.io) * [OVH](https://www.ovh.com) * [Scaleway](https://www.scaleway.com) +* [Akamai Edge DNS](https://learn.akamai.com/en-us/products/cloud_security/edge_dns.html) 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. @@ -77,6 +78,7 @@ The following table clarifies the current status of the providers according to t | Google Cloud DNS | Stable | | | AWS Route 53 | Stable | | | AWS Cloud Map | Beta | | +| Akamai Edge DNS | Beta | | | AzureDNS | Beta | | | CloudFlare | Beta | | | RcodeZero | Alpha | | @@ -96,7 +98,6 @@ The following table clarifies the current status of the providers according to t | TransIP | Alpha | | | VinylDNS | Alpha | | | RancherDNS | Alpha | | -| Akamai FastDNS | Alpha | | | OVH | Alpha | | | Scaleway DNS | Alpha | @Sh4d1 | | Vultr | Alpha | | diff --git a/docs/tutorials/akamai-edgedns.md b/docs/tutorials/akamai-edgedns.md new file mode 100644 index 000000000..5e5381b7d --- /dev/null +++ b/docs/tutorials/akamai-edgedns.md @@ -0,0 +1,251 @@ +# Setting up External-DNS for Services on Akamai Edge DNS + +## Prerequisites + +Akamai Edge DNS (formally known as Fast DNS) provider support was first released in External-DNS v0.5.18 + +### Zones + +External-DNS manages service endpoints in existing DNS zones. The Akamai provider does not add, remove or configure new zones in anyway. Edge DNS zones can be created and managed thru the [Akamai Control Center](https://control.akamai.com) or [Akamai DevOps Tools](https://developer.akamai.com/devops), [Akamai CLI](https://developer.akamai.com/cli) and [Akamai Terraform Provider](https://developer.akamai.com/tools/integrations/terraform) + +### Akamai Edge DNS Authentication + +The Akamai Edge DNS provider requires valid Akamai Edgegrid API authentication credentials to access zones and manage associated DNS records. + +Credentials can be provided to the provider either directly by key or indirectly via a file. The Akamai credential keys and mappings to the Akamai provider utilizing different presentation methods are: + +| Edgegrid Auth Key | External-DNS Cmd Line Key | Environment/ConfigMap Key | Description | +| ----------------- | ------------------------- | ------------------------- | ----------- | +| host | akamai-serviceconsumerdomain | EXTERNAL_DNS_AKAMAI_SERVICECONSUMERDOMAIN | Akamai Edgegrid API server | +| access_token | akamai-access-token | EXTERNAL_DNS_AKAMAI_ACCESS_TOKEN | Akamai Edgegrid API access token | +| client_token | akamai-client-token | EXTERNAL_DNS_AKAMAI_CLIENT_TOKEN |Akamai Edgegrid API client token | +| client-secret | akamai-client-secret | EXTERNAL_DNS_AKAMAI_CLIENT_SECRET |Akamai Edgegrid API client secret | + +In addition to specifying auth credentials individually, the credentials may be referenced indirectly by using the Akamai Edgegrid .edgerc file convention. + +| External-DNS Cmd Line | Environment/ConfigMap | Description | +| --------------------- | --------------------- | ----------- | +| akamai-edgerc-path | EXTERNAL_DNS_AKAMAI_EDGERC_PATH | Accessible path to Edgegrid credentials file, e.g /home/test/.edgerc | +| akamai-edgerc-section | EXTERNAL_DNS_AKAMAI_EDGERC_SECTION | Section in Edgegrid credentials file containing credentials | + +Note: akamai-edgerc-path and akamai-edgerc-section are present in External-DNS versions after v0.7.4 + +[Akamai API Authentication](https://developer.akamai.com/getting-started/edgegrid) provides an overview and further information pertaining to the generation of auth credentials for API base applications and tools. + +The following example defines and references a Kubernetes ConfigMap secret, applied by referencing the secret and its keys in the env section of the deployment. + + +## Deploy External-DNS + +An operational External-DNS deployment consists of an External-DNS container and service. The following sections demonstrate the ConfigMap objects that would make up an example functional external DNS kubernetes configuration utilizing NGINX as the exposed service. + +Connect your `kubectl` client to the cluster with which you want to test External-DNS, and then apply one of the following manifest files for deployment: + +### 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.4 + args: + - --source=service # or ingress or both + - --provider=akamai + - --domain-filter=example.com + # zone-id-filter may be specified as well to filter on contract ID + - --registry=txt + - --txt-owner-id={{ owner-id-for-this-external-dns }} + env: + - name: EXTERNAL_DNS_AKAMAI_SERVICECONSUMERDOMAIN + valueFrom: + secretKeyRef: + name: external-dns + key: EXTERNAL_DNS_AKAMAI_SERVICECONSUMERDOMAIN + - name: EXTERNAL_DNS_AKAMAI_CLIENT_TOKEN + valueFrom: + secretKeyRef: + name: external-dns + key: EXTERNAL_DNS_AKAMAI_CLIENT_TOKEN + - name: EXTERNAL_DNS_AKAMAI_CLIENT_SECRET + valueFrom: + secretKeyRef: + name: external-dns + key: EXTERNAL_DNS_AKAMAI_CLIENT_SECRET + - name: EXTERNAL_DNS_AKAMAI_ACCESS_TOKEN + valueFrom: + secretKeyRef: + name: external-dns + key: EXTERNAL_DNS_AKAMAI_ACCESS_TOKEN +``` + +### 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: + containers: + - name: external-dns + image: k8s.gcr.io/external-dns/external-dns:v0.7.4 + args: + - --source=service # or ingress or both + - --provider=akamai + - --domain-filter=example.com + # zone-id-filter may be specified as well to filter on contract ID + - --registry=txt + - --txt-owner-id={{ owner-id-for-this-external-dns }} + env: + - name: EXTERNAL_DNS_AKAMAI_SERVICECONSUMERDOMAIN + valueFrom: + secretKeyRef: + name: external-dns + key: EXTERNAL_DNS_AKAMAI_SERVICECONSUMERDOMAIN + - name: EXTERNAL_DNS_AKAMAI_CLIENT_TOKEN + valueFrom: + secretKeyRef: + name: external-dns + key: EXTERNAL_DNS_AKAMAI_CLIENT_TOKEN + - name: EXTERNAL_DNS_AKAMAI_CLIENT_SECRET + valueFrom: + secretKeyRef: + name: external-dns + key: EXTERNAL_DNS_AKAMAI_CLIENT_SECRET + - name: EXTERNAL_DNS_AKAMAI_ACCESS_TOKEN + valueFrom: + secretKeyRef: + name: external-dns + key: EXTERNAL_DNS_AKAMAI_ACCESS_TOKEN +``` + +Create the deployment for External-DNS: + +``` +$ kubectl create -f externaldns.yaml +``` + +## 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: nginx.example.com + external-dns.alpha.kubernetes.io/ttl: "600" #optional +spec: + selector: + app: nginx + type: LoadBalancer + ports: + - protocol: TCP + port: 80 + targetPort: 80 +``` + +Create the deployment, service and ingress object: + +``` +$ kubectl create -f nginx.yaml +``` + +## Verify Akamai Edge DNS Records + +It is recommended to wait 3-5 minutes before validating the records to allow the record changes to propagate to all the Akamai name servers worldwide. + +The records can be validated using the [Akamai Control Center](http://control.akamai.com) or by executing a dig, nslookup or similar DNS command. + +## Cleanup + +Once you successfully configure and verify record management via External-DNS, you can delete the tutorial's example: + +``` +$ kubectl delete -f nginx.yaml +$ kubectl delete -f externaldns.yaml +``` + +## Additional Information + +* The Akamai provider allows the administrative user to filter zones by both name (domain-filter) and contract Id (zone-id-filter). The Edge DNS API will return a '500 Internal Error' if an invalid contract Id is provided. +* The provider will substitute any embedded quotes in TXT records with `` ` `` (back tick) when writing the records to the API. + diff --git a/docs/tutorials/akamai-fastdns.md b/docs/tutorials/akamai-fastdns.md deleted file mode 100644 index e4940b6b5..000000000 --- a/docs/tutorials/akamai-fastdns.md +++ /dev/null @@ -1,192 +0,0 @@ -# Setting up Akamai FastDNS - -## Prerequisites - -Akamai FastDNS provider support was added via [this PR](https://github.com/kubernetes-sigs/external-dns/pull/1384), thus you need to use a release where this pr is included. This should be at least v0.5.18 - -The Akamai FastDNS provider expects that your zones, you wish to add records to, already exists -and are configured correctly. It does not add, remove or configure new zones in anyway. - -To do this please refer to the [FastDNS documentation](https://learn.akamai.com/en-us/products/web_performance/fast_dns.html). - -Additional data you will have to provide: - -* Service Consumer Domain -* Access token -* Client token -* Client Secret - -Make these available to external DNS somehow. In the following example a secret is used by referencing the secret and its keys in the env section of the deployment. - -If you happen to have questions regarding authentication, please refer to the [API Client Authentication documentation](https://developer.akamai.com/legacy/introduction/Client_Auth.html) - -## Deployment - -Deploying external DNS for Akamai is actually nearly identical to deploying -it for other providers. This is what a sample `deployment.yaml` looks like: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: external-dns - labels: - app.kubernetes.io/name: external-dns - app.kubernetes.io/version: v0.6.0 -spec: - strategy: - type: Recreate - selector: - matchLabels: - app.kubernetes.io/name: external-dns - template: - metadata: - labels: - app.kubernetes.io/name: external-dns - app.kubernetes.io/version: v0.6.0 - spec: - # Only use if you're also using RBAC - # serviceAccountName: external-dns - containers: - - name: external-dns - image: k8s.gcr.io/external-dns/external-dns:v0.7.3 - args: - - --source=ingress # or service or both - - --provider=akamai - - --registry=txt - - --txt-owner-id={{ owner-id-for-this-external-dns }} - env: - - name: EXTERNAL_DNS_AKAMAI_SERVICECONSUMERDOMAIN - valueFrom: - secretKeyRef: - name: external-dns - key: EXTERNAL_DNS_AKAMAI_SERVICECONSUMERDOMAIN - - name: EXTERNAL_DNS_AKAMAI_CLIENT_TOKEN - valueFrom: - secretKeyRef: - name: external-dns - key: EXTERNAL_DNS_AKAMAI_CLIENT_TOKEN - - name: EXTERNAL_DNS_AKAMAI_CLIENT_SECRET - valueFrom: - secretKeyRef: - name: external-dns - key: EXTERNAL_DNS_AKAMAI_CLIENT_SECRET - - name: EXTERNAL_DNS_AKAMAI_ACCESS_TOKEN - valueFrom: - secretKeyRef: - name: external-dns - key: EXTERNAL_DNS_AKAMAI_ACCESS_TOKEN -``` - -## RBAC - -If your cluster is RBAC enabled, you also need to setup the following, before you can run external-dns: - -```yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - name: external-dns - namespace: default ---- -apiVersion: rbac.authorization.k8s.io/v1beta1 -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/v1beta1 -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 -``` -## Verify ExternalDNS works (Ingress example) - -Create an ingress resource manifest file. - -> For ingress objects ExternalDNS will create a DNS record based on the host specified for the ingress object. - -```yaml -apiVersion: networking.k8s.io/v1beta1 -kind: Ingress -metadata: - name: foo - annotations: - kubernetes.io/ingress.class: "nginx" # use the one that corresponds to your ingress controller. -spec: - rules: - - host: foo.bar.com - http: - paths: - - backend: - serviceName: foo - servicePort: 80 -``` - -## Verify ExternalDNS works (Service example) - -Create the following sample application to test that ExternalDNS works. - -> For services ExternalDNS will look for the annotation `external-dns.alpha.kubernetes.io/hostname` on the service and use the corresponding value. - -> If you want to give multiple names to service, you can set it to external-dns.alpha.kubernetes.io/hostname with a comma separator. - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: nginx - annotations: - external-dns.alpha.kubernetes.io/hostname: nginx.external-dns-test.my-org.com -spec: - type: LoadBalancer - ports: - - port: 80 - name: http - targetPort: 80 - selector: - app: nginx - ---- - -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 - name: http -``` - - -**Important!**: Don't run dig, nslookup or similar immediately. You'll get hit by [negative DNS caching](https://tools.ietf.org/html/rfc2308), which is hard to flush. -Wait about 30s-1m (interval for external-dns to kick in)