From d93bcf8124fa080fac98f35a189422d5460a5f87 Mon Sep 17 00:00:00 2001 From: Simon Gerber Date: Fri, 9 Aug 2024 13:32:15 +0200 Subject: [PATCH] Update DNS scheme documentation to match current best practices We've started using .vshnmanaged.net by default for new clusters. This commit updates the DNS scheme page to match our current best practices. --- .../ROOT/pages/explanations/dns_scheme.adoc | 80 +++++++++++-------- 1 file changed, 47 insertions(+), 33 deletions(-) diff --git a/docs/modules/ROOT/pages/explanations/dns_scheme.adoc b/docs/modules/ROOT/pages/explanations/dns_scheme.adoc index 49f5df39..5da53634 100644 --- a/docs/modules/ROOT/pages/explanations/dns_scheme.adoc +++ b/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 ``:: 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 ``:: - 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:[] @@ -57,24 +61,34 @@ No DNS records will be created. `api-int.` +``:: + + The floating IP on which the applications are exposed. + + `ingress. + +``:: + + 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.` + ``:: + Usually a CNAME record to `ingress.`. + `*.apps.` ``:: `etcd-.` -``:: - - DNS Resource Record of type `SRV` pointing to the `` instances. - - `_etcd-server-ssl._tcp.` - ``:: 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.` @@ -87,51 +101,51 @@ The following DNS records must resolve publicly: * `` * `` - 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.vshn.net. +_acme-challenge.apps.c-summer-shadow-test1.vshnmanaged.net IN TXT .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 ----