diff --git a/docs/sources/gateway.md b/docs/sources/gateway.md new file mode 100644 index 0000000000..7482aaa587 --- /dev/null +++ b/docs/sources/gateway.md @@ -0,0 +1,82 @@ +# Gateway sources + +The gateway-grcproute, gateway-httproute, gateway-tcproute, gateway-tlsroute, and gateway-udproute +sources create DNS entries based on their respective `gateway.networking.k8s.io` resources. + +## Filtering the Routes considered + +These sources support the `--label-filter` flag, which filters *Route resources +by a set of labels. + +## Domain names + +To calculate the Domain names created from a *Route, this source first collects a set +of [domain names from the *Route](#domain-names-from-route). + +It then iterates over each of the `status.parents` with +a [matching Gateway](#matching-gateways) and at least one [matching listener](#matching-listeners). +For each matching listener, if the +listener has a `hostname`, it narrows the set of domain names from the *Route to the portion +that overlaps the `hostname`. If a matching listener does not have a `hostname`, it uses +the un-narrowed set of domain names. + +### Domain names from Route + +The set of domain names from a *Route is sourced from the following places: + +* If the *Route is a GRPCRoute, HTTPRoute, or TLSRoute, adds each of the`spec.hostnames`. + +* Adds the hostnames from any `external-dns.alpha.kubernetes.io/hostname` annotation on the *Route. +This behavior is suppressed if the `--ignore-hostname-annotation` flag was specified. + +* If no endpoints were produced by the previous steps +or the `--combine-fqdn-annotation` flag was specified, then adds hostnames +generated from any`--fqdn-template` flag. + +* If no endpoints were produced by the previous steps, each +attached Gateway listener will use its `hostname`, if present. + +### Matching Gateways + +Matching Gateways are discovered by iterating over the *Route's `status.parents`: + +* Ignores parents with a `parentRef.group` other than +`gateway.networking.k8s.io` or a `parentRef.kind` other than `Gateway`. + +* If the `--gateway-namespace` flag was specified, ignores parents with a `parentRef.namespace` other +than the specified value. + +* If the `--gateway-label-filter` flag was specified, ignores parents whose Gateway does not match the +specified label filter. + +* Ignores parents whose Gateway either does not exist or has not accepted the route. + +### Matching listeners + +Iterates over all listeners for the parent's `parentRef.sectionName`: + +* Ignores listeners whose `protocol` field does not match the kind of the *Route per the following table: + +| kind | protocols | +|------------|-------------| +| GRPCRoute | HTTP, HTTPS | +| HTTPRoute | HTTP, HTTPS | +| TCPRoute | TCP | +| TLSRoute | TLS | +| UDPRoute | UDP | + +* If the parent's `parentRef.port` port is specified, ignores listeners without a matching `port`. + +* Ignores listeners which specify an `allowedRoutes` which does not allow the route. + +## Targets + +The targets of the DNS entries created from a *Route are sourced from the following places: + +1. If a matching parent Gateway has an `external-dns.alpha.kubernetes.io/target` annotation, uses +the values from that. + +2. Otherwise, iterates over that parent Gateway's `status.addresses`, +adding each address's `value`. + +The targets from each parent Gateway matching the *Route are then combined and de-duplicated. diff --git a/docs/sources/sources.md b/docs/sources/sources.md index e0224c4c38..4c9dc8b93e 100644 --- a/docs/sources/sources.md +++ b/docs/sources/sources.md @@ -1,26 +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.md) | Service | Yes | Yes | -| skipper-routegroup | RouteGroup.zalando.org | Yes | | -| traefik-proxy | IngressRoute.traefik.io IngressRouteTCP.traefik.io IngressRouteUDP.traefik.io | Yes | | +| 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](gateway.md) | GRPCRoute.gateway.networking.k8s.io | Yes | Yes | +| [gateway-httproute](gateway.md) | HTTPRoute.gateway.networking.k8s.io | Yes | Yes | +| [gateway-tcproute](gateway.md) | TCPRoute.gateway.networking.k8s.io | Yes | Yes | +| [gateway-tlsroute](gateway.md) | TLSRoute.gateway.networking.k8s.io | Yes | Yes | +| [gateway-udproute](gateway.md) | 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.md) | 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 e464d717fe..8698d28b2d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,6 +16,7 @@ nav: - About: annotations/annotations.md - Sources: - About: sources/sources.md + - Gateway: sources/gateway.md - Ingress: sources/ingress.md - Service: sources/service.md - Registries: