envoyproxy · zirain · Nov 8, 2025 · Nov 3, 2025 · Nov 3, 2025 · Nov 7, 2025
@@ -3,9 +3,9 @@ title = "BackendTLSPolicy"
 +++
 
 
-    The `BackendTLSPolicy` resource is Alpha and has been part of
-    the Experimental Channel since `v1.0.0`. For more information on release
-    channels, refer to our [versioning guide](https://gateway-api.sigs.k8s.io/concepts/versioning).
+    The `BackendTLSPolicy` resource is GA and has been part of the Standard
+    Channel since `v1.4.0`. For more information on release channels, refer
+    to our [versioning guide](https://gateway-api.sigs.k8s.io/concepts/versioning).
 
 [BackendTLSPolicy][backendtlspolicy] is a Gateway API type for specifying the TLS configuration
 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.
 
 While there are other API objects provided for TLS to be configured for **passthrough** and **edge** termination,
 this API object allows users to specifically configure **backend** TLS termination.  For more information on TLS
-configuration in Gateway API, see [TLS Configuration](https://gateway-api.sigs.k8s.io/guides/tls/).
+configuration in Gateway API, see [TLS Configuration](https://gateway-api.sigs.k8s.io/guides/tls).
 
 ![Image showing three TLS Termination Types](https://gateway-api.sigs.k8s.io/images/tls-termination-types.png)
 
-BackendTLSPolicy is a Direct [PolicyAttachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/) without defaults or overrides,
+BackendTLSPolicy is a Direct [PolicyAttachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment) without defaults or overrides,
 applied to a Service that accesses a backend, where the BackendTLSPolicy resides in the same namespace as the
 Service to which it is applied. The BackendTLSPolicy and the Service must reside in the same namespace in order
 to prevent the complications involved with sharing trust across namespace boundaries.
@@ -37,19 +37,21 @@ The specification of a [BackendTLSPolicy][backendtlspolicy] consists of:
 - [Validation][validation] - Defines the configuration for TLS, including hostname, CACertificateRefs, and
 WellKnownCACertificates.
 - [Hostname][hostname] - Defines the Server Name Indication (SNI) that the Gateway uses to connect to the backend.
+- [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.  
 - [CACertificateRefs][caCertificateRefs] - Defines one or more references to objects that contain PEM-encoded TLS certificates,
 which are used to establish a TLS handshake between the Gateway and backend Pod.  Either CACertificateRefs or
 WellKnownCACertificates may be specified, but not both.
 - [WellKnownCACertificates][wellKnownCACertificates] - Specifies whether system CA certificates may be used in the TLS
 handshake between the Gateway and backend Pod.  Either CACertificateRefs or WellKnownCACertificates may be specified, but not both.
+- [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.  
 
 The following chart outlines the object definitions and relationship:
 ```mermaid
 flowchart LR
     backendTLSPolicy[["<b>backendTLSPolicy</b> <hr><align=left>BackendTLSPolicySpec: spec<br>PolicyStatus: status</align>"]]
     spec[["<b>spec</b><hr>PolicyTargetReferenceWithSectionName: targetRefs <br> BackendTLSPolicyValidation: tls"]]
     status[["<b>status</b><hr>[ ]PolicyAncestorStatus: ancestors"]]
-    validation[["<b>tls</b><hr>LocalObjectReference: caCertificateRefs<br>wellKnownCACertificatesType: wellKnownCACertificates/<br>PreciseHostname: hostname"]]
+    validation[["<b>tls</b><hr>LocalObjectReference: caCertificateRefs<br>wellKnownCACertificatesType: wellKnownCACertificates<br>PreciseHostname: hostname<br>[]SubjectAltName: subjectAltNames"]]  
     ancestorStatus[["<b>ancestors</b><hr>AncestorRef: parentReference<br>GatewayController: controllerName<br>[]Condition: conditions"]]
     targetRefs[[<b>targetRefs</b><hr>]]
     service["<b>service</>"]
@@ -68,15 +70,10 @@ The following illustrates a BackendTLSPolicy that configures TLS for a Service s
 flowchart LR
     client(["client"])
     gateway["Gateway"]
-    style gateway fill:#02f,color:#fff
     httproute["HTTP<BR>Route"]
-    style httproute fill:#02f,color:#fff
     service["Service"]
-    style service fill:#02f,color:#fff
     pod1["Pod"]
-    style pod1 fill:#02f,color:#fff
     pod2["Pod"]
-    style pod2 fill:#02f,color:#fff
     client -.->|HTTP <br> request| gateway
     gateway --> httproute
     httproute -.->|BackendTLSPolicy|service
@@ -110,6 +107,31 @@ Also note:
 
     - Wildcard hostnames are not allowed.
 
+#### Subject Alternative Names
+
+
+    This field was added to BackendTLSPolicy in `v1.2.0`
+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.  
+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.  
+
+
+    - IP addresses and wildcard hostnames are not allowed. (see the description for Hostname above for more details). 
+    - Hostname: DNS name format
+    - URI: URI format (e.g., SPIFFE ID)
+
+#### TLS Options
+
+
+    This field was added to BackendTLSPolicy in `v1.2.0`
+The options field allows specification of implementation-specific TLS configurations. This can include:  
+
+- Vendor-specific mutual TLS automation configuration  
+- Minimum supported TLS version restrictions
+- Supported cipher suite configurations
+
+Check your implementation documentation for details.  
+
+###
 #### Certificates
 
 The BackendTLSPolicyValidation must contain a certificate reference of some kind, and contains two ways to configure the
@@ -140,7 +162,9 @@ uses `PolicyAncestorStatus` to allow you to know which parentReference set that
 [backendtlspolicy]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#backendtlspolicy
 [validation]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#backendtlspolicyvalidation
 [caCertificateRefs]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#localobjectreference
-[wellKnownCACertificates]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#wellknowncacertificatestype
+[wellKnownCACertificates]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#localobjectreference
 [hostname]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#precisehostname
 [rfc-3986]: https://tools.ietf.org/html/rfc3986
 [targetRefs]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#localpolicytargetreferencewithsectionname
+[subjectAltNames]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#subjectaltname
+[options]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#backendtlspolicyspec
@@ -171,8 +171,6 @@ header "my.filter.com". Note that GRPCRoute uses HTTPRoute filters for features
 with functionality identical to HTTPRoute, such as this.
 
 ```yaml
-#$ Used in:
-#$ - site-src/api-types/grpcroute.md
 apiVersion: gateway.networking.k8s.io/v1
 kind: GRPCRoute
 metadata:
@@ -224,8 +222,6 @@ The following example forwards gRPC requests for the method `User.Login` to serv
 header `magic: foo` to service "my-service2" on port `50051`:
 
 ```yaml
-#$ Used in:
-#$ - site-src/api-types/grpcroute.md
 apiVersion: gateway.networking.k8s.io/v1
 kind: GatewayClass
 metadata:
@@ -289,8 +285,6 @@ The following example uses the `weight` field to forward 90% of gRPC requests to
 Service:
 
 ```yaml
-#$ Used in:
-#$ - site-src/api-types/grpcroute.md
 apiVersion: gateway.networking.k8s.io/v1
 kind: GRPCRoute
 metadata:
@@ -321,7 +315,7 @@ on `weight` and other fields.
     For more information on release channels, refer to our
     [versioning guide](https://gateway-api.sigs.k8s.io/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.
+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.
 
 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.
 
@@ -368,12 +362,12 @@ Multiple GRPCRoutes 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][grpcrouterule].
 
-[grpcroute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#grpcroute
-[grpcrouterule]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#grpcrouterule
-[hostname]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#hostname
+[grpcroute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#grpcroute
+[grpcrouterule]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#grpcrouterule
+[hostname]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#hostname
 [rfc-3986]: https://tools.ietf.org/html/rfc3986
-[matches]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#grpcroutematch
-[filters]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#grpcroutefilter
-[backendRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#grpcroutebackendref
-[parentRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#parentref
-[name]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#sectionname
+[matches]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#grpcroutematch
+[filters]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#grpcroutefilter
+[backendRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#grpcbackendref
+[parentRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#parentreference
+[name]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#sectionname
@@ -181,8 +181,6 @@ strategies, rate-limiting, and traffic shaping.
 The following example adds header "my-header: foo" to HTTP requests with Host
 header "my.filter.com".
 ```yaml
-#$ Used in:
-#$ - site-src/api-types/httproute.md
 apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
@@ -233,18 +231,16 @@ are specified that would result in a response being sent, a 404 error code
 is returned.
 
 The following example forwards HTTP requests for path prefix `/bar` to service
-"my-service1" on port `8080`, and HTTP requests fulfilling _all_ four of the
+"my-service1" on port `8080`, and HTTP requests fulfilling _all_ four of the 
 following criteria
 
-- header `magic: foo`
+- header `magic: foo` 
 - query param `great: example`
 - path prefix `/some/thing`
 - method `GET`
 
 to service "my-service2" on port `8080`:
 ```yaml
-#$ Used in:
-#$ - site-src/api-types/httproute.md
 apiVersion: gateway.networking.k8s.io/v1
 kind: GatewayClass
 metadata:
@@ -307,9 +303,6 @@ The following example uses the `weight` field to forward 90% of HTTP requests to
 `foo.example.com` to the "foo-v1" Service and the other 10% to the "foo-v2"
 Service:
 ```yaml
-#$ Used in:
-#$ - site-src/guides/traffic-splitting.md
-#$ - site-src/api-types/httproute.md
 apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
@@ -350,7 +343,7 @@ There are 2 kinds of timeouts that can be configured in an HTTPRoute Rule:
 
 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](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.
+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.
 
 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`:
 
@@ -385,7 +378,7 @@ Reference the [timeouts][timeouts] API documentation for additional details.
     For more information on release channels, refer to our
     [versioning guide](https://gateway-api.sigs.k8s.io/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.
+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.
 
 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.
 
@@ -471,14 +464,14 @@ 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/reference/1.4/spec#httproute
-[httprouterule]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httprouterule
-[hostname]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#hostname
+[httproute]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httproute
+[httprouterule]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httprouterule
+[hostname]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#hostname
 [rfc-3986]: https://tools.ietf.org/html/rfc3986
-[matches]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httproutematch
-[filters]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httproutefilter
-[backendRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httpbackendref
-[parentRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#parentref
-[timeouts]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#httproutetimeouts
+[matches]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httproutematch
+[filters]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httproutefilter
+[backendRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httpbackendref
+[parentRef]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#parentreference
+[timeouts]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#httproutetimeouts
 [appProtocol]: https://kubernetes.io/docs/concepts/services-networking/service/#application-protocol
-[sectionName]: https://gateway-api.sigs.k8s.io/reference/1.4/spec#sectionname
+[sectionName]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#sectionname
@@ -90,7 +90,7 @@ While the API is simplistic in nature, it comes with a few notable decisions:
    other. This makes it impossible for them to conflict with each other.
 
 Please see the [API
-Specification](https://gateway-api.sigs.k8s.io/reference/1.4/spec#gateway.networking.k8s.io/v1alpha2.ReferenceGrant)
+Specification](https://gateway-api.sigs.k8s.io/reference/spec#referencegrant)
 for more details on how specific ReferenceGrant fields are interpreted.
 
 ## Implementation Guidelines

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# DOC_DEST_DIR=/path/to/dir YAML_SRC_BASE_URL=... SYNC_FILES="a.md b.md" ./tools/hack/gwapi-doc-download-includes.sh
+
+: "${DOC_DEST_DIR:=site/content/en/latest/api/gateway_api}"
+: "${YAML_SRC_BASE_URL:=https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/main/examples}"
+: "${SYNC_FILES:=gateway.md gatewayclass.md httproute.md grpcroute.md backendtlspolicy.md referencegrant.md}"
+: "${LOG_TARGET:=echo \"[docs]\"}"
+
+GREP=$(command -v grep)
+SED=$(command -v sed)
+# use ggrep/gsed on macOS if available
+if [[ "$(uname)" == "Darwin" ]]; then
+  if command -v ggrep &> /dev/null; then
+    GREP=$(command -v ggrep)
+  fi
+  if command -v gsed &> /dev/null; then
+    SED=$(command -v gsed)
+  fi
+fi
+
+for file in $SYNC_FILES; do
+  echo "processing: $file"
+  src="$DOC_DEST_DIR/$file"
+  if [ ! -f "$src" ]; then
+    echo "  skip: $src not found"
+    continue
+  fi
+
+  # Extract the path inside {% include 'path' %} and download each referenced file
+  includes=$($GREP -oP "{% include '\K[^']+" "$src" || true)
+  for include_path in $includes; do
+    filename=$(basename "$include_path")
+    dest="$DOC_DEST_DIR/$filename"
+    dest_dir=$(dirname "$dest")
+    mkdir -p "$dest_dir"
+    url="$YAML_SRC_BASE_URL/$include_path"
+    echo "downloading $url to $dest"
+    curl -sSL -o "$dest" "$url"
+
+    # Remove lines start with `#$`
+    $SED -i '/^#\$/d' "$dest"
+  done
+done
@@ -16,6 +16,13 @@
 
 SHELL:=/usr/bin/env bash -euo pipefail
 
+GNU_SED := $(shell sed --version >/dev/null 2>&1 && echo "yes" || echo "no")
+ifeq ($(GNU_SED),yes)
+SED=sed -i
+else
+SED=sed -i ''
+endif
+
 # ====================================================================================================
 # ROOT Options:
 # ====================================================================================================