You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: site/content/en/latest/api/gateway_api/backendtlspolicy.md
+36-12Lines changed: 36 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,9 +3,9 @@ title = "BackendTLSPolicy"
3
3
+++
4
4
5
5
6
-
The `BackendTLSPolicy` resource is Alpha and has been part of
7
-
the Experimental Channel since `v1.0.0`. For more information on release
8
-
channels, refer to our [versioning guide](https://gateway-api.sigs.k8s.io/concepts/versioning).
6
+
The `BackendTLSPolicy` resource is GA and has been part of the Standard
7
+
Channel since `v1.4.0`. For more information on release channels, refer
8
+
to our [versioning guide](https://gateway-api.sigs.k8s.io/concepts/versioning).
9
9
10
10
[BackendTLSPolicy][backendtlspolicy] is a Gateway API type for specifying the TLS configuration
11
11
of the connection from the Gateway to a backend pod/s via the Service API object.
@@ -18,11 +18,11 @@ how to connect to a backend pod that has its own certificate.
18
18
19
19
While there are other API objects provided for TLS to be configured for **passthrough** and **edge** termination,
20
20
this API object allows users to specifically configure **backend** TLS termination. For more information on TLS
21
-
configuration in Gateway API, see [TLS Configuration](https://gateway-api.sigs.k8s.io/guides/tls/).
21
+
configuration in Gateway API, see [TLS Configuration](https://gateway-api.sigs.k8s.io/guides/tls).
22
22
23
23
24
24
25
-
BackendTLSPolicy is a Direct [PolicyAttachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/) without defaults or overrides,
25
+
BackendTLSPolicy is a Direct [PolicyAttachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment) without defaults or overrides,
26
26
applied to a Service that accesses a backend, where the BackendTLSPolicy resides in the same namespace as the
27
27
Service to which it is applied. The BackendTLSPolicy and the Service must reside in the same namespace in order
28
28
to prevent the complications involved with sharing trust across namespace boundaries.
@@ -37,19 +37,21 @@ The specification of a [BackendTLSPolicy][backendtlspolicy] consists of:
37
37
-[Validation][validation] - Defines the configuration for TLS, including hostname, CACertificateRefs, and
38
38
WellKnownCACertificates.
39
39
-[Hostname][hostname] - Defines the Server Name Indication (SNI) that the Gateway uses to connect to the backend.
40
+
-[SubjectAltNames][subjectAltNames] - Specifies one or more Subject Alternative Names that the backend certificate must match. When specified, the certificate must have at least one matching SAN. This field enables separation between SNI (hostname) and certificate identity validation. A maximum of 5 SANs are allowed.
40
41
-[CACertificateRefs][caCertificateRefs] - Defines one or more references to objects that contain PEM-encoded TLS certificates,
41
42
which are used to establish a TLS handshake between the Gateway and backend Pod. Either CACertificateRefs or
42
43
WellKnownCACertificates may be specified, but not both.
43
44
-[WellKnownCACertificates][wellKnownCACertificates] - Specifies whether system CA certificates may be used in the TLS
44
45
handshake between the Gateway and backend Pod. Either CACertificateRefs or WellKnownCACertificates may be specified, but not both.
46
+
-[Options][options] - A map of key/value pairs enabling extended TLS configuration for implementations that choose to provide support. Check your implementation's documentation for details.
45
47
46
48
The following chart outlines the object definitions and relationship:
@@ -68,15 +70,10 @@ The following illustrates a BackendTLSPolicy that configures TLS for a Service s
68
70
flowchart LR
69
71
client(["client"])
70
72
gateway["Gateway"]
71
-
style gateway fill:#02f,color:#fff
72
73
httproute["HTTP<BR>Route"]
73
-
style httproute fill:#02f,color:#fff
74
74
service["Service"]
75
-
style service fill:#02f,color:#fff
76
75
pod1["Pod"]
77
-
style pod1 fill:#02f,color:#fff
78
76
pod2["Pod"]
79
-
style pod2 fill:#02f,color:#fff
80
77
client -.->|HTTP <br> request| gateway
81
78
gateway --> httproute
82
79
httproute -.->|BackendTLSPolicy|service
@@ -110,6 +107,31 @@ Also note:
110
107
111
108
- Wildcard hostnames are not allowed.
112
109
110
+
#### Subject Alternative Names
111
+
112
+
113
+
This field was added to BackendTLSPolicy in `v1.2.0`
114
+
The subjectAltNames field enables basic mutual TLS configuration between Gateways and backends, as well as the optional use of SPIFFE. When subjectAltNames is specified, the certificate served by the backend must have at least one Subject Alternative Name matching one of the specified values. This is particularly useful for SPIFFE implementations where URI-based SANs may not be valid SNIs.
115
+
Subject Alternative Names may contain one of either a Hostname or URI field, and must contain a Type specifying whether Hostname or URI is chosen.
116
+
117
+
118
+
- IP addresses and wildcard hostnames are not allowed. (see the description for Hostname above for more details).
119
+
- Hostname: DNS name format
120
+
- URI: URI format (e.g., SPIFFE ID)
121
+
122
+
#### TLS Options
123
+
124
+
125
+
This field was added to BackendTLSPolicy in `v1.2.0`
126
+
The options field allows specification of implementation-specific TLS configurations. This can include:
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.
318
+
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/index#section-names)), in the status stanzas of resources related to the route object, to identify internal configuration objects generated by the implementation from GRPCRoute Rule, etc.
325
319
326
320
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.
327
321
@@ -368,12 +362,12 @@ Multiple GRPCRoutes can be attached to a single Gateway resource. Importantly,
368
362
only one Route rule may match each request. For more information on how conflict
369
363
resolution applies to merging, refer to the [API specification][grpcrouterule].
Copy file name to clipboardExpand all lines: site/content/en/latest/api/gateway_api/httproute.md
+13-20Lines changed: 13 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -181,8 +181,6 @@ strategies, rate-limiting, and traffic shaping.
181
181
The following example adds header "my-header: foo" to HTTP requests with Host
182
182
header "my.filter.com".
183
183
```yaml
184
-
#$ Used in:
185
-
#$ - site-src/api-types/httproute.md
186
184
apiVersion: gateway.networking.k8s.io/v1
187
185
kind: HTTPRoute
188
186
metadata:
@@ -233,18 +231,16 @@ are specified that would result in a response being sent, a 404 error code
233
231
is returned.
234
232
235
233
The following example forwards HTTP requests for path prefix `/bar` to service
236
-
"my-service1"on port `8080`, and HTTP requests fulfilling _all_ four of the
234
+
"my-service1"on port `8080`, and HTTP requests fulfilling _all_ four of the
237
235
following criteria
238
236
239
-
- header `magic: foo`
237
+
- header `magic: foo`
240
238
- query param `great: example`
241
239
- path prefix `/some/thing`
242
240
- method `GET`
243
241
244
242
to service "my-service2" on port `8080`:
245
243
```yaml
246
-
#$ Used in:
247
-
#$ - site-src/api-types/httproute.md
248
244
apiVersion: gateway.networking.k8s.io/v1
249
245
kind: GatewayClass
250
246
metadata:
@@ -307,9 +303,6 @@ The following example uses the `weight` field to forward 90% of HTTP requests to
307
303
`foo.example.com`to the "foo-v1" Service and the other 10% to the "foo-v2"
308
304
Service:
309
305
```yaml
310
-
#$ Used in:
311
-
#$ - site-src/guides/traffic-splitting.md
312
-
#$ - site-src/api-types/httproute.md
313
306
apiVersion: gateway.networking.k8s.io/v1
314
307
kind: HTTPRoute
315
308
metadata:
@@ -350,7 +343,7 @@ There are 2 kinds of timeouts that can be configured in an HTTPRoute Rule:
350
343
351
344
Because the `request` timeout encompasses the `backendRequest` timeout, the value of `backendRequest` must not be greater than the value of `request` timeout.
352
345
353
-
Timeouts are optional, and their fields are of type [Duration](https://gateway-api.sigs.k8s.io/geps/gep-2257). A zero-valued timeout ("0s") MUST be interpreted as disabling the timeout. A valid non-zero-valued timeout MUST be >= 1ms.
346
+
Timeouts are optional, and their fields are of type [Duration](https://gateway-api.sigs.k8s.io/geps/gep-2257/index). A zero-valued timeout ("0s") MUST be interpreted as disabling the timeout. A valid non-zero-valued timeout MUST be >= 1ms.
354
347
355
348
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`:
356
349
@@ -385,7 +378,7 @@ Reference the [timeouts][timeouts] API documentation for additional details.
385
378
For more information on release channels, refer to our
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.
381
+
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/index#section-names)), in the status stanzas of resources related to the route object, to identify internal configuration objects generated by the implementation from HTTPRoute Rule, etc.
389
382
390
383
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.
391
384
@@ -471,14 +464,14 @@ only one Route rule may match each request. For more information on how conflict
471
464
resolution applies to merging, refer to the [API specification][httprouterule].
0 commit comments