Merge pull request #3806 from johngmyers/doc-sources

Document the Ingress source

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`. 

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               |              |

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

pkg/apis/externaldns/types.go

@@ -416,20 +416,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("namespace", "Limit resources queried for 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("annotation-filter", "Filter resources queried for endpoints by annotation, using label selector semantics").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("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("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-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 tls spec section in ingresses resources, applicable only for ingress sources (optional, default: false)").BoolVar(&cfg.IgnoreIngressTLSSpec)
+	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)

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
-			}
 		}
 
 		if len(ingEndpoints) == 0 {