Implement per-hostname client certificate validation (mTLS)

[ahmed25dev]

Question: Is there a way to enable mTLS on only one specific service in a single Gateway without impacting others?

Current config:
listeners:

• ..

tls:
frontend:
default:
validation:
caCertificateRefs:
- kind: Secret
group: ""
name: client-validation-ca-secret
namespace: nginx-gateway
mode: AllowInsecureFallback
perPort:
- port: 8443
tls:
validation:
caCertificateRefs:
- kind: Secret
group: ""
name: client-validation-ca-secret
namespace: nginx-gateway
mode: AllowValidOnly

Problem: When we enable mTLS on the Gateway, ALL services get prompted for client certs, not just the one that needs it (even with different ports).

Constraint: Single Gateway (avoid multiple LoadBalancers)

any solution ?

Thanks!

[salonichf5]

Just to confirm, are you looking to enable mTLS for incoming connections into the Gateway (frontend), or for outgoing connections from the Gateway to a specific backend service? Based on your config, it looks like frontend mTLS.

A few things to note:
Any TLS settings applied at the Gateway level will affect all routes attached to that Gateway so what you're experiencing is expected behavior. If you want mTLS scoped to a specific service, the approach depends on the direction:

Frontend mTLS (client → Gateway): This is inherently Gateway-wide. There's no native way to require client certificates only for certain routes on a single Gateway listener.
Backend mTLS (Gateway → service): You can use a BackendTLSPolicy targeted at a specific Service, which gives you per-service TLS control without touching other routes.

Here are two guides that may help depending on your use case:

Frontend mTLS — Gateway-level client validation
Backend TLS / mTLS — includes an example of using BackendTLSPolicy to secure a specific backend service

If frontend mTLS scoped to a single route is the actual requirement, that's worth filing as a feature request it's not something the current Gateway API spec supports at the route level today.

[ahmed25dev]

Thank you for the clarification.

Just to confirm, my goal is to enable client mTLS for only a single service/route, not for all applications behind the Gateway.

In that case, should I be looking at a TLSRoute with TLS passthrough instead of frontend TLS client certificate validation?

[salonichf5]

Your instinct is right — TLS Passthrough + TLSRoute is the better fit here. I tested it and it works exactly as expected.

Recommendation: Let each backend own its own TLS configuration and use TLS Passthrough on the Gateway. The Gateway stays transparent and just forwards the request as is with no cert management at the gateway level at all. Services that need mTLS configure it on their own.

Setup tested:

Gateway with 2 TLS Passthrough listeners on separate ports
2 TLSRoutes, one per listener
catalog backend: standard TLS, no client cert required
payments backend: TLS + ssl_verify_client on, rejects requests without a valid client cert

Example File:

Gateway:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: nginx-gateway
  namespace: default
spec:
  gatewayClassName: nginx
  listeners:
    - name: catalog
      hostname: catalog.personapp.com
      port: 443
      protocol: TLS
      tls:
        mode: Passthrough
      allowedRoutes:
        kinds:
          - group: gateway.networking.k8s.io
            kind: TLSRoute
        namespaces:
          from: All
    - name: payments
      hostname: payments.personapp.com
      port: 8443
      protocol: TLS
      tls:
        mode: Passthrough
      allowedRoutes:
        kinds:
          - group: gateway.networking.k8s.io
            kind: TLSRoute
        namespaces:
          from: All

Routes

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: catalog-route
  namespace: default
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: nginx-gateway
      sectionName: catalog
  hostnames:
    - catalog.personapp.com
  rules:
    - backendRefs:
        - name: catalog
          port: 8443
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: payments-route
  namespace: default
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: nginx-gateway
      sectionName: payments
  hostnames:
    - payments.personapp.com
  rules:
    - backendRefs:
        - name: payments
          port: 8443

Backends

# ── CATALOG (standard TLS, no client cert) ────────────────────────────────────
apiVersion: v1
kind: ConfigMap
metadata:
  name: catalog-config
  namespace: default
data:
  app.conf: |-
    server {
        listen 8443 ssl;
        listen [::]:8443 ssl;

        server_name catalog.personapp.com;

        ssl_certificate     /etc/nginx/ssl/tls.crt;
        ssl_certificate_key /etc/nginx/ssl/tls.key;

        default_type text/plain;

        location / {
            return 200 "hello from catalog pod $hostname\n";
        }
    }
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: catalog-nginx-config
  namespace: default
data:
  nginx.conf: |
    worker_processes auto;
    pid /tmp/nginx.pid;
    events {
        worker_connections 1024;
    }
    http {
        error_log /var/log/nginx/error.log debug;
        include /etc/nginx/conf.d/*.conf;
    }
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: catalog
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: catalog
  template:
    metadata:
      labels:
        app: catalog
    spec:
      containers:
        - name: catalog
          image: nginxinc/nginx-unprivileged:latest
          ports:
            - containerPort: 8443
          volumeMounts:
            - name: tls-secret
              mountPath: /etc/nginx/ssl
              readOnly: true
            - name: config-volume
              mountPath: /etc/nginx/conf.d
            - name: nginx-config
              mountPath: /etc/nginx/nginx.conf
              subPath: nginx.conf
      volumes:
        - name: tls-secret
          secret:
            secretName: catalog-tls-secret
        - name: config-volume
          configMap:
            name: catalog-config
        - name: nginx-config
          configMap:
            name: catalog-nginx-config
---
apiVersion: v1
kind: Service
metadata:
  name: catalog
  namespace: default
spec:
  selector:
    app: catalog
  ports:
    - port: 8443
      targetPort: 8443
      protocol: TCP
      name: https
---
# ── PAYMENTS (mTLS — ssl_verify_client on) ────────────────────────────────────
apiVersion: v1
kind: ConfigMap
metadata:
  name: payments-config
  namespace: default
data:
  app.conf: |-
    server {
        listen 8443 ssl;
        listen [::]:8443 ssl;

        server_name payments.personapp.com;

        ssl_certificate     /etc/nginx/ssl/server/tls.crt;
        ssl_certificate_key /etc/nginx/ssl/server/tls.key;

        ssl_client_certificate /etc/nginx/ssl/client-ca/ca.crt;
        ssl_verify_client      on;
        ssl_verify_depth       2;

        default_type text/plain;

        location / {
            return 200 "hello from payments pod $hostname\n";
        }
    }
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: payments-nginx-config
  namespace: default
data:
  nginx.conf: |
    worker_processes auto;
    pid /tmp/nginx.pid;
    events {
        worker_connections 1024;
    }
    http {
        log_format mtls '$remote_addr ssl_client_verify=$ssl_client_verify client=$ssl_client_s_dn';
        error_log /var/log/nginx/error.log debug;
        include /etc/nginx/conf.d/*.conf;
    }
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payments
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: payments
  template:
    metadata:
      labels:
        app: payments
    spec:
      containers:
        - name: payments
          image: nginxinc/nginx-unprivileged:latest
          ports:
            - containerPort: 8443
          volumeMounts:
            - name: server-cert
              mountPath: /etc/nginx/ssl/server
              readOnly: true
            - name: client-ca
              mountPath: /etc/nginx/ssl/client-ca
              readOnly: true
            - name: config-volume
              mountPath: /etc/nginx/conf.d
            - name: nginx-config
              mountPath: /etc/nginx/nginx.conf
              subPath: nginx.conf
      volumes:
        - name: server-cert
          secret:
            secretName: payments-tls-secret
        - name: client-ca
          secret:
            secretName: client-ca-secret
        - name: config-volume
          configMap:
            name: payments-config
        - name: nginx-config
          configMap:
            name: payments-nginx-config
---
apiVersion: v1
kind: Service
metadata:
  name: payments
  namespace: default
spec:
  selector:
    app: payments
  ports:
    - port: 8443
      targetPort: 8443
      protocol: TCP
      name: https

Testing:

# catalog (local 9443 → remote 443)
curl --resolve catalog.personapp.com:9443:127.0.0.1 https://catalog.personapp.com:9443 -k

# payments (local 8443 → remote 8443)
curl --resolve payments.personapp.com:8443:127.0.0.1 https://payments.personapp.com:8443 -k

Handling connection for 9443
hello from catalog pod catalog-7646549555-5n49f
Handling connection for 8443
<html>
<head><title>400 No required SSL certificate was sent</title></head>
<body>
<center><h1>400 Bad Request</h1></center>
<center>No required SSL certificate was sent</center>
<hr><center>nginx/1.31.1</center>
</body>
</html>

---

curl --resolve payments.personapp.com:8443:127.0.0.1 https://payments.personapp.com:8443 \
  --cert <(kubectl get secret test-client-secret -o jsonpath='{.data.tls\.crt}' | base64 -d) \
  --key  <(kubectl get secret test-client-secret -o jsonpath='{.data.tls\.key}' | base64 -d) \
  -k

Handling connection for 8443
hello from payments pod payments-6647b949f5-mch2x