From 803514575fc3627cd5d04870d73d234a028c216a Mon Sep 17 00:00:00 2001 From: Igor Benko Date: Fri, 23 May 2025 17:31:23 +0200 Subject: [PATCH 1/3] Describe how to add additional hostnames to be resolved in the cluster --- .../self-hosted/kubernetes-troubleshooting.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/docs/self-hosted/kubernetes-troubleshooting.md b/docs/self-hosted/kubernetes-troubleshooting.md index fb758683..6c035cbf 100644 --- a/docs/self-hosted/kubernetes-troubleshooting.md +++ b/docs/self-hosted/kubernetes-troubleshooting.md @@ -86,4 +86,66 @@ flushdb Afterwards, run `composer update mirrors` to make sure all repository references are up-to-date. +#### The application is not able to resolve the hostnames of internal services - for example when accessing a GitLab server in a local network +Kubernetes clusters use their own DNS resolution mechanism. Even if the host server can resolve local hostnames (through +local DNS servers or `/etc/resolv.conf`), these names are not resolvable within the cluster. + +You can configure additional hostnames to be resolved by the cluster by following the instructions below. + +Make a backup of the current `coredns` config to a yaml file in case you need to revert changes or want to keep it as +a reference: +``` +kubectl -n kube-system get configmap coredns -o yaml > coredns-config.yaml +``` + +Start editing the `coredns` config by issuing the following command: +``` +kubectl -n kube-system edit configmap coredns +``` + +This will open the current `coredns` config in your default editor. Add all additional hostnames with corresponding IPs to the `hosts` config block. +If the `hosts` config block doesn't exist yet, please add it. + +**Important:** Add the `fallthrough` entry as the last entry in order to resolve all other hostnames that are not listed in the `hosts` config block! + +The full configuration should look similar to this: +``` +data: + Corefile: | + .:53 { + errors + health { + lameduck 5s + } + ready + kubernetes cluster.local in-addr.arpa ip6.arpa { + pods insecure + fallthrough in-addr.arpa ip6.arpa + ttl 30 + } + prometheus :9153 + forward . /etc/resolv.conf { + max_concurrent 1000 + } + hosts { + 10.1.2.3 your-gitlab-server-hostname.local + fallthrough + } + cache 30 + loop + reload + loadbalance + } +``` + + +Restart coredns to apply the changes: +``` +kubectl -n kube-system rollout restart deployment coredns +``` + +To verify that the configured hostnames can now be correctly resolved, use this command: +``` +kubectl exec -it $(kubectl get pods -o name | grep worker | head -1 | cut -d'/' -f2) -- nslookup your-gitlab-server-hostname.local +``` From 69f90dd43af87fd004ed5e9aa90b0805932a3498 Mon Sep 17 00:00:00 2001 From: Igor Benko Date: Mon, 26 May 2025 09:46:49 +0200 Subject: [PATCH 2/3] Update docs/self-hosted/kubernetes-troubleshooting.md Co-authored-by: Steven Rombauts --- docs/self-hosted/kubernetes-troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/self-hosted/kubernetes-troubleshooting.md b/docs/self-hosted/kubernetes-troubleshooting.md index 6c035cbf..1973dd23 100644 --- a/docs/self-hosted/kubernetes-troubleshooting.md +++ b/docs/self-hosted/kubernetes-troubleshooting.md @@ -86,7 +86,7 @@ flushdb Afterwards, run `composer update mirrors` to make sure all repository references are up-to-date. -#### The application is not able to resolve the hostnames of internal services - for example when accessing a GitLab server in a local network +#### Issues with internal hostname resolution Kubernetes clusters use their own DNS resolution mechanism. Even if the host server can resolve local hostnames (through local DNS servers or `/etc/resolv.conf`), these names are not resolvable within the cluster. From 6d4398e5a1a26da37986217468c2c828a6e91bdb Mon Sep 17 00:00:00 2001 From: Igor Benko Date: Wed, 28 May 2025 14:44:25 +0200 Subject: [PATCH 3/3] Use CoreDNS instead of coredns when describing the service. --- docs/self-hosted/kubernetes-troubleshooting.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/self-hosted/kubernetes-troubleshooting.md b/docs/self-hosted/kubernetes-troubleshooting.md index 1973dd23..83efb26d 100644 --- a/docs/self-hosted/kubernetes-troubleshooting.md +++ b/docs/self-hosted/kubernetes-troubleshooting.md @@ -93,18 +93,18 @@ local DNS servers or `/etc/resolv.conf`), these names are not resolvable within You can configure additional hostnames to be resolved by the cluster by following the instructions below. -Make a backup of the current `coredns` config to a yaml file in case you need to revert changes or want to keep it as +Make a backup of the current CoreDNS config to a yaml file in case you need to revert changes or want to keep it as a reference: ``` kubectl -n kube-system get configmap coredns -o yaml > coredns-config.yaml ``` -Start editing the `coredns` config by issuing the following command: +Start editing the CoreDNS config by issuing the following command: ``` kubectl -n kube-system edit configmap coredns ``` -This will open the current `coredns` config in your default editor. Add all additional hostnames with corresponding IPs to the `hosts` config block. +This will open the current CoreDNS config in your default editor. Add all additional hostnames with corresponding IPs to the `hosts` config block. If the `hosts` config block doesn't exist yet, please add it. **Important:** Add the `fallthrough` entry as the last entry in order to resolve all other hostnames that are not listed in the `hosts` config block! @@ -140,7 +140,7 @@ data: ``` -Restart coredns to apply the changes: +Restart CoreDNS to apply the changes: ``` kubectl -n kube-system rollout restart deployment coredns ```