Setting up ExternalDNS using AWS Cloud Map API¶
This tutorial describes how to set up ExternalDNS for usage within a Kubernetes cluster with AWS Cloud Map API.
AWS Cloud Map API is an alternative approach to managing DNS records directly using the Route53 API. It is more suitable for a dynamic environment where service endpoints change frequently. It abstracts away technical details of the DNS protocol and offers a simplified model. AWS Cloud Map consists of three main API calls:
- CreatePublicDnsNamespace – automatically creates a DNS hosted zone
- CreateService – creates a new named service inside the specified namespace
- RegisterInstance/DeregisterInstance – can be called multiple times to create a DNS record for the specified Service
Learn more about the API in the AWS Cloud Map API Reference.
IAM Permissions¶
To use the AWS Cloud Map API, a user must have permissions to create the DNS namespace. Additionally you need to make sure that your nodes (on which External DNS runs) have an IAM instance profile with the AWSCloudMapFullAccess managed policy attached, that provides following permissions:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"route53:GetHostedZone",
"route53:ListHostedZonesByName",
"route53:CreateHostedZone",
"route53:DeleteHostedZone",
"route53:ChangeResourceRecordSets",
"route53:CreateHealthCheck",
"route53:GetHealthCheck",
"route53:DeleteHealthCheck",
"route53:UpdateHealthCheck",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"servicediscovery:*"
],
"Resource": [
"*"
]
}
]
}
Set up a namespace¶
Create a DNS namespace using the AWS Cloud Map API:
Verify that the namespace was truly created
Deploy ExternalDNS¶
Connect your kubectl client to the cluster that you want to test ExternalDNS with.
Then apply the following manifest file to deploy ExternalDNS.
Manifest (for clusters without RBAC enabled)¶
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: registry.k8s.io/external-dns/external-dns:v0.14.2
env:
- name: AWS_REGION
value: us-east-1 # put your CloudMap NameSpace region
args:
- --source=service
- --source=ingress
- --domain-filter=external-dns-test.my-org.com # Makes ExternalDNS see only the namespaces that match the specified domain. Omit the filter if you want to process all available namespaces.
- --provider=aws-sd
- --aws-zone-type=public # Only look at public namespaces. Valid values are public, private, or no value for both)
- --txt-owner-id=my-identifier
Manifest (for clusters with RBAC enabled)¶
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:
serviceAccountName: external-dns
containers:
- name: external-dns
image: registry.k8s.io/external-dns/external-dns:v0.14.2
env:
- name: AWS_REGION
value: us-east-1 # put your CloudMap NameSpace region
args:
- --source=service
- --source=ingress
- --domain-filter=external-dns-test.my-org.com # Makes ExternalDNS see only the namespaces that match the specified domain. Omit the filter if you want to process all available namespaces.
- --provider=aws-sd
- --aws-zone-type=public # Only look at public namespaces. Valid values are public, private, or no value for both)
- --txt-owner-id=my-identifier
Verify that 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/hostnameon the service and use the corresponding value.
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
After one minute check that a corresponding DNS record for your service was created in your hosted zone. We recommended that you use the Amazon Route53 console for that purpose.
Custom TTL¶
The default DNS record TTL (time to live) is 300 seconds. You can customize this value by setting the annotation external-dns.alpha.kubernetes.io/ttl.
For example, modify the service manifest YAML file above:
apiVersion: v1
kind: Service
metadata:
name: nginx
annotations:
external-dns.alpha.kubernetes.io/hostname: nginx.external-dns-test.my-org.com
external-dns.alpha.kubernetes.io/ttl: "60"
spec:
...
This will set the TTL for the DNS record to 60 seconds.
Clean up¶
Delete all service objects before terminating the cluster so all load balancers get cleaned up correctly.
Give ExternalDNS some time to clean up the DNS records for you. Then delete the remaining service and namespace.
$ aws servicediscovery list-services
{
"Services": [
{
"Id": "srv-6dygt5ywvyzvi3an",
"Arn": "arn:aws:servicediscovery:us-west-2:861574988794:service/srv-6dygt5ywvyzvi3an",
"Name": "nginx"
}
]
}