Skip to content
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

Jump to bottom

Document the Gateway sources #3936

Merged
merged 1 commit into from
Sep 19, 2023
Merged

Document the Gateway sources #3936

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
82 changes: 82 additions & 0 deletions docs/sources/gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
48 changes: 24 additions & 24 deletions docs/sources/sources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 | |
1 change: 1 addition & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down