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

Documenting Route attachment for v1alpha2 #762

Merged
merged 1 commit into from
Aug 13, 2021
Merged

Documenting Route attachment for v1alpha2 #762

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.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions site-src/v1alpha2/api-types/gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
77 changes: 30 additions & 47 deletions site-src/v1alpha2/api-types/httproute.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,44 +7,37 @@ 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 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.
- [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

Expand All @@ -61,16 +54,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
```
Expand Down Expand Up @@ -136,9 +126,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.
Expand All @@ -150,19 +140,14 @@ 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:
```yaml
{% 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
Expand All @@ -173,13 +158,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":
Expand All @@ -190,30 +176,27 @@ metadata:
name: http-example
...
status:
gateways:
- gatewayRef:
parents:
- parentRefs:
name: gw-example
namespace: gw-example-ns
conditions:
- type: Admitted
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
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
[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

Loading