Docs: route rule name (#3299)

* Move GEP-995 to Experimental Signed-off-by: Guilherme Cassolato <[email protected]> * docs: Fix the description of the format for the name field of route rules Signed-off-by: Guilherme Cassolato <[email protected]> * docs: Route Rule name field Signed-off-by: Guilherme Cassolato <[email protected]> --------- Signed-off-by: Guilherme Cassolato <[email protected]>
kubernetes-sigs · Sep 30, 2024 · 076d830 · 076d830
1 parent 3b7ca06
commit 076d830
Show file tree

Hide file tree

Showing 5 changed files with 67 additions and 23 deletions.
diff --git a/examples/experimental/http-route-rule-name.yaml 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/geps/gep-995/index.md b/geps/gep-995/index.md
@@ -41,19 +41,10 @@ This GEP proposes to add a new optional `name` field to the [GRPCRouteRule](http
 
 ### Format
 
-The name of a route rule, if present, MUST be a string that begins with a single lowercase letter (`a-z`) and is followed by any number of characters, from 0 to a maximum of 252, that is either a letter, a digit, or any of the following symbols `-`, `_`. The value of the `name` field MUST be treated as case-sensitive.
-
-A simple regular expression that can be used to test a string conforms with the format of the `name` field for route rules, compatible with Golang's [`regexp`](https://pkg.go.dev/regexp) package, is: `^[a-z][-_a-zA-Z0-9]{0,252}$`. (Provided as example)
-
-A set of [kubebuilder](https://book.kubebuilder.io/reference/markers/crd-validation) annotations for the validation of patterns compatible with the `name` field, to be used in CRDs, is: (Provided as example)
-
-```yaml
-// +kubebuilder:validation:Pattern=`^[a-z][-_a-zA-Z0-9]*$`
-// +kubebuilder:validation:MinLength=1
-// +kubebuilder:validation:MaxLength=253
-```
-
-This format for the `name` field of route rules differs from the pattern adopted for the [`SectionName`](https://github.com/kubernetes-sigs/gateway-api/blob/f544a46ef92b7f234ee3e7bf50da35b05f862c35/apis/v1/shared_types.go#L624C10-L624C10) type, which was thought for specifying mainly DNS subdomain names ([RFC 1123](https://www.rfc-editor.org/rfc/rfc1123)), due to its use in the gateway listeners originally.
+If specified, the name of a route rule MUST comply with the [`SectionName`](https://github.com/kubernetes-sigs/gateway-api/blob/v1.0.0/apis/v1/shared_types.go#L607-L624) type:
+- starts and ends with a lower case Latin letter (`a-z`) or digit (`0-9`);
+- accepts any lower case Latin letter (`a-z`), digits (`0-9`), and the following special characters: `-`, `.`;
+- contains a minimum of 1 and maximum of 253 characters.
 
 ### Volition
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -123,7 +123,8 @@ nav:
       - geps/gep-1867/index.md
       - geps/gep-2648/index.md
       - geps/gep-2649/index.md
-    # - Implementable:
+    - Implementable:
+      - geps/gep-3155/index.md
     - Experimental:
       - geps/gep-995/index.md
       - geps/gep-1619/index.md

diff --git 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.
 
 <!--- Editable SVG available at site-src/images/grpcroute-basic-example.svg -->
 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
@@ -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.