Skip to content

docs(istio): document ingress annotation #5756

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 20, 2025
+40 −27
Merged

docs(istio): document ingress annotation #5756

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5672654
docs(istio): document ingress annotation
ivankatliarchuk Aug 19, 2025
1ae06c4
docs(istio): document ingress annotation
ivankatliarchuk Aug 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 30 additions & 19 deletions docs/annotations/annotations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,25 @@ ExternalDNS sources support a number of annotations on the Kubernetes resources

The following table documents which sources support which annotations:

| Source | controller | hostname | internal-hostname | target | ttl | (provider-specific) |
|--------------|------------|----------|-------------------|---------|---------|---------------------|
| Ambassador | | | | Yes | Yes | Yes |
| Connector | | | | | | |
| Contour | Yes | Yes[^1] | | Yes | Yes | Yes |
| CloudFoundry | | | | | | |
| CRD | | | | | | |
| F5 | | | | Yes | Yes | |
| Gateway | Yes | Yes[^1] | | Yes[^4] | Yes | Yes |
| Gloo | | | | Yes | Yes[^5] | Yes[^5] |
| Ingress | Yes | Yes[^1] | | Yes | Yes | Yes |
| Istio | Yes | Yes[^1] | | Yes | Yes | Yes |
| Kong | | Yes[^1] | | Yes | Yes | Yes |
| Node | Yes | | | Yes | Yes | |
| OpenShift | Yes | Yes[^1] | | Yes | Yes | Yes |
| Pod | | Yes | Yes | Yes | | |
| Service | Yes | Yes[^1] | Yes[^1][^2] | Yes[^3] | Yes | Yes |
| Skipper | Yes | Yes[^1] | | Yes | Yes | Yes |
| Traefik | | Yes[^1] | | Yes | Yes | Yes |
| Source | controller | hostname | internal-hostname | target | ttl | (provider-specific) | ingress |
|--------------|------------|----------|-------------------|---------|---------|---------------------|:-------:|
| Ambassador | | | | Yes | Yes | Yes | No |
| Connector | | | | | | | No |
| Contour | Yes | Yes[^1] | | Yes | Yes | Yes | No |
| CloudFoundry | | | | | | | No |
| CRD | | | | | | | No |
| F5 | | | | Yes | Yes | | No |
| Gateway | Yes | Yes[^1] | | Yes[^4] | Yes | Yes | No |
| Gloo | | | | Yes | Yes[^5] | Yes[^5] | No |
| Ingress | Yes | Yes[^1] | | Yes | Yes | Yes | No |
| Istio | Yes | Yes[^1] | | Yes | Yes | Yes | Yes |
| Kong | | Yes[^1] | | Yes | Yes | Yes | No |
| Node | Yes | | | Yes | Yes | | No |
| OpenShift | Yes | Yes[^1] | | Yes | Yes | Yes | No |
| Pod | | Yes | Yes | Yes | | | No |
| Service | Yes | Yes[^1] | Yes[^1][^2] | Yes[^3] | Yes | Yes | No |
| Skipper | Yes | Yes[^1] | | Yes | Yes | Yes | No |
| Traefik | | Yes[^1] | | Yes | Yes | Yes | No |

[^1]: Unless the `--ignore-hostname-annotation` flag is specified.
[^2]: Only behaves differently than `hostname` for `Service`s of type `ClusterIP` or `LoadBalancer`.
Expand Down Expand Up @@ -143,6 +143,17 @@ If the value is `annotation-only`, use only the domains from the `Ingress` annot

If the annotation is not present, use the domains from both the spec and annotations.

## external-dns.alpha.kubernetes.io/ingress

This annotation allows ExternalDNS to work with Istio Gateways that don't have a public IP.

It can be used to address a specific architectural pattern, when a Kubernetes Ingress directs all public traffic to the Istio Gateway:

- **The Challenge**: By default, ExternalDNS sources the public IP address for a DNS record from a Service of type LoadBalancer.
However, in some service mesh setups, the Istio Gateway's Service is of type ClusterIP, with all public traffic routed to it via a separate Kubernetes Ingress object. This setup leaves the Gateway without a public IP that ExternalDNS can discover.

- **The Solution**: The annotation on the Istio Gateway tells ExternalDNS to ignore the Gateway's Service IP. Instead, it directs ExternalDNS to a specified Ingress resource to find the target LoadBalancer IP address.

## external-dns.alpha.kubernetes.io/internal-hostname

Specifies the domain for the resource's DNS records that are for use from internal networks.
Expand Down
16 changes: 9 additions & 7 deletions source/annotations/annotations.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,19 +40,21 @@ const (
SetIdentifierKey = AnnotationKeyPrefix + "set-identifier"
AliasKey = AnnotationKeyPrefix + "alias"
TargetKey = AnnotationKeyPrefix + "target"
// The annotation used for figuring out which controller is responsible
// ControllerKey The annotation used for figuring out which controller is responsible
ControllerKey = AnnotationKeyPrefix + "controller"
// The annotation used for defining the desired hostname
// HostnameKey The annotation used for defining the desired hostname
HostnameKey = AnnotationKeyPrefix + "hostname"
// The annotation used for specifying whether the public or private interface address is used
// AccessKey The annotation used for specifying whether the public or private interface address is used
AccessKey = AnnotationKeyPrefix + "access"
// The annotation used for specifying the type of endpoints to use for headless services
// EndpointsTypeKey The annotation used for specifying the type of endpoints to use for headless services
EndpointsTypeKey = AnnotationKeyPrefix + "endpoints-type"
// The annotation used to determine the source of hostnames for ingresses. This is an optional field - all
// Ingress the annotation used to determine if the gateway is implemented by an Ingress object
Ingress = AnnotationKeyPrefix + "ingress"
// IngressHostnameSourceKey The annotation used to determine the source of hostnames for ingresses. This is an optional field - all
// available hostname sources are used if not specified.
IngressHostnameSourceKey = AnnotationKeyPrefix + "ingress-hostname-source"
// The value of the controller annotation so that we feel responsible
// ControllerValue The value of the controller annotation so that we feel responsible
ControllerValue = "dns-controller"
// The annotation used for defining the desired hostname
// InternalHostnameKey The annotation used for defining the desired hostname
InternalHostnameKey = AnnotationKeyPrefix + "internal-hostname"
)
2 changes: 1 addition & 1 deletion source/istio_gateway.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ import (

// IstioGatewayIngressSource is the annotation used to determine if the gateway is implemented by an Ingress object
// instead of a standard LoadBalancer service type
const IstioGatewayIngressSource = "external-dns.alpha.kubernetes.io/ingress"
const IstioGatewayIngressSource = annotations.Ingress

// gatewaySource is an implementation of Source for Istio Gateway objects.
// The gateway implementation uses the spec.servers.hosts values for the hostnames.
Expand Down
Loading