RouteTLSSDSFilter reference (Kubernetes)

RouteTLSSDSFilter is a Kubernetes-only custom resource that lets an HTTPRoute backend override TLS certificate selection with SDS.

Use it when a specific backend service should present a different certificate than the listener or gateway default SDS certificate.

Configuration model

A RouteTLSSDSFilter has the following shape:

apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteTLSSDSFilter
metadata.name: filter name
metadata.namespace: filter namespace
spec.sds: SDS configuration
- clusterName: optional, can be inherited from listener/gateway SDS defaults
- certResource: required

Field reference

`spec.sds.certResource`

Defines the SDS certificate resource name to request for this backend.

Required: yes
Type: string

`spec.sds.clusterName`

Defines the SDS cluster used to fetch certResource.

Required: no (if inherited)
Type: string
Inheritance: when omitted, Kubernetes can inherit it from listener/gateway SDS defaults if exactly one effective cluster can be resolved.

How to attach the filter

Attach RouteTLSSDSFilter on HTTPRoute.rules[].backendRefs[].filters[] using ExtensionRef:

Validation behavior

spec.sds.certResource must be set.
If spec.sds.clusterName is omitted, inheritance must resolve to exactly one SDS cluster.
If inheritance is missing or ambiguous, the route/filter is rejected.
Rule-level placement (HTTPRoute.rules[].filters[]) is invalid for this filter type.

Example: explicit clusterName and certResource

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: api-route-override
  namespace: default
spec:
  parentRefs:
  - name: sds-gateway
    sectionName: https
  hostnames:
  - b.example.test
  rules:
  - backendRefs:
    - name: svc-b
      port: 5678
      filters:
      - type: ExtensionRef
        extensionRef:
          group: consul.hashicorp.com
          kind: RouteTLSSDSFilter
          name: route-sds-override-http
---
apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteTLSSDSFilter
metadata:
  name: route-sds-override-http
  namespace: default
spec:
  sds:
    clusterName: sds-cluster-2
    certResource: foo.example.com

Example: inherited clusterName

In this example, the filter sets only certResource. The SDS clusterName is inherited from gateway/listener defaults.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: sds-gateway
  namespace: default
  annotations:
    api-gateway.consul.hashicorp.com/tls_sds_cluster_name: sds-cluster
    api-gateway.consul.hashicorp.com/tls_sds_cert_resource: wildcard.ingress.consul
spec:
  gatewayClassName: consul
  listeners:
  - name: https
    protocol: HTTPS
    port: 8443
    hostname: a.example.test
    tls:
      mode: Terminate
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: api-route-inherit
  namespace: default
spec:
  parentRefs:
  - name: sds-gateway
    sectionName: https
  hostnames:
  - c.example.test
  rules:
  - backendRefs:
    - name: svc-c
      port: 5678
      filters:
      - type: ExtensionRef
        extensionRef:
          group: consul.hashicorp.com
          kind: RouteTLSSDSFilter
          name: route-sds-inherit
---
apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteTLSSDSFilter
metadata:
  name: route-sds-inherit
  namespace: default
spec:
  sds:
    certResource: c.example.test