TLS Termination Configuration

This lesson explains TLS termination with the Gateway API and how to attach certificates to a Gateway. You will learn the two TLS modes supported by the Gateway API, how to obtain and store certificates in Kubernetes, and how to reference those certificates from a Gateway (including cross-namespace access control). We’ll cover:

TLS modes (Terminate vs Passthrough)
Creating and storing TLS materials in a Kubernetes Secret
Referencing Secrets from a Gateway listener
Using ReferenceGrant to allow cross-namespace Secret references

TLS modes in Gateway API

The Gateway API supports two TLS handling modes:

Terminate
The Gateway terminates TLS. It validates the certificate and decrypts the request. Traffic between the Gateway and backend is plain HTTP (or otherwise unencrypted). This is the simplest setup and lets the Gateway inspect request headers, paths, and bodies for routing or modification.
Passthrough
The Gateway forwards the encrypted client connection without terminating TLS. The backend (the application pod or a sidecar/proxy in front of it) must validate and terminate TLS. This preserves end-to-end encryption but requires the backend to have access to the certificate and private key and to perform TLS termination.

A diagram titled "TLS Methods in Gateway API" comparing two approaches—Terminate and Passthrough—showing client, gateway, and app boxes with encrypted/protected or unprotected request flows and short pros/cons. The top row shows TLS terminated at the gateway (traffic decrypted there); the bottom row shows passthrough with end-to-end encryption to the app.

If you need encryption all the way to the pod (passthrough), the backend must hold the private key and certificate to validate and terminate TLS. For automated issuance and rotation of certificates inside your cluster, consider using cert-manager.

If you plan to terminate TLS at the pod (passthrough), use an automated certificate solution like cert-manager to simplify issuance, renewal, and rotation of TLS materials inside your cluster.

Obtaining a signed certificate

A certificate is required in both modes. Typical enterprise setups use an internal Certificate Authority (CA). The high-level flow to obtain a signed certificate:

Generate a private key.
Create a Certificate Signing Request (CSR) using the private key.
Submit the CSR to your CA.
Receive a signed certificate from the CA.

An infographic titled "Generating a Signed TLS Certificate – Steps" showing an engineer using a laptop/OpenSSL to create a CSR and private key, send them to a Certificate Authority, and receive back a signed .crt. The bottom lists the four steps: generate key, generate CSR, send to CA for signing, and receive the signed certificate.

You can use OpenSSL locally to generate a private key and CSR. Example:

openssl genrsa -out tls.key 2048
openssl req -new -key tls.key -subj "/CN=example.com" -out tls.csr
# Submit tls.csr to your CA and receive tls.crt

After you receive tls.crt and have the private key tls.key, store them in Kubernetes as a TLS Secret so your Gateway can access them.

A slide titled "Creating a Certificate Secret in Kubernetes" showing a Kubernetes cluster containing a certificate icon stored as a secret. A dashed arrow with a padlock and checkmark points from the cluster to an orange "GateWay" oval.

Create a TLS Secret

Create a TLS Secret with kubectl (kubectl handles base64 encoding for you). Replace the placeholders (examples shown in a code block so angle brackets are safe):

kubectl create secret tls <secret-name> --cert=<path-to-crt> --key=<path-to-key> -n <namespace>

Or create the Secret manifest yourself. A TLS Secret uses type kubernetes.io/tls and contains tls.crt and tls.key fields (base64-encoded):

apiVersion: v1
kind: Secret
metadata:
  name: cafe-secret
  namespace: certificate
type: kubernetes.io/tls
data:
  tls.crt: <BASE64_ENCODED_CERTIFICATE>
  tls.key: <BASE64_ENCODED_PRIVATE_KEY>

Inspect a created Secret as YAML:

kubectl get secret cafe-secret -n certificate -o yaml

Treat private keys with care. Keep Secrets in restricted namespaces and limit RBAC access. If you must store private keys in the cluster, ensure appropriate RBAC, audit, and rotation policies are in place.

Reference the Secret from a Gateway listener

To terminate TLS at the Gateway, add an HTTPS listener and reference the Secret via certificateRefs. Example Gateway manifest:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: cafe
  namespace: gateway-namespace
spec:
  gatewayClassName: nginx
  listeners:
  - name: http
    port: 80
    protocol: HTTP
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: cafe-secret
        namespace: certificate

In this example the Secret cafe-secret resides in the certificate namespace, and the Gateway itself is in gateway-namespace. When the Secret is in a different namespace, the Gateway must be allowed to reference it.

Allow cross-namespace references with ReferenceGrant

Use a Gateway API ReferenceGrant to permit a resource in one namespace to reference a resource (Secret) in another namespace. Create the ReferenceGrant in the namespace that owns the Secret. Example:

apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
  name: grant-gateway-reference
  namespace: certificate
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: cafe
  to:
  - group: ""
    kind: Secret
    name: cafe-secret

Best practices for ReferenceGrant:

Create the ReferenceGrant in the namespace owning the target resource (the Secret’s namespace).
In to, list the exact resources allowed to be referenced (for Secrets use group: "" and kind: Secret).
In from, specify the referencing resource (Gateway API group, kind, and name). You can widen the scope if needed (for example, use selectors or omit name to allow multiple Gateways).

Quick reference: commands and manifests

Action	Command / Manifest
Create TLS Secret (kubectl)	`kubectl create secret tls <secret-name> --cert=<path-to-crt> --key=<path-to-key> -n <namespace>`
Inspect Secret	`kubectl get secret cafe-secret -n certificate -o yaml`
Gateway TLS listener (example)	See the Gateway manifest YAML block above
ReferenceGrant (example)	See the ReferenceGrant YAML block above

Links and references

Gateway API — Gateway API project documentation
cert-manager — Automate issuance and rotation of TLS certs in Kubernetes
OpenSSL — Generate keys and CSRs locally

That’s it for this lesson. You should now understand the two TLS modes in Gateway API, how to provision a certificate, store it in a Kubernetes Secret, and grant cross-namespace access so a Gateway can use the certificate.

Introduction & Why Gateway API

Core Gateway API Resources

Advanced Traffic Management

TLS and Cross-Namespace Security

Troubleshooting and Best Practices

TLS Termination Configuration

TLS modes in Gateway API

Obtaining a signed certificate

Create a TLS Secret

Reference the Secret from a Gateway listener

Allow cross-namespace references with ReferenceGrant

Quick reference: commands and manifests

Links and references

Watch Video

​TLS modes in Gateway API

​Obtaining a signed certificate

​Create a TLS Secret

​Reference the Secret from a Gateway listener

​Allow cross-namespace references with ReferenceGrant

​Quick reference: commands and manifests

​Links and references

Watch Video

TLS modes in Gateway API

Obtaining a signed certificate

Create a TLS Secret

Reference the Secret from a Gateway listener

Allow cross-namespace references with ReferenceGrant

Quick reference: commands and manifests

Links and references