Merge pull request #351 from appuio/cleanup-dns-scheme

Update DNS scheme documentation to match current best practices

docs/modules/ROOT/pages/explanations/dns_scheme.adoc

@@ -7,12 +7,16 @@ An OpenShift 4 cluster requires using a specific DNS scheme which is described o
 `<base domain>`::
 
   The base domain for the cluster (input by the customer).
+  If the customer doesn't provide a specific base domain, VSHN uses `vshnmanaged.net` as the base domain.
 
 == Automatically generated values
 
 `<cluster id>`::
 
-  The Project Syn Lieutenant cluster id of the cluster (auto generated by the Lieutenant API).
+  The Project Syn Lieutenant cluster id of the cluster.
+  The cluster ID can be generated by the Lieutenant API.
+  The cluster ID is always prefixed with `c-`.
+  By default, VSHN will suggest a cluster ID that reflects the customer and stage of the cluster, for example `c-company-test1`
 
 
 pass:[<!-- vale Microsoft.Units = NO -->]
@@ -57,24 +61,34 @@ No DNS records will be created.
 
   `api-int.<cluster domain>`
 
+`<ingress floating IP>`::
+
+  The floating IP on which the applications are exposed.
+
+  `ingress.<cluster-domain>
+
+`<egress floating IP>`::
+
+  The floating IP to which egress traffic is SNATed.
+  Optional, but always present for clusters running in a private network with a VSHN-managed default gateway.
+
+  `egress.<cluster-domain>`
+
 `<default app domain>`::
 
+  Usually a CNAME record to `ingress.<cluster-domain>`.
+
   `*.apps.<cluster domain>`
 
 `<etcd>`::
 
   `etcd-<index>.<cluster domain>`
 
-`<etcd srv>`::
-
-  DNS Resource Record of type `SRV` pointing to the `<etcd>` instances.
-
-  `_etcd-server-ssl._tcp.<cluster domain>`
-
 `<acme challenge>`::
 
   DNS Resource Record of type `TXT` used for validating certificates using the DNS01 method.
   *It must be possible to create these records programmatically with one of the APIs supported by https://cert-manager.io/docs/configuration/acme/dns01/#supported-dns01-providers[cert-manager]*.
+  By default, VSHN will use a self-hosted https://github.com/joohoi/acme-dns[acme-dns] instance to manage the TXT records.
 
   `_acme-challenge.<default app domain | external api>`
 
@@ -87,51 +101,51 @@ The following DNS records must resolve publicly:
  * `<default app domain>`
  * `<external api>`
 
- Everything else must resolve at least within the clusters network.
+ Everything else must resolve at least within the cluster's network.
 ====
 
 == Example
 
 === DNS Records
 
-A full list of DNS records for one cluster using the above definition:
+A full list of DNS records for the test cluster of company "summer-shadow" according to the definition on this page:
+
+NOTE: This example assumes that the customer doesn't provide a custom base domain.
 
 ----
 ; Services
-api-int.c-summer-shadow-2592.example.com IN A x.x.x.x
-api.c-summer-shadow-2592.example.com IN A x.x.x.x
-
-etcd-0.c-summer-shadow-2592.example.com IN A x.x.x.x
-etcd-1.c-summer-shadow-2592.example.com IN A x.x.x.x
-etcd-2.c-summer-shadow-2592.example.com IN A x.x.x.x
+api.c-summer-shadow-test1.vshnmanaged.net IN A x.x.x.x
+api-int.c-summer-shadow-test1.vshnmanaged.net IN A x.x.x.x
+ingress.c-summer-shadow-test1.vshnmanaged.net IN A x.x.x.x
+egress.c-summer-shadow-test1.vshnmanaged.net IN A x.x.x.x
 
-*.apps.c-summer-shadow-2592.example.com IN CNAME api.c-summer-shadow-2592.example.com
+*.apps.c-summer-shadow-2592.vshnmanaged.net IN CNAME ingress.c-summer-shadow-test1.example.com.
 
-_acme-challenge.api.c-summer-shadow-2592.example.com IN TXT ...
-_acme-challenge.apps.c-summer-shadow-2592.example.com IN TXT ...
+etcd-0.c-summer-shadow-test1.vshnmanaged.net IN A x.x.x.x
+etcd-1.c-summer-shadow-test1.vshnmanaged.net IN A x.x.x.x
+etcd-2.c-summer-shadow-test1.vshnmanaged.net IN A x.x.x.x
 
-_etcd-server-ssl._tcp.c-summer-shadow-2592.example.com IN SRV 0 10 2380 etcd-0.c-summer-shadow-2592.example.com
-_etcd-server-ssl._tcp.c-summer-shadow-2592.example.com IN SRV 0 10 2380 etcd-1.c-summer-shadow-2592.example.com
-_etcd-server-ssl._tcp.c-summer-shadow-2592.example.com IN SRV 0 10 2380 etcd-2.c-summer-shadow-2592.example.com
+_acme-challenge.api.c-summer-shadow-test1.vshnmanaged.net IN CNAME <acme-dns-client-uuid>.acme-dns.vshn.net.
+_acme-challenge.apps.c-summer-shadow-test1.vshnmanaged.net IN TXT <acme-dns-client-uuid>.acme-dns.vshn.net.
 ----
 
 === Hostnames
 
-A full list of example hostnames for one cluster using the above definition:
+A full list of example hostnames for the test cluster of company "summer-shadow" according to the definition on this page:
 
 ----
-infra-454b.c-summer-shadow-2592.example.com
-infra-9031.c-summer-shadow-2592.example.com
-infra-c8f2.c-summer-shadow-2592.example.com
+infra-454b.c-summer-shadow-test1.vshnmanaged.net
+infra-9031.c-summer-shadow-test1.vshnmanaged.net
+infra-c8f2.c-summer-shadow-test1.vshnmanaged.net
 
-lb-5f52.c-summer-shadow-2592.example.com
-lb-ba8f.c-summer-shadow-2592.example.com
+lb-5f52.c-summer-shadow-test1.vshnmanaged.net
+lb-ba8f.c-summer-shadow-test1.vshnmanaged.net
 
-master-0e9c.c-summer-shadow-2592.example.com
-master-1a3c.c-summer-shadow-2592.example.com
-master-e976.c-summer-shadow-2592.example.com
+master-0e9c.c-summer-shadow-test1.vshnmanaged.net
+master-1a3c.c-summer-shadow-test1.vshnmanaged.net
+master-e976.c-summer-shadow-test1.vshnmanaged.net
 
-worker-4720.c-summer-shadow-2592.example.com
-worker-7d32.c-summer-shadow-2592.example.com
-worker-a640.c-summer-shadow-2592.example.com
+worker-4720.c-summer-shadow-test1.vshnmanaged.net
+worker-7d32.c-summer-shadow-test1.vshnmanaged.net
+worker-a640.c-summer-shadow-test1.vshnmanaged.net
 ----