Skip to content

Commit 8846d61

Browse files
reshnmValentinGerlach
reshnm
and
ValentinGerlach
authored
docs: add local dns adr (#12)
Co-authored-by: Valentin Gerlach <valentin.gerlach@sap.com>
1 parent 465645b commit 8846d61

File tree

2 files changed

+155
-1
lines changed

2 files changed

+155
-1
lines changed

‎adrs/2025-07-17-local-dns.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
authors:
3+
- ReneSchuenemann # Change to your own handle. Add yourself to "authors.yml" if necessary.
4+
---
5+
6+
# Local DNS
7+
8+
## Context and Problem Statement
9+
10+
When creating services on a Kubernetes cluster, they shall be accessible from other clusters within an openMCP landscape. To achieve this a `Gateway` and `HTTPRoute` resource is created. The Gateway controller will assign a routable IP address to the Gateway resource. The HTTPRoute resource will then be used to route traffic to the service.
11+
12+
```yaml
13+
apiVersion: gateway.networking.k8s.io/v1beta1
14+
kind: Gateway
15+
metadata:
16+
name: example-gateway
17+
namespace: default
18+
spec:
19+
gatewayClassName: openmcp
20+
listeners:
21+
- name: http
22+
protocol: HTTP
23+
port: 80
24+
allowedRoutes:
25+
namespaces:
26+
from: Same
27+
status:
28+
addresses:
29+
- type: IPAddress
30+
value: "172.18.201.1"
31+
---
32+
apiVersion: gateway.networking.k8s.io/v1beta1
33+
kind: HTTPRoute
34+
metadata:
35+
name: example-route
36+
namespace: default
37+
spec:
38+
parentRefs:
39+
- name: example-gateway
40+
hostnames:
41+
- svc-abc123.workload01.openmcp.cluster
42+
rules:
43+
- matches:
44+
- path:
45+
type: PathPrefix
46+
value: /
47+
backendRefs:
48+
- name: example-svc
49+
port: 80
50+
```
51+
52+
The problem is that the service is only reachable via the IP address and not via the hostname. This is because the DNS server in the openMCP landscape does not know about the service and therefore cannot resolve the hostname to the IP address. The Kubernetes dns service only knows how to route to service within the same cluster. On an openMCP landscape however, services must be reachable from other clusters by stable host names.
53+
54+
Therefore there is a need for a openMCP DNS solution that makes these host names resolvable on all clusters that ar part of the openMCP landscape.
55+
56+
## openMCP DNS System Service
57+
58+
To solve the stated problem, a `openMCP DNS System Service` is needed. This system service will be responsible for the following tasks:
59+
60+
* Deploy a central openMCP DNS server in the openMCP landscape. This DNS server will be used to resolve all host names in the openMCP base domain `openmcp.cluster`.
61+
* For each cluster in the openMCP landscape, the system service will configure the Kubernetes local DNS service to forward DNS queries for the openMCP base domain to the central openMCP DNS server. This will ensure that all clusters can resolve host names in the openMCP base domain.
62+
* For each Gateway or Ingress resource, the system service will create a DNS entry in the central openMCP DNS server. The DNS entry will map the hostname to the IP address of the Gateway or Ingress resource.
63+
* For each cluster in the openMCP landscape, the system service will annotate the `Cluster` resource with the openMCP base domain. This will help service providers to configure their services to use the openMCP base domain for their host names.
64+
65+
This shall be completely transparent to a service provider. The service provider only needs to create a Gateway or Ingress resource and the DNS entry will be created automatically.
66+
67+
## Example Implementation
68+
69+
For the example implementation, following components are used:
70+
71+
* [External-DNS](https://kubernetes-sigs.github.io/external-dns/latest/)
72+
* [CoreDNS](https://coredns.io/)
73+
* [ETCD](https://etcd.io/)
74+
75+
The `DNS Provider` is running on the platform cluster. The `DNS Provider` is deploying an `ETCD` and the cental `CoreDNS` instance on the platform cluster. The `ETCD` instance is used to store the DNS entries. The `CoreDNS` is reading the DNS entries from the `ETCD` instance and is used to resolve the host names.
76+
77+
```yaml
78+
# CoreDNS configuration to read DNS entries from ETCD for the openMCP base domain `openmcp.cluster`
79+
- name: etcd
80+
parameters: openmcp.cluster
81+
configBlock: |-
82+
stubzones
83+
path /skydns
84+
endpoint http://10.96.55.87:2379
85+
```
86+
87+
The `DNS Provier` is reconciling `Cluster` resources. For each `Cluster` resource, the `DNS Provider` is deploying an `External-DNS` instance on the cluster. The `External-DNS` instance is used to detect the `Gateway` and `Ingress` resources and to automatically create the DNS entries in the `ETCD` instance running on the platform cluster.
88+
89+
```yaml
90+
# external-dns configuration to detect Gateway and Ingress resources and write DNS entries to ETCD
91+
containers:
92+
- name: external-dns
93+
image: registry.k8s.io/external-dns/external-dns:v0.16.1
94+
args:
95+
- --source=ingress
96+
- --source=gateway-httproute
97+
- --provider=coredns
98+
- --domain-filter=platform.openmcp.cluster # only detect hostnames in the openMCP base domain belonging to the cluster
99+
env:
100+
- name: ETCD_URLS
101+
value: http://172.18.200.2:2379 # external routable IP of the ETCD instance running on the platform cluster
102+
```
103+
104+
```mermaid
105+
graph TD
106+
subgraph Platform Cluster
107+
A[DNS Provider]
108+
B[CoreDNS]
109+
C[ETCD]
110+
F[Cluster]
111+
A -- deploys --> B
112+
A -- deploys --> C
113+
A -- reconcile --> F
114+
C -- reads --> B
115+
end
116+
117+
subgraph Workload Cluster
118+
D[External-DNS]
119+
E[Ingress / Gateway]
120+
D -- writes --> C
121+
D -- detects --> E
122+
A -- deploys --> D
123+
end
124+
```
125+
126+
The `DNS Provider` is updating the `CoreDNS` configuration on the platform cluster and on all other clusters. The `CoreDNS` configuration is updated to forward DNS queries for the openMCP base domain to the central `CoreDNS` instance running on the platform cluster. This will ensure that all clusters can resolve host names in the openMCP base domain.
127+
128+
```corefile
129+
openmcp.cluster {
130+
forward . 172.18.200.3
131+
log
132+
errors
133+
}
134+
```
135+
```mermaid
136+
graph TD
137+
subgraph Platform Cluster
138+
A[DNS Provider]
139+
B[CoreFile]
140+
A -- updates --> B
141+
end
142+
143+
subgraph Workload Cluster
144+
C[CoreFile]
145+
A -- updates --> C
146+
end
147+
```
148+
149+
Then on any pod in any cluster of the openMCP landscape, the hostname can be resolved to the IP address of the Gateway or Ingress resource.

‎adrs/authors.yml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,12 @@ ValentinGerlach:
55
image_url: /img/authors/ValentinGerlach.png
66
socials:
77
github: ValentinGerlach
8-
8+
ReneSchuenemann:
9+
name: Rene Schünemann
10+
title: openMCP Contributor
11+
url: https://github.com/reshnm
12+
socials:
13+
github: reshnm
914
MaximilianTechritz:
1015
name: Maximilian Techritz
1116
title: openMCP Contributor

0 commit comments

Comments
 (0)