From 1eccb64bcbbc6c42bec9a0014338e7d4ecb9f693 Mon Sep 17 00:00:00 2001
From: Ivan Ka <5395690+ivankatliarchuk@users.noreply.github.com>
Date: Wed, 9 Jul 2025 08:43:28 +0100
Subject: [PATCH] fix(source/service): headless records and root/base domain
 (#5624)

Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com>
---
 docs/annotations/annotations.md | 67 +++++++++++++++++++++++++++++++++
 docs/tutorials/hostport.md      | 24 ++++++------
 2 files changed, 80 insertions(+), 11 deletions(-)

diff --git a/docs/annotations/annotations.md b/docs/annotations/annotations.md
index c5c172f23..bc3cffc10 100644
--- a/docs/annotations/annotations.md
+++ b/docs/annotations/annotations.md
@@ -66,6 +66,73 @@ Multiple hostnames can be specified through a comma-separated list, e.g.
 
 For `Pods`, uses the `Pod`'s `Status.PodIP`, unless they are `hostNetwork: true` in which case the NodeExternalIP is used for IPv4 and NodeInternalIP for IPv6.
 
+Notes:
+
+- This annotation `overrides` any automatically derived hostnames (e.g., from Ingress.spec.rules[].host).
+- Hostnames must match the domain filter set in ExternalDNS (e.g., --domain-filter=example.com).
+- This is an alpha annotation — subject to change; newer versions may support alternatives or deprecate it.
+- This annotation is helpful for:
+  - Services or other resources without native hostname fields.
+  - Explicit overrides or multi-host situations.
+  - Avoiding reliance on auto-detection or heuristics.
+
+### Use Cases for `external-dns.alpha.kubernetes.io/hostname` annotation
+
+#### Explicit Hostname Mapping for Services
+
+You have a Service (e.g. of type LoadBalancer or ClusterIP) and want to expose it under a custom DNS name:
+
+```yml
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-service
+  annotations:
+    external-dns.alpha.kubernetes.io/hostname: app.example.com
+spec:
+  type: LoadBalancer
+  ...
+```
+
+> ExternalDNS will create a A or CNAME record for app.example.com pointing to the external IP or hostname of the service.
+
+#### Multi-Hostname Records
+
+You can assign multiple hostnames by separating them with commas:
+
+```yml
+annotations:
+  external-dns.alpha.kubernetes.io/hostname: api.example.com,api.internal.example.com
+```
+
+> ExternalDNS will create two DNS records for the same service.
+
+#### Static DNS Assignment Without Ingress Rules
+
+When using Ingress, you usually declare hostnames in the spec.rules[].host. But with this annotation, you can manage DNS independently:
+
+```yml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: my-ingress
+  annotations:
+    external-dns.alpha.kubernetes.io/hostname: www.example.com
+spec:
+  rules:
+    - http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: my-service
+                port:
+                  number: 80
+```
+
+> Useful when DNS management is decoupled from routing logic.
+
 ## external-dns.alpha.kubernetes.io/ingress-hostname-source
 
 Specifies where to get the domain for an `Ingress` resource.
diff --git a/docs/tutorials/hostport.md b/docs/tutorials/hostport.md
index 30a3f31c1..a789459ea 100644
--- a/docs/tutorials/hostport.md
+++ b/docs/tutorials/hostport.md
@@ -169,7 +169,7 @@ Very important here, is to set the `hostPort`(only works if the PodSecurityPolic
 
 Now we need to define a headless service to use to expose the Kafka pods. There are generally two approaches to use expose the nodeport of a Headless service:
 
-1. Add `--fqdn-template={{name}}.example.org`
+1. Add `--fqdn-template={{ .Name }}.example.org`
 2. Use a full annotation
 
 If you go with #1, you just need to define the headless service, here is an example of the case #2:
@@ -190,22 +190,24 @@ spec:
     component: kafka
 ```
 
-This will create 3 dns records:
+This will create 4 dns records:
 
 ```sh
-kafka-0.example.org
-kafka-1.example.org
-kafka-2.example.org
+kafka-0.example.org IP-0
+kafka-1.example.org IP-1
+kafka-2.example.org IP-2
+example.org IP-0,IP-1,IP-2
 ```
 
-If you set `--fqdn-template={{name}}.example.org` you can omit the annotation.
-Generally it is a better approach to use  `--fqdn-template={{name}}.example.org`, because then
-you would get the service name inside the generated A records:
+> !Notice rood domain with records `example.org`
+
+If you set `--fqdn-template={{ .Name }}.example.org` you can omit the annotation.
 
 ```sh
-kafka-0.ksvc.example.org
-kafka-1.ksvc.example.org
-kafka-2.ksvc.example.org
+kafka-0.ksvc.example.org IP-0
+kafka-1.ksvc.example.org IP-1
+kafka-2.ksvc.example.org IP-2
+ksvc.example.org IP-0,IP-1,IP-2
 ```
 
 #### Using pods' HostIPs as targets