diff --git a/site-src/v1alpha2/api-types/gateway.md b/site-src/v1alpha2/api-types/gateway.md index 54cb8401df..e138b7abbc 100644 --- a/site-src/v1alpha2/api-types/gateway.md +++ b/site-src/v1alpha2/api-types/gateway.md @@ -12,7 +12,7 @@ The `Gateway` spec defines the following: * `GatewayClassName`- Defines the name of a `GatewayClass` object used by this Gateway. * `Listeners`- Define the hostnames, ports, protocol, termination, TLS - settings and which routes should be associated to a listener. + settings and which routes can be attached to a listener. * `Addresses`- Define the network addresses requested for this gateway. If the desired configuration specified in Gateway spec cannot be achieved, the @@ -39,8 +39,8 @@ desired state represented in `spec`. `GatewayStatus` consists of the following: - `Addresses`- Lists the IP addresses that have actually been bound to the Gateway. -- `Listeners`- Provide status for each unique listener port defined in `spec`. -- `Conditions`- Describe the current status conditions of the Gateway. +- `Listeners`- Provide status for each unique listener defined in `spec`. +- `Conditions`- Describe the current status conditions of the Gateway. Both `Conditions` and `Listeners.conditions` follow the conditions pattern used elsewhere in Kubernetes. This is a list that includes a type of condition, the diff --git a/site-src/v1alpha2/api-types/httproute.md b/site-src/v1alpha2/api-types/httproute.md index a6ab4b81bc..8b267d7031 100644 --- a/site-src/v1alpha2/api-types/httproute.md +++ b/site-src/v1alpha2/api-types/httproute.md @@ -7,46 +7,39 @@ of HTTP requests from a Gateway listener to an API object, i.e. Service. The specification of an HTTPRoute consists of: -- [Gateways][gateways]- Define which Gateways can use this HTTPRoute. +- [ParentRefs][parentRef]- Define which Gateways (or other resources) this Route + wants to be attached to. - [Hostnames][hostname] (optional)- Define a list of hostnames to use for matching the Host header of HTTP requests. - [TLS][tls-config] (optional)- Defines the TLS certificate to use for Hostnames defined in this Route. - [Rules][httprouterule]- Define a list of rules to perform actions against - matching HTTP requests. Each rule consists - of [matches][matches], [filters][filters] (optional), and [forwardTo][forwardto] - (optional) fields. + matching HTTP requests. Each rule consists of [matches][matches], + [filters][filters] (optional), and [backendRefs][backendRef] (optional) + fields. The following illustrates an HTTPRoute that sends all traffic to one Service: ![httproute-basic-example](/images/httproute-basic-example.svg) -### Gateways +### Attaching to Gateways -Gateways define which Gateways can use the HTTPRoute. If unspecified, `gateways` -defaults to `allow: SameNamespace` which allows all Gateways in the HTTPRoute's -namespace. +Each Route includes a way to reference the parent resources it wants to attach +to. In most cases, that's going to be Gateways, but there is some flexibility +here for implementations to support other types of parent resources. -The following example allows Gateways from namespace "httproute-ns-example": +The following example shows how a Route would attach to the `acme-lb` Gateway: ```yaml kind: HTTPRoute apiVersion: gateway.networking.k8s.io/v1alpha1 metadata: name: httproute-example - namespace: httproute-ns-example spec: - gateways: - allow: SameNamespace + parentRefs: + name: acme-lb ``` -Possible values for `allow` are: - -- `All`: Gateways in any namespace can use this route. -- `FromList`: Only Gateways specified in `gatewayRefs` may use this route. -- `SameNamespace` (default): Only Gateways in the same namespace may use this - route. - -If `allow` results in preventing the selection of an HTTPRoute by a Gateway, an -“Admitted: false” condition must be set on the Gateway for this Route. +Note that the target Gateway needs to allow HTTPRoutes from the route's +namespace to be attached for the attachment to be successful. ### Hostnames @@ -63,16 +56,13 @@ Incoming requests are matched against hostnames before the HTTPRoute rules are evaluated. If no hostname is specified, traffic is routed based on HTTPRoute rules and filters (optional). -The following example defines hostname "my.example.com" and allows Gateways -from the same namespace as HTTPRoute "httproute-example": +The following example defines hostname "my.example.com": ```yaml kind: HTTPRoute apiVersion: gateway.networking.k8s.io/v1alpha1 metadata: name: httproute-example spec: - gateways: - allow: SameNamespace hostnames: - my.example.com ``` @@ -161,9 +151,9 @@ Conformance levels are defined by the filter type: Specifying a core filter multiple times has unspecified or custom conformance. -#### ForwardTo (optional) +#### BackendRefs (optional) -ForwardTo defines API objects where matching requests should be sent. If +BackendRefs defines API objects where matching requests should be sent. If unspecified, the rule performs no forwarding. If unspecified and no filters are specified that would result in a response being sent, a 503 error code is returned. @@ -175,11 +165,6 @@ header `magic: foo` to service "my-service2" on port `8080`: {% include 'basic-http.yaml' %} ``` -**Note:** Forwarding to a custom resource instead of a service can be -accomplished by specifying `backendRef` instead of `serviceName`. A -`backendRef` follows the standard Kubernetes `group`, `kind` and `name` -schema. - The following example uses the `weight` field to forward HTTP requests for prefix `/bar` equally across service "my-trafficsplit-svc1" and service "my-trafficsplit-svc2", i.e. traffic splitting: @@ -187,7 +172,7 @@ prefix `/bar` equally across service "my-trafficsplit-svc1" and service {% include 'http-trafficsplit.yaml' %} ``` -Reference the [forwardTo][forwardto] API documentation for additional details +Reference the [backendRef][backendRef] API documentation for additional details of `weight` and other fields. ## Status @@ -198,13 +183,14 @@ Status defines the observed state of HTTPRoute. RouteStatus defines the observed state that is required across all route types. -#### Gateways +#### Parents -Gateways define a list of the Gateways that are associated with the HTTPRoute, -and the status of the HTTPRoute with respect to each of these Gateways. When a -Gateway selects this HTTPRoute, the controller that manages the Gateway should -add an entry to this list when the controller first sees the route and should -update the entry as appropriate when the route is modified. +Parents define a list of the Gateways (or other parent resources) that are +associated with the HTTPRoute, and the status of the HTTPRoute with respect to +each of these Gateways. When a HTTPRoute adds a reference to a Gateway in +parentRefs, the controller that manages the Gateway should add an entry to this +list when the controller first sees the route and should update the entry as +appropriate when the route is modified. The following example indicates HTTPRoute "http-example" has been admitted by Gateway "gw-example" in namespace "gw-example-ns": @@ -215,8 +201,8 @@ metadata: name: http-example ... status: - gateways: - - gatewayRef: + parents: + - parentRefs: name: gw-example namespace: gw-example-ns conditions: @@ -224,10 +210,6 @@ status: status: "True" ``` -A maximum of 100 Gateways can be represented in this list. If this list is full, -there may be additional Gateways using this Route that are not included in the -list. - ### Merging Multiple HTTPRoutes can be attached to a single Gateway resource. Importantly, only one Route rule may match each request. For more information on how conflict @@ -235,11 +217,12 @@ resolution applies to merging, refer to the [API specification](httprouterule). [httproute]: https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute -[gateways]: https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.RouteGateways [httprouterule]: https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRouteRule [hostname]: https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Hostname [tls-config]: https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.RouteTLSConfig [rfc-3986]: https://tools.ietf.org/html/rfc3986 [matches]: https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRouteMatch [filters]: https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRouteFilter -[forwardto]: https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRouteForwardTo +[backendRef]: https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPBackendRef +[parentRef]: https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ParentRef + diff --git a/site-src/v1alpha2/concepts/api-overview.md b/site-src/v1alpha2/concepts/api-overview.md index 8a9f380ae8..2e57666bc3 100644 --- a/site-src/v1alpha2/concepts/api-overview.md +++ b/site-src/v1alpha2/concepts/api-overview.md @@ -17,9 +17,10 @@ section in the Security model for details. ## Resource model -> Note: Resources will initially live in the `gateway.networking.k8s.io` API group as -> Custom Resource Definitions (CRDs). Unqualified resource names will implicitly -> be in this API group. +!!! note + Gateway API Resources live in the `gateway.networking.k8s.io` API group as + Custom Resource Definitions (CRDs). Unqualified resource names will + implicitly be in this API group. There are three main types of objects in our resource model: @@ -67,148 +68,89 @@ GatewayClass. As the Gateway spec captures user intent, it may not contain a complete specification for all attributes in the spec. For example, the user may omit -fields such as addresses, TLS settings. This allows the controller -managing the GatewayClass to provide these settings for the user, resulting in a -more portable spec. This behaviour will be made clear using the GatewayClass -Status object. +fields such as addresses, TLS settings. This allows the controller managing the +GatewayClass to provide these settings for the user, resulting in a more +portable spec. This behaviour will be made clear using the GatewayClass Status +object. -A Gateway MAY contain one or more *Route references which serve to direct -traffic for a subset of traffic to a specific service.* - -### {HTTP,TCP,Foo}Route +### Routes Route objects define protocol-specific rules for mapping requests from a Gateway -to Kubernetes Services. - -`HTTPRoute` and `TCPRoute` are currently the only defined Route objects. -Additional protocol-specific Route objects may be added in the future. - -### Route binding - -When a Route binds to a Gateway it represents configuration that is applied on -the Gateway that configures the underlying load balancer or proxy. How and which -Routes bind to Gateways is controlled by the resources themselves. Route and -Gateway resources have built-in controls to permit or constrain how they select -each other. This is useful for enforcing organizational policies for how Routes -are exposed and on which Gateways. Consider the following example: - -> A Kubernetes cluster admin has deployed a Gateway “shared-gw” in the “Infra” -> Namespace to be used by different application teams for exposing their -> applications outside the cluster. Teams A and B (in Namespaces “A” and “B” -> respectively) bind their Routes to this Gateway. They are unaware of each other -> and as long as their Route rules do not conflict with each other they can -> continue operating in isolation. Team C has special networking needs (perhaps -> performance, security, or criticality) and they need a dedicated Gateway to -> proxy their application to the outside world. Team C deploys their own Gateway -> “dedicated-gw” in the “C” Namespace that can only be used by apps in the "C" -> Namespace. +to Kubernetes Services. There are 4 Route resources included with the Gateway +API: - -![route binding](/images/gateway-route-binding.png) +* HTTPRoute +* TCPRoute +* TLSRoute +* UDPRoute + +Additional Route resources may be added in the future. + +## Attaching Routes to Gateways + +When a Route attaches to a Gateway, it represents configuration that is applied +on the Gateway that configures the underlying load balancer or proxy. How and +which Routes bind to Gateways is controlled by the resources themselves. Route +and Gateway resources have built-in controls to permit or constrain how they are +attached. These built-in controls along with RBAC allow organizations to enforce +policies for how Routes are exposed and on which Gateways. There is a lot of flexibility in how Routes can bind to Gateways to achieve different organizational policies and scopes of responsibility. These are different relationships that Gateways and Routes can have: - **One-to-one** - A Gateway and Route may be deployed and used by a single - owner and have a one-to-one relationship. Team C is an example of this. + owner and have a one-to-one relationship. - **One-to-many** - A Gateway can have many Routes bound to it that are owned by - different teams from across different Namespaces. Teams A and B are an example - of this. + different teams from across different Namespaces. - **Many-to-one** - Routes can also be bound to more than one Gateway, allowing a single Route to control application exposure simultaneously across different IPs, load balancers, or networks. -*In summary, Gateways select Routes and Routes control their exposure. When a -Gateway selects a Route that allows itself to be exposed, then the Route will -bind to the Gateway. When Routes are bound to a Gateway it means their -collective routing rules are configured on the underlying load balancers or -proxies that are managed by that Gateway. Thus, a Gateway is a logical -representation of a networking data plane that can be configured through -Routes.* - -#### Route Selection - -A Gateway selects routes based on the Route metadata, specifically the kind, -namespace, and labels of Route resources. Routes are actually bound to specific -listeners within the Gateway so each listener has a `listener.routes` field -which selects Routes by one or more of the following criterea: - -- **Label** - A Gateway can select Routes via labels that exist on the -resource (similar to how Services select Pods via Pod labels). -- **Kind** - A Gateway listener can only select a single type of Route -resource. This could be an HTTPRoute, TCPRoute, or a custom Route type. -- **Namespace** - A Gateway can also control from which Namespaces Routes can be -selected via the `namespaces.from` field. It supports three possible values: - - `SameNamespace` is the default option. Only Routes in the same namespace - as this Gateway will be selected. - - `All` will select Routes from all Namespaces. - - `Selector` means that Routes from a subset of Namespaces selected by a - Namespace label selector will be selected by this Gateway. When `Selector` - is used then the `listeners.routes.namespaces.selector` field can be used - to specify label selectors. This field is not supported with `All` or +### Example + +A Kubernetes cluster admin has deployed a Gateway `shared-gw` in the `Infra` +Namespace to be used by different application teams for exposing their +applications outside the cluster. Teams A and B (in Namespaces `A` and `B` +respectively) bind their Routes to this Gateway. They are unaware of each +other and as long as their Route rules do not conflict with each other they +can continue operating in isolation. Team C has special networking needs +(perhaps performance, security, or criticality) and they need a dedicated +Gateway to proxy their application to the outside world. Team C deploys their +own Gateway `dedicated-gw` in the `C` Namespace that can only be used by apps +in the `C` Namespace. + + +![route binding](/images/gateway-route-binding.png) + +### How it Works + +The following is required for a Route to be attached to a Gateway: + +1. The Route needs an entry in its `parentRefs` field referencing the Gateway. +2. At least one listener on the Gateway needs to allow this attachment. + +Each Gateway listener can restrict which Routes can be attached with the +following mechanisms: + +1. **Hostname:** When the `hostname` field on a listener is set, attached Routes + that specify a `hostnames` field must have at least one overlapping value. +2. **Namespaces:** The `namespaces` field on a listener can be used to restrict + where Routes may be attached from. The `namespaces.from` field supports the + following values: + * `SameNamespace` is the default option. Only Routes in the same namespace + as this Gateway may be attached. + * `All` will allow Routes from all Namespaces to be attached. + * `Selector` means that Routes from a subset of Namespaces selected by a + Namespace label selector may be attached to this Gateway. When `Selector` + is used, the `listeners.routes.namespaces.selector` field must be used to + specify label selectors. This field is not supported with `All` or `SameNamespace`. +3. **Kinds:** The `kinds` field on a listener can be used to restrict the kinds + of Routes that may be attached. -The below Gateway will select all HTTPRoute resources with the `expose: -prod-web-gw` across all Namespaces in the cluster. - -``` -kind: Gateway -... -spec: - listeners: - - routes: - kind: HTTPRoute - selector: - matchLabels: - expose: prod-web-gw - namespaces: - from: All -``` - -#### Route Exposure - -Routes can determine how they are exposed through Gateways. The `gateways.allow` -field supports three values: - -- `All` is the default value if none is specified. This leaves all binding -to the Route label and Namespace selectors on the Gateway. -- `SameNamespace` only allows this Route to bind with Gateways from the -same Namespace. -- `FromList` allows an explicit list of Gateways to be specifiied that a -Route will bind with. `gateways.gatewayRefs` is only supported with this option. - -The following `my-route` Route selects only the `foo-gateway` in the -`foo-namespace` and will not be able to bind with any other Gateways. Note that -`foo-gateway` is in a different Namespace. If the `foo-gateway` allows -cross-Namespace binding and also selects this Route then `my-route` will bind to -it. - -```yaml -kind: HTTPRoute -metadata: - name: my-route - namespace: bar-namespace -spec: - gateways: - allow: FromList - gatewayRefs: - - name: foo-gateway - namespace: foo-namespace -``` - -Note that Gateway and Route binding is bi-directional. This means that both -resources must select each other for them to bind. If a Gateway has Route label -selectors that do not match any existing Route then nothing will bind to it even -if a Route's `spec.gateways.allow = All`. Similarly, if a Route references a -specific Gateway, but that Gateway is not selecting the Route's Namespace, then -they will not bind. A binding will only take place if both resources select each -other. - -It may not always be apparent from the resource specifications which Gateways -and Routes are bound, but binding can be determined from the resource status. -The [Route status](/api-types/httproute#routestatus) will list all of the Gateways that -a Route is bound to and any relevant conditions for the binding. +If none of the above are specified, a Gateway listener will trust Routes +attached from the same namespace that support the listener protocol. ### Combined types diff --git a/site-src/v1alpha2/concepts/security-model.md b/site-src/v1alpha2/concepts/security-model.md index 9d3745dbfb..deb551c785 100644 --- a/site-src/v1alpha2/concepts/security-model.md +++ b/site-src/v1alpha2/concepts/security-model.md @@ -96,14 +96,11 @@ configuration](https://github.com/open-policy-agent/gatekeeper-library/pull/24) that could be used for this. ## Route Namespaces -Gateway API allow Gateways to select Routes across multiple Namespaces. +Gateway API enables Routes to be attached to Gateways from different Namespaces. Although this can be remarkably powerful, this capability needs to be used -carefully. Gateways include a `RouteNamespaces` field that allows selecting -multiple namespaces with a label selector. By default, this is limited to Routes -in the same namespace as the Gateway. Additionally, Routes include a `Gateways` -field that allows them to restrict which Gateways use them. If the Gateways -field is not specified (i.e. its empty), then the Route will default to allowing -selection by Gateways in the same namespace. +carefully. Gateway Listeners include a `namespaces` field that can allow Routes +to be attached from additional namespaces. By default, this is limited to Routes +in the same namespace as the Gateway. ## Controller Requirements To be considered conformant with the Gateway API spec, controllers need to: