From 0eb91e358daa00b0c9dca0074c5b26947f008d0e Mon Sep 17 00:00:00 2001 From: John Gardiner Myers Date: Tue, 4 Jul 2023 19:09:51 -0700 Subject: [PATCH] Document the Ingress source --- docs/sources/ingress.md | 48 +++++++++++++++++++++++++++++++++++ docs/sources/sources.md | 26 +++++++++++++++++++ mkdocs.yml | 3 +++ pkg/apis/externaldns/types.go | 16 ++++++------ source/ingress.go | 6 +---- 5 files changed, 86 insertions(+), 13 deletions(-) create mode 100644 docs/sources/ingress.md create mode 100644 docs/sources/sources.md diff --git a/docs/sources/ingress.md b/docs/sources/ingress.md new file mode 100644 index 000000000..f622a10fc --- /dev/null +++ b/docs/sources/ingress.md @@ -0,0 +1,48 @@ +# Ingress source + +The ingress source creates DNS entries based on `Ingress.networking.k8s.io` resources. + +## Filtering the Ingresses considered + +The `--ingress-class` flag filters Ingress resources by a set of ingress classes. +The flag may be specified multiple times in order to +allow multiple ingress classes. + +This source supports the `--label-filter` flag, which filters Ingress resources +by a set of labels. + +## Domain names + +The domain names of the DNS entries created from an Ingress are sourced from the following places: + +* Iterates over the Ingress's `spec.rules`, adding any non-empty `host`. + + This behavior is suppressed if the `--ignore-ingress-rules-spec` flag was specified +or the Ingress had an +`external-dns.alpha.kubernetes.io/ingress-hostname-source: annotation-only` annotation. + +* Iterates over the Ingress's `spec.tls`, adding each member of `hosts`. + + This behavior is suppressed if the `--ignore-ingress-tls-spec` flag was specified +or the Ingress had an +`external-dns.alpha.kubernetes.io/ingress-hostname-source: annotation-only` annotation, + +* Adds the hostnames from any `external-dns.alpha.kubernetes.io/hostname` annotation. + + This behavior is suppressed if the `--ignore-hostname-annotation` flag was specified +or the Ingress had an +`external-dns.alpha.kubernetes.io/ingress-hostname-source: defined-hosts-only` annotation. + +* If no endpoints were produced for an Ingress by the previous steps +or the `--combine-fqdn-annotation` flag was specified, then adds hostnames +generated from any`--fqdn-template` flag. + +## Targets + +The targets of the DNS entries created from an Ingress are sourced from the following places: + +* If the Ingress has an `external-dns.alpha.kubernetes.io/target` annotation, uses +the values from that. + +* Otherwise, iterates over the Ingress's `status.loadBalancer.ingress`, +adding each non-empty `ip` and `hostname`. diff --git a/docs/sources/sources.md b/docs/sources/sources.md new file mode 100644 index 000000000..7506bbce3 --- /dev/null +++ b/docs/sources/sources.md @@ -0,0 +1,26 @@ +# Sources + +| Source | Resources | annotation-filter | label-filter | +|-----------------------|-------------------------------------------------------------------------------|-------------------|--------------| +| ambassador-host | Host.getambassador.io | | | +| connector | | | | +| contour-httpproxy | HttpProxy.projectcontour.io | Yes | | +| cloudfoundry | | | | +| crd | DNSEndpoint.externaldns.k8s.io | Yes | Yes | +| f5-virtualserver | VirtualServer.cis.f5.com | Yes | | +| gateway-grpcroute | GRPCRoute.gateway.networking.k8s.io | Yes | Yes | +| gateway-httproute | HTTPRoute.gateway.networking.k8s.io | Yes | Yes | +| gateway-tcproute | TCPRoute.gateway.networking.k8s.io | Yes | Yes | +| gateway-tlsroute | TLSRoute.gateway.networking.k8s.io | Yes | Yes | +| gateway-udproute | UDPRoute.gateway.networking.k8s.io | Yes | Yes | +| gloo-proxy | Proxy.gloo.solo.io | | | +| [ingress](ingress.md) | Ingress.networking.k8s.io | Yes | Yes | +| istio-gateway | Gateway.networking.istio.io | Yes | | +| istio-virtualservice | VirtualService.networking.istio.io | Yes | | +| kong-tcpingress | TCPIngress.configuration.konghq.com | Yes | | +| node | Node | Yes | | +| openshift-route | Route.route.openshift.io | Yes | Yes | +| pod | Pod | | | +| service | Service | Yes | Yes | +| skipper-routegroup | RouteGroup.zalando.org | Yes | | +| traefik-proxy | IngressRoute.traefik.io IngressRouteTCP.traefik.io IngressRouteUDP.traefik.io | Yes | | diff --git a/mkdocs.yml b/mkdocs.yml index 471428721..b9ee2801e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,6 +14,9 @@ nav: - Tutorials: tutorials/ - Annotations: - About: annotations/annotations.md + - Sources: + - About: sources/sources.md + - Ingress: sources/ingress.md - Registries: - About: registry/registry.md - TXT: registry/txt.md diff --git a/pkg/apis/externaldns/types.go b/pkg/apis/externaldns/types.go index e8ff36636..c652ef1ed 100644 --- a/pkg/apis/externaldns/types.go +++ b/pkg/apis/externaldns/types.go @@ -413,20 +413,20 @@ func (cfg *Config) ParseFlags(args []string) error { app.Flag("skipper-routegroup-groupversion", "The resource version for skipper routegroup").Default(source.DefaultRoutegroupVersion).StringVar(&cfg.SkipperRouteGroupVersion) // Flags related to processing source - app.Flag("source", "The resource types that are queried for endpoints; specify multiple times for multiple sources (required, options: service, ingress, node, fake, connector, gateway-httproute, gateway-grpcroute, gateway-tlsroute, gateway-tcproute, gateway-udproute, istio-gateway, istio-virtualservice, cloudfoundry, contour-httpproxy, gloo-proxy, crd, empty, skipper-routegroup, openshift-route, ambassador-host, kong-tcpingress, f5-virtualserver, traefik-proxy)").Required().PlaceHolder("source").EnumsVar(&cfg.Sources, "service", "ingress", "node", "pod", "gateway-httproute", "gateway-grpcroute", "gateway-tlsroute", "gateway-tcproute", "gateway-udproute", "istio-gateway", "istio-virtualservice", "cloudfoundry", "contour-httpproxy", "gloo-proxy", "fake", "connector", "crd", "empty", "skipper-routegroup", "openshift-route", "ambassador-host", "kong-tcpingress", "f5-virtualserver", "traefik-proxy") + app.Flag("source", "The resource types that are queried for endpoints; specify multiple times for multiple sources (required, options: service, ingress, node, pod, fake, connector, gateway-httproute, gateway-grpcroute, gateway-tlsroute, gateway-tcproute, gateway-udproute, istio-gateway, istio-virtualservice, cloudfoundry, contour-httpproxy, gloo-proxy, crd, empty, skipper-routegroup, openshift-route, ambassador-host, kong-tcpingress, f5-virtualserver, traefik-proxy)").Required().PlaceHolder("source").EnumsVar(&cfg.Sources, "service", "ingress", "node", "pod", "gateway-httproute", "gateway-grpcroute", "gateway-tlsroute", "gateway-tcproute", "gateway-udproute", "istio-gateway", "istio-virtualservice", "cloudfoundry", "contour-httpproxy", "gloo-proxy", "fake", "connector", "crd", "empty", "skipper-routegroup", "openshift-route", "ambassador-host", "kong-tcpingress", "f5-virtualserver", "traefik-proxy") app.Flag("openshift-router-name", "if source is openshift-route then you can pass the ingress controller name. Based on this name external-dns will select the respective router from the route status and map that routerCanonicalHostname to the route host while creating a CNAME record.").StringVar(&cfg.OCPRouterName) - app.Flag("namespace", "Limit sources of endpoints to a specific namespace (default: all namespaces)").Default(defaultConfig.Namespace).StringVar(&cfg.Namespace) - app.Flag("annotation-filter", "Filter sources managed by external-dns via annotation using label selector semantics (default: all sources)").Default(defaultConfig.AnnotationFilter).StringVar(&cfg.AnnotationFilter) - app.Flag("label-filter", "Filter sources managed by external-dns via label selector when listing all resources; currently supported by source types CRD, ingress, service and openshift-route").Default(defaultConfig.LabelFilter).StringVar(&cfg.LabelFilter) - app.Flag("ingress-class", "Require an ingress to have this class name (defaults to any class; specify multiple times to allow more than one class)").StringsVar(&cfg.IngressClassNames) + app.Flag("namespace", "Limit resources queried for endpoints to a specific namespace (default: all namespaces)").Default(defaultConfig.Namespace).StringVar(&cfg.Namespace) + app.Flag("annotation-filter", "Filter resources queried for endpoints by annotation, using label selector semantics").Default(defaultConfig.AnnotationFilter).StringVar(&cfg.AnnotationFilter) + app.Flag("label-filter", "Filter resources queried for endpoints by label selector; currently supported by source types crd, gateway-httproute, gateway-grpcroute, gateway-tlsroute, gateway-tcproute, gateway-udproute, ingress, openshift-route, and service").Default(defaultConfig.LabelFilter).StringVar(&cfg.LabelFilter) + app.Flag("ingress-class", "Require an Ingress to have this class name (defaults to any class; specify multiple times to allow more than one class)").StringsVar(&cfg.IngressClassNames) app.Flag("fqdn-template", "A templated string that's used to generate DNS names from sources that don't define a hostname themselves, or to add a hostname suffix when paired with the fake source (optional). Accepts comma separated list for multiple global FQDN.").Default(defaultConfig.FQDNTemplate).StringVar(&cfg.FQDNTemplate) app.Flag("combine-fqdn-annotation", "Combine FQDN template and Annotations instead of overwriting").BoolVar(&cfg.CombineFQDNAndAnnotation) - app.Flag("ignore-hostname-annotation", "Ignore hostname annotation when generating DNS names, valid only when using fqdn-template is set (optional, default: false)").BoolVar(&cfg.IgnoreHostnameAnnotation) - app.Flag("ignore-ingress-tls-spec", "Ignore tls spec section in ingresses resources, applicable only for ingress sources (optional, default: false)").BoolVar(&cfg.IgnoreIngressTLSSpec) + app.Flag("ignore-hostname-annotation", "Ignore hostname annotation when generating DNS names, valid only when --fqdn-template is set (default: false)").BoolVar(&cfg.IgnoreHostnameAnnotation) + app.Flag("ignore-ingress-tls-spec", "Ignore the spec.tls section in Ingress resources (default: false)").BoolVar(&cfg.IgnoreIngressTLSSpec) app.Flag("gateway-namespace", "Limit Gateways of Route endpoints to a specific namespace (default: all namespaces)").StringVar(&cfg.GatewayNamespace) app.Flag("gateway-label-filter", "Filter Gateways of Route endpoints via label selector (default: all gateways)").StringVar(&cfg.GatewayLabelFilter) app.Flag("compatibility", "Process annotation semantics from legacy implementations (optional, options: mate, molecule, kops-dns-controller)").Default(defaultConfig.Compatibility).EnumVar(&cfg.Compatibility, "", "mate", "molecule", "kops-dns-controller") - app.Flag("ignore-ingress-rules-spec", "Ignore rules spec section in ingresses resources, applicable only for ingress sources (optional, default: false)").BoolVar(&cfg.IgnoreIngressRulesSpec) + app.Flag("ignore-ingress-rules-spec", "Ignore the spec.rules section in Ingress resources (default: false)").BoolVar(&cfg.IgnoreIngressRulesSpec) app.Flag("publish-internal-services", "Allow external-dns to publish DNS records for ClusterIP services (optional)").BoolVar(&cfg.PublishInternal) app.Flag("publish-host-ip", "Allow external-dns to publish host-ip for headless services (optional)").BoolVar(&cfg.PublishHostIP) app.Flag("always-publish-not-ready-addresses", "Always publish also not ready addresses for headless services (optional)").BoolVar(&cfg.AlwaysPublishNotReadyAddresses) diff --git a/source/ingress.go b/source/ingress.go index af7a9dc99..cca0ab7f6 100644 --- a/source/ingress.go +++ b/source/ingress.go @@ -162,11 +162,7 @@ func (sc *ingressSource) Endpoints(ctx context.Context) ([]*endpoint.Endpoint, e return nil, err } - if sc.combineFQDNAnnotation { - ingEndpoints = append(ingEndpoints, iEndpoints...) - } else { - ingEndpoints = iEndpoints - } + ingEndpoints = append(ingEndpoints, iEndpoints...) } if len(ingEndpoints) == 0 {