From a269e3479514b3824143fc42c95c6015452487c1 Mon Sep 17 00:00:00 2001 From: Guilherme Cassolato Date: Tue, 27 Aug 2024 18:28:53 +0200 Subject: [PATCH] docs: Route Rule name field Signed-off-by: Guilherme Cassolato --- .../experimental/http-route-rule-name.yaml | 22 +++++++++++++ site-src/api-types/grpcroute.md | 16 ++++++++-- site-src/api-types/httproute.md | 32 +++++++++++++++---- 3 files changed, 61 insertions(+), 9 deletions(-) create mode 100644 examples/experimental/http-route-rule-name.yaml diff --git a/examples/experimental/http-route-rule-name.yaml b/examples/experimental/http-route-rule-name.yaml new file mode 100644 index 0000000000..86da65ccb5 --- /dev/null +++ b/examples/experimental/http-route-rule-name.yaml @@ -0,0 +1,22 @@ +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: example-route +spec: + parentRefs: + - name: example-gateway + rules: + - name: read-only + matches: + - method: GET + backendRefs: + - name: backend-mirror-svc + port: 8080 + - name: write-only + matches: + - method: POST + - method: PATCH + - method: DELETE + backendRefs: + - name: backend-svc + port: 8080 diff --git a/site-src/api-types/grpcroute.md b/site-src/api-types/grpcroute.md index b57ae43bcc..88a0369661 100644 --- a/site-src/api-types/grpcroute.md +++ b/site-src/api-types/grpcroute.md @@ -65,8 +65,8 @@ The specification of a GRPCRoute consists of: matching the Host header of gRPC requests. - [Rules][grpcrouterule]- Define a list of rules to perform actions against matching gRPC requests. Each rule consists of [matches][matches], - [filters][filters] (optional), and [backendRefs][backendRef] (optional) - fields. + [filters][filters] (optional), [backendRefs][backendRef] (optional), and + [name][name] (optional) fields. The following illustrates a GRPCRoute that sends all traffic to one Service: @@ -217,6 +217,18 @@ Service: Reference the [backendRef][backendRef] API documentation for additional details on `weight` and other fields. +#### Name (optional) + +??? example "Experimental Channel since v1.2.0" + + This concept has been part of the Experimental Channel since `v1.2.0`. + For more information on release channels, refer to our + [versioning guide](/concepts/versioning). + +GRPCRoute Rules include an optional `name` field. The applications for the name of a route rule are implementation-specific. It can be used to reference individual route rules by name from other resources, such as in the `sectionName` field of metaresources ([GEP-2648](https://gateway-api.sigs.k8s.io/geps/gep-2648/#apply-policies-to-sections-of-a-resource)), in the status stanzas of resources related to the route object, to identify internal configuration objects generated by the implementation from GRPCRoute Rule, etc. + +If specified, the value of the name field must comply with the [`SectionName`](https://github.com/kubernetes-sigs/gateway-api/blob/v1.0.0/apis/v1/shared_types.go#L607-L624) type. + ## Status Status defines the observed state of the GRPCRoute. diff --git a/site-src/api-types/httproute.md b/site-src/api-types/httproute.md index 52c671fa73..6f63506f02 100644 --- a/site-src/api-types/httproute.md +++ b/site-src/api-types/httproute.md @@ -19,8 +19,8 @@ The specification of an HTTPRoute consists of: 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), [backendRefs][backendRef] (optional) and [timeouts][timeouts] (optional) - fields. + [filters][filters] (optional), [backendRefs][backendRef] (optional), + [timeouts][timeouts] (optional), and [name][name] (optional) fields. The following illustrates an HTTPRoute that sends all traffic to one Service: ![httproute-basic-example](/images/httproute-basic-example.svg) @@ -193,7 +193,7 @@ Conformance levels are defined by the filter type: - Implementers are encouraged to support "extended" filters. - "Implementation-specific" filters have no API guarantees across implementations. -Specifying a core filter multiple times has unspecified or +Specifying a core filter multiple times has unspecified or implementation-specific conformance. All filters are expected to be compatible with each other except for the @@ -233,7 +233,7 @@ on `weight` and other fields. ??? example "Experimental Channel since v1.0.0" HTTPRoute timeouts have been part of the Experimental Channel since `v1.0.0`. - For more information on release channels, refer to our + For more information on release channels, refer to our [versioning guide](/concepts/versioning). HTTPRoute Rules include a `Timeouts` field. If unspecified, timeout behavior is implementation-specific. @@ -256,16 +256,34 @@ The following example uses the `request` field which will cause a timeout if a c Reference the [timeouts][timeouts] API documentation for additional details. +#### Name (optional) + +??? example "Experimental Channel since v1.2.0" + + This concept has been part of the Experimental Channel since `v1.2.0`. + For more information on release channels, refer to our + [versioning guide](/concepts/versioning). + +HTTPRoute Rules include an optional `name` field. The applications for the name of a route rule are implementation-specific. It can be used to reference individual route rules by name from other resources, such as in the `sectionName` field of metaresources ([GEP-2648](https://gateway-api.sigs.k8s.io/geps/gep-2648/#apply-policies-to-sections-of-a-resource)), in the status stanzas of resources related to the route object, to identify internal configuration objects generated by the implementation from HTTPRoute Rule, etc. + +If specified, the value of the name field must comply with the [`SectionName`](https://github.com/kubernetes-sigs/gateway-api/blob/v1.0.0/apis/v1/shared_types.go#L607-L624) type. + +The following example specifies the `name` field to identify HTTPRoute Rules used to split traffic between a _read-only_ backend service and a _write-only_ one: + +```yaml +{% include 'experimental/http-route-rule-name.yaml' %} +``` + ##### Backend Protocol ??? example "Experimental Channel since v1.0.0" This concept has been part of the Experimental Channel since `v1.0.0`. - For more information on release channels, refer to our + For more information on release channels, refer to our [versioning guide](/concepts/versioning). -Some implementations may require the [backendRef][backendRef] to be labeled -explicitly in order to route traffic using a certain protocol. For Kubernetes +Some implementations may require the [backendRef][backendRef] to be labeled +explicitly in order to route traffic using a certain protocol. For Kubernetes Service backends this can be done by specifying the [`appProtocol`][appProtocol] field.