mirrors/external-dns
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/external-dns.git synced 2025-08-06 01:26:59 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse Source 
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.
This commit is contained in:
Edward Lynes 2020-11-23 14:42:31 -05:00
parent 75429cc504
commit f33a90f88b
4 changed files with 254 additions and 193 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGELOG.md
View File

@ -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

3
README.md
View File

@ -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 | |

251
docs/tutorials/akamai-edgedns.md Normal file
View File

@ -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.

192
docs/tutorials/akamai-fastdns.md
View File

@ -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)