Update DNS guide for devs

website/documentation/guides/administer_shoots/dns_names/_index.md

@@ -11,31 +11,31 @@ aliases: ["/050-tutorials/content/howto/dns_names"]
 # Request DNS Names in Shoot Clusters
 
 ## Introduction
-Gardener allows Shoot clusters to request DNS names for Ingresses and Services out of the box. 
-Therefore the gardener must be installed with the `shoot-dns-service` extension.
-This extension uses the seed's dns management infrastructure to maintain DNS
-names for shoot clusters. So, far only the external DNS domain of a shoot
-(already used for the kubernetes api server and ingress DNS names) can be used
-for managed DNS names.
+Within a shoot cluster, it is possible to request DNS records via the following resource types:
+- [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
+- [Service](https://kubernetes.io/docs/concepts/services-networking/service/)
+- [DNSEntry](https://github.com/gardener/external-dns-management/blob/master/examples/40-entry-dns.yaml)
 
+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
 
-The shoot DNS feature is not globally enabled by default (depends on the 
-extension registration on the garden cluster). Therefore it must be
-enabled per shoot.
-
-To enable the feature for a shoot, the shoot manifest must add the `shoot-dns-service` extension.
+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.
 
 ```yaml
+kind: Shoot
 ...
 spec:
   extensions:
     - type: shoot-dns-service
 ...
 ```
 
-## Configuration In Shoot Cluster
+## DNS providers, domain scope
+
+Gardener can only manage DNS records on your behalf if you have proper DNS providers in place. Please consult [this page](../dns_providers/_index.md) for more information.
+
+## Request DNS records via Service/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
@@ -73,3 +73,55 @@ 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.
+
+## Request DNS records via DNSEntry resources
+
+```yaml
+apiVersion: dns.gardener.cloud/v1alpha1
+kind: DNSEntry
+metadata:
+  annotations:
+    dns.gardener.cloud/class: garden
+  name: dns
+  namespace: default
+spec:
+  dnsName: "my.subdomain.for.shootsomain.cloud"
+  ttl: 600
+  # txt records, either text or targets must be specified
+# text:
+# - foo-bar
+  targets:
+  # target records (CNAME or A records)
+  - 8.8.8.8
+```
+
+## 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 -n default describe service my-service
+
+Events:
+  Type    Reason          Age                From                    Message
+  ----    ------          ----               ----                    -------
+  Normal  dns-annotation  19s                dns-controller-manager  my.subdomain.for.shootsomain.cloud: dns entry is pending
+  Normal  dns-annotation  19s (x3 over 19s)  dns-controller-manager  my.subdomain.for.shootsomain.cloud: dns entry pending: waiting for dns reconciliation
+  Normal  dns-annotation  9s (x3 over 10s)   dns-controller-manager  my.subdomain.for.shootsomain.cloud: dns entry active
+```
+
+Please note, events vanish after their retention period (usually `1h`).
+
+## DNSEntry status
+
+`DNSEntry` resources offer a `.status` sub-resource which can be used to check the current state of the object.
+
+Status of a erroneous `DNSEntry`.
+```
+  status:
+    message: No responsible provider found
+    observedGeneration: 3
+    provider: remote
+    state: Error
+```

website/documentation/guides/administer_shoots/dns_providers/_index.md

@@ -0,0 +1,49 @@
+---
+title: Manage DNS Providers
+description: "Manage DNS providers for DNS records in your shoot cluster"
+type: docs
+level: Advanced
+category: DNS
+scope: app-developer
+aliases: ["/050-tutorials/content/howto/dns_names"]
+---
+
+# DNS Providers
+
+## Introduction
+
+Gardener can manage DNS records on your behalf, so that you can request them via different resource types (see [here](../dns_names/_index.md#Introduction)) within the shoot cluster. The domains for which you are permitted to request records, are however restricted and depend on the DNS provider confguration.
+
+## Shoot provider
+
+By default, every shoot cluster is equipped with a default provider. It is the very same provider that manages the shoot cluster's Kube-Apiserver public DNS record (DNS address in your Kubeconfig).
+
+```
+kind: Shoot
+...
+dns:
+  domain: shoot.project.default-domain.gardener.cloud
+```
+
+You are permitted to request any sub-domain of `.dns.domain` that is not already taken (e.g. `api.shoot.project.default-domain.gardener.cloud`, `*.ingress.shoot.project.default-domain.gardener.cloud`) with this provider.
+
+## Additional providers
+
+If you need to request DNS records for domains not managed by the [default provider](#Shoot-provider), additional providers must be configured in the shoot specification.
+
+For example:
+```
+kind: Shoot
+...
+dns:
+  domain: shoot.project.default-domain.gardener.cloud
+  providers:
+  - secretName: my-aws-account
+    type: aws-route53
+  - secretName: my-gcp-account
+    type: google-clouddns
+```
+
+> Please consult the [API-Reference](https://gardener.cloud/documentation/references/core/#core.gardener.cloud/v1beta1.DNSProvider) to get a complete list of supported fields and configuration options.
+
+Referenced secrets should exist in the project namespace in the Garden cluster and must comply with the provider specific credentials format. The **External-DNS-Management** project provides corresponding examples ([20-secret-\<provider-name>-credentials.yaml](https://github.com/gardener/external-dns-management/tree/master/examples)) for known providers.