7 minute read
Request DNS Names in Shoot Clusters
Within a shoot cluster, it is possible to request DNS records via the following resource types:
It is necessary that the Gardener installation your shoot cluster runs in is equipped with a
shoot-dns-service extension. This extension uses the seed’s dns management infrastructure to maintain DNS names for shoot clusters. Please ask your Gardener operator if the extension is available in your environment.
Shoot Feature Gate
In some Gardener setups the
shoot-dns-service extension is not enabled globally and thus must be configured per shoot cluster. Please adapt the shoot specification by the configuration shown below to activate the extension individually.
kind: Shoot ... spec: extensions: - type: shoot-dns-service ...
Before you start
You should :
- Have created a shoot cluster
- Have created and correctly configured a DNS Provider (Please consult this page for more information)
- Have a basic understanding of DNS (see link under References)
There are 2 types of DNS that you can use within Kubernetes :
- internal (usually managed by coreDNS)
- external (managed by a public DNS provider).
This page, and the extension, exclusively works for external DNS handling.
Gardener allows 2 way of managing your external DNS:
- Manually, which means you are in charge of creating / maintaining your Kubernetes related DNS entries
- Via the Gardener DNS extension
Gardener DNS extension
The managed external DNS records feature of the Gardener clusters makes all this easier. You do not need DNS service provider specific knowledge, and in fact you do not need to leave your cluster at all to achieve that. You simply annotate the Ingress / Service that needs its DNS records managed and it will be automatically created / managed by Gardener.
Managed external DNS records are supported with the following DNS provider types:
Request DNS records for Ingress resources
To request a DNS name for an Ingress or Service object in the shoot cluster it must be annotated with the DNS class
garden and an annotation denoting the desired DNS names.
Example for an annotated Ingress resource:
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: amazing-ingress annotations: # Let Gardener manage external DNS records for this Ingress. dns.gardener.cloud/dnsnames: special.example.com # Use "*" to collects domains names from .spec.rules.host dns.gardener.cloud/ttl: "600" dns.gardener.cloud/class: garden # If you are delegating the certificate management to Gardener, uncomment the following line #cert.gardener.cloud/purpose: managed spec: rules: - host: special.example.com http: paths: - pathType: Prefix path: "/" backend: service: name: amazing-svc port: number: 8080 # Uncomment the following part if you are delegating the certificate management to Gardener #tls: # - hosts: # - special.example.com # secretName: my-cert-secret-name
For an Ingress, the DNS names are already declared in the specification. Nevertheless the dnsnames annotation must be present. Here a subset of the DNS names of the ingress can be specified. If DNS names for all names are desired, the value
all can be used.
Keep in mind that ingress resources are ignored unless an ingress controller is set up. Gardener does not provide an ingress controller by default. For more details, see Ingress Controllers and Service in the Kubernetes documentation.
Request DNS records for service type LoadBalancer
Example for an annotated Service (it must have the type
apiVersion: v1 kind: Service metadata: name: amazing-svc annotations: # Let Gardener manage external DNS records for this Service. dns.gardener.cloud/dnsnames: special.example.com dns.gardener.cloud/ttl: "600" dns.gardener.cloud/class: garden spec: selector: app: amazing-app ports: - protocol: TCP port: 80 targetPort: 8080 type: LoadBalancer
Creating a DNSEntry resource explicitly
It is also possible to create a DNS entry via the Kubernetes resource called
apiVersion: dns.gardener.cloud/v1alpha1 kind: DNSEntry metadata: annotations: # Let Gardener manage this DNS entry. dns.gardener.cloud/class: garden name: special-dnsentry namespace: default spec: dnsName: special.example.com ttl: 600 targets: - 18.104.22.168
If one of the accepted DNS names is a direct subname of the shoot’s ingress domain, this is already handled by the standard wildcard entry for the ingress domain. Therefore this name should be excluded from the dnsnames list in the annotation. If only this DNS name is configured in the ingress, no explicit DNS entry is required, and the DNS annotations should be omitted at all.
You can check the status of the
$ kubectl get dnsentry NAME DNS TYPE PROVIDER STATUS AGE mydnsentry special.example.com aws-route53 default/aws Ready 24s
As soon as the status of the entry is
Ready, the provider has accepted the new DNS record. Depending on the provider and your DNS settings and cache, it may take up to 24 hours for the new entry to be propagated over all internet.
More examples can be found here
Request DNS records for Service/Ingress resources using a DNSAnnotation resource
In rare cases it may not be possible to add annotations to a
Ingress resource object.
E.g.: the helm chart used to deploy the resource may not be adaptable for some reasons or some automation is used, which always restores the original content of the resource object by dropping any additional annotations.
In these cases, it is recommended to use an additional
DNSAnnotation resource in order to have more flexibility that
DNSentry resources. The
DNSAnnotation resource makes the DNS shoot service behave as if annotations have been added to the referenced resource.
For the Ingress example shown above, you can create a
DNSAnnotation resource alternatively to provide the annotations.
apiVersion: dns.gardener.cloud/v1alpha1 kind: DNSAnnotation metadata: annotations: dns.gardener.cloud/class: garden name: test-ingress-annotation namespace: default spec: resourceRef: kind: Ingress apiVersion: networking.k8s.io/v1 name: test-ingress namespace: default annotations: dns.gardener.cloud/dnsnames: '*' dns.gardener.cloud/class: garden
Note that the DNSAnnotation resource itself needs the
dns.gardener.cloud/class=garden annotation. This also only works for annotations known to the DNS shoot service (see Accepted External DNS Records Annotations).
For more details, see also DNSAnnotation objects
Accepted External DNS Records Annotations
Here are all of the accepted annotation related to the DNS extension:
- dns.gardener.cloud/dnsnames # Mandatory, accepts a comma-separated list of DNS names if multiple names are required - dns.gardener.cloud/class # Mandatory, DNS extension class name (usually "garden") - dns.gardener.cloud/ttl # Recommended, Time-To-Live of the DNS record - dns.gardener.cloud/cname-lookup-interval # Optional, lookup interval for CNAMEs that must be resolved to IP (in seconds) - dns.gardener.cloud/realms # Optional, for restricting provider access for shoot DNS entries
If one of the accepted DNS names is a direct subdomain of the shoot’s ingress domain, this is already handled by the standard wildcard entry for the ingress domain. Therefore, this name should be excluded from the dnsnames list in the annotation. If only this DNS name is configured in the ingress, no explicit DNS entry is required, and the DNS annotations should be omitted at all.
General DNS tools
To check the DNS resolution, use the
$ nslookup special.your-domain.com
or with dig
$ dig +short special.example.com Depending on your network settings, you may get a successful response faster using a public DNS server (e.g. 22.214.171.124, 126.96.36.199, or 188.8.131.52) dig @184.108.40.206 +short special.example.com
DNS record events
The DNS controller publishes Kubernetes events for the resource which requested the DNS record (Ingress, Service, DNSEntry). These events reveal more information about the DNS requests being processed and are especially useful to check any kind of misconfiguration, e.g. requests for a domain you don’t own.
Events for a successfully created DNS record:
$ kubectl describe service my-service Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal dns-annotation 19s dns-controller-manager special.example.com: dns entry is pending Normal dns-annotation 19s (x3 over 19s) dns-controller-manager special.example.com: dns entry pending: waiting for dns reconciliation Normal dns-annotation 9s (x3 over 10s) dns-controller-manager special.example.com: dns entry active
Please note, events vanish after their retention period (usually
DNSEntry resources offer a
.status sub-resource which can be used to check the current state of the object.
Status of a erroneous
status: message: No responsible provider found observedGeneration: 3 provider: remote state: Error