Merge pull request #2533 from kubernetes-sigs/v1-docs

k8s-ci-robot · web-flow · commit d3eade088bde · 2023-10-31T18:26:18.000+01:00
v1.0 docs
diff --git a/examples/experimental/http-route-timeouts/timeout-example.yaml b/examples/experimental/http-route-timeouts/timeout-example.yaml
@@ -0,0 +1,18 @@
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: timeout-example
+spec:
+  parentRefs:
+  - name: example-gateway
+  rules:
+  - matches:
+    - path:
+        type: PathPrefix
+        value: /timeout
+    timeouts:
+      request: 10s
+      backendRequest: 2s
+    backendRefs:
+    - name: timeout-svc
+      port: 8080
diff --git a/examples/experimental/v1alpha2/backendtlspolicy-ca-certs.yaml b/examples/experimental/v1alpha2/backendtlspolicy-ca-certs.yaml
@@ -0,0 +1,17 @@
+#$ Used in:
+#$ - site-src/guides/tls.md
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: BackendTLSPolicy
+metadata:
+  name: tls-upstream-auth
+spec:
+  targetRef:
+    kind: Service
+    name: auth-service
+    group: ""
+  tls:
+    caCertRefs:
+      - kind: ConfigMapReference
+        name: auth-cert
+        group: ""
+    hostname: auth.example.com
diff --git a/examples/experimental/v1alpha2/backendtlspolicy-system-certs.yaml b/examples/experimental/v1alpha2/backendtlspolicy-system-certs.yaml
@@ -0,0 +1,14 @@
+#$ Used in:
+#$ - site-src/guides/tls.md
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: BackendTLSPolicy
+metadata:
+  name: tls-upstream-dev
+spec:
+  targetRef:
+    kind: Service
+    name: dev-service
+    group: ""
+  tls:
+    wellKnownCACerts: "System"
+    hostname: dev.example.com
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -79,6 +79,7 @@ nav:
     - TCP routing: guides/tcp.md
     - gRPC Routing: guides/grpc-routing.md
     - Migrating from Ingress: guides/migrating-from-ingress.md
+    - Backend Protocol Selection: guides/backend-protocol.md
   - Reference:
     - Implementer's Guide: reference/implementers-guide.md
     - API Types:
diff --git a/site-src/api-types/httproute.md b/site-src/api-types/httproute.md
@@ -17,7 +17,7 @@ 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), and [backendRefs][backendRef] (optional)
+  [filters][filters] (optional), [backendRefs][backendRef] (optional) and [timeouts][timeouts] (optional)
   fields.
 
 The following illustrates an HTTPRoute that sends all traffic to one Service:
@@ -165,6 +165,44 @@ Service:
 Reference the [backendRef][backendRef] API documentation for additional details
 on `weight` and other fields.
 
+#### Timeouts (optional)
+
+??? example "Experimental Channel in v1.0.0+"
+
+    HTTPRoute timeouts are part of the Experimental Channel in `v1.0.0+`.
+
+HTTPRoute Rules include a `Timeouts` field. If unspecified, timeout behavior is implementation-specific.
+
+There are 2 kinds of timeouts that can be configured in an HTTPRoute Rule:
+
+1. `request` is the timeout for the Gateway API implementation to send a response to a client HTTP request. This timeout is intended to cover as close to the whole request-response transaction as possible, although an implementation MAY choose to start the timeout after the entire request stream has been received instead of immediately after the transaction is initiated by the client.
+
+2. `backendRequest` is a timeout for a single request from the Gateway to a backend. This timeout covers the time from when the request first starts being sent from the gateway to when the full response has been received from the backend. This can be particularly helpful if the Gateway retries connections to a backend.
+
+Because the `request` timeout encompasses the `backendRequest` timeout, the value of `backendRequest` must not be greater than the value of `request` timeout.
+
+Timeouts are optional, and their fields are of type [Duration](/geps/gep-2257/). A zero-valued timeout ("0s") MUST be interpreted as disabling the timeout. A valid non-zero-valued timeout MUST be >= 1ms.
+
+The following example uses the `request` field which will cause a timeout if a client request is taking longer than 10 seconds to complete. The example also defines a 2s `backendRequest` which specifies a timeout for an individual request from the gateway to a backend service `timeout-svc`:
+```yaml
+{% include 'experimental/http-route-timeouts/timeout-example.yaml' %}
+```
+
+Reference the [timeouts][timeouts] API documentation for additional details.
+
+##### Backend Protocol
+
+??? example "Experimental Channel in v1.0.0+"
+
+    This concept is part of the Experimental Channel in `v1.0.0+`.
+
+
+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.
+
+
 ## Status
 
 Status defines the observed state of HTTPRoute.
@@ -214,4 +252,5 @@ resolution applies to merging, refer to the [API specification][httprouterule].
 [filters]: /reference/spec/#gateway.networking.k8s.io/v1beta1.HTTPRouteFilter
 [backendRef]: /reference/spec/#gateway.networking.k8s.io/v1beta1.HTTPBackendRef
 [parentRef]: /reference/spec/#gateway.networking.k8s.io/v1beta1.ParentRef
-
+[timeouts]: /reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteTimeouts
+[appProtocol]: https://kubernetes.io/docs/concepts/services-networking/service/#application-protocol
diff --git a/site-src/guides/backend-protocol.md b/site-src/guides/backend-protocol.md
@@ -0,0 +1,34 @@
+# Backend Protocol
+
+??? example "Experimental Channel in v1.0.0+"
+
+    This concept is part of the Experimental Channel in `v1.0.0+`.
+
+Not all implementations of Gateway API support automatic protocol selection. In some cases protocols are disabled without an explicit opt-in. 
+
+When a Route's backend references a Kubernetes Service, application developers can specify the protocol using `ServicePort` [`appProtocol`][appProtocol] field.
+
+For example the following `store` Kubernetes Service is indicating the port `8080` supports HTTP/2 Prior Knowledge.
+
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: store
+spec:
+  selector:
+    app: store
+  ports:
+  - protocol: TCP
+    appProtocol: kubernetes.io/h2c
+    port: 8080
+    targetPort: 8080
+```
+
+Currently, Gateway API has conformance testing for:
+
+- `kubernetes.io/h2c` - HTTP/2 Prior Knowledge
+- `kubernetes.io/ws` - WebSocket over HTTP
+
+[appProtocol]: https://kubernetes.io/docs/concepts/services-networking/service/#application-protocol
diff --git a/site-src/guides/tls.md b/site-src/guides/tls.md
@@ -1,12 +1,12 @@
 # TLS Configuration
 
-Gateway API allow for a variety of ways to configure TLS. This document lays
+Gateway API allows for a variety of ways to configure TLS. This document lays
 out various TLS settings and gives general guidelines on how to use them
 effectively.
 
 !!! info "Experimental Channel"
 
-    The `TLSRoute` resource described below is currently only included in the
+    The `TLSRoute` and `BackendTLSPolicy` resources described below are currently only included in the
     "Experimental" channel of Gateway API. For more information on release
     channels, refer to the [related documentation](https://gateway-api.sigs.k8s.io/concepts/versioning).
 
@@ -23,32 +23,36 @@ For Gateways, there are two connections involved:
 With Gateway API, TLS configuration of downstream and
 upstream connections is managed independently.
 
-Depending on the Listener Protocol, different TLS modes and Route types are supported.
+For downstream connections, depending on the Listener Protocol, different TLS modes and Route types are supported.
 
-Listener Protocol | TLS Mode | Route Type Supported
---- | --- | ---
-TLS | Passthrough | TLSRoute
-TLS | Terminate | TCPRoute
-HTTPS | Terminate | HTTPRoute
+| Listener Protocol | TLS Mode    | Route Type Supported |
+|-------------------|-------------|---------------------|
+| TLS               | Passthrough | TLSRoute            |
+| TLS               | Terminate   | TCPRoute            |
+| HTTPS             | Terminate   | HTTPRoute           |
 
 Please note that in case of `Passthrough` TLS mode, no TLS settings take
-effect as the TLS session from the client is NOT terminated at the Gateway.
-The rest of the document assumes that TLS is being terminated at the Gateway,
-which is the default setting.
+effect as the TLS session from the client is NOT terminated at the Gateway, but rather
+passes through the Gateway, encrypted.
+
+For upstream connections, `BackendTLSPolicy` is used, and neither listener protocol nor TLS mode apply to the
+upstream TLS configuration. For `HTTPRoute`, the use of both `Terminate` TLS mode and `BackendTLSPolicy` is supported.
+Using these together provides what is commonly known as a connection that is terminated and then re-encrypted at
+the Gateway.
 
 ## Downstream TLS
 
 Downstream TLS settings are configured using listeners at the Gateway level.
 
 ### Listeners and TLS
 
-Listeners expose the TLS setting on a per domain or sub-domain basis.
+Listeners expose the TLS setting on a per domain or subdomain basis.
 TLS settings of a listener are applied to all domains that satisfy the
 `hostname` criteria.
 
 In the following example, the Gateway serves the TLS certificate
 defined in the `default-cert` Secret resource for all requests.
-Although, the example refers to HTTPS protocol, one can also use the same
+Although the example refers to HTTPS protocol, one can also use the same
 feature for TLS-only protocol along with TLSRoutes.
 
 ```yaml
@@ -98,6 +102,55 @@ would be invalid.
 {% include 'standard/tls-cert-cross-namespace.yaml' %}
 ```
 
+## Upstream TLS
+
+Upstream TLS settings are configured using the experimental `BackendTLSPolicy`
+attached to a `Service` via a target reference.
+
+This resource can be used to describe the SNI the Gateway should use to connect to the
+backend and how the certificate served by the backend Pod(s) should be verified.
+
+### TargetRefs and TLS
+
+BackendTLSPolicy contains specification for the `TargetRef` and `TLS`.  TargetRef is required and
+identifies the `Service` for which your HTTPRoute requires TLS. The `TLS` configuration contains a
+required `Hostname`, and either `CACertRefs` or `WellKnownCACerts`.
+
+Hostname refers to the SNI the Gateway should use to connect to the backend, and
+must match the certificate served by the backend pod.
+
+CACertRefs refer to one or more PEM-encoded TLS certificates. If there are no specific certificates
+to use, then you must set WellKnownCACerts to "System" to tell the Gateway to use a set of trusted
+CA Certificates. There may be some variation in which system certificates are used by each implementation.
+Refer to documentation from your implementation of choice for more information.
+
+!!! info "Restrictions"
+
+    - Cross-namespace certificate references are not allowed.
+    - Wildcard hostnames are not allowed.
+
+### Examples
+
+#### Using System Certificates
+
+In this example, the `BackendTLSPolicy` is configured to use system certificates to connect with a
+TLS-encrypted upstream connection where Pods backing the `dev` Service are expected to serve a valid
+certificate for `dev.example.com`.
+
+```yaml
+{% include 'experimental/v1alpha2/backendtlspolicy-system-certs.yaml' %}
+```
+
+#### Using Explicit CA Certificates
+
+In this example, the `BackendTLSPolicy` is configured to use certificates defined in the configuration
+map `auth-cert` to connect with a TLS-encrypted upstream connection where Pods backing the `auth` Service
+are expected to serve a valid certificate for `auth.example.com`.
+
+```yaml
+{% include 'experimental/v1alpha2/backendtlspolicy-ca-certs.yaml' %}
+```
+
 ## Extensions
 
 Gateway TLS configurations provides an `options` map to add additional TLS
