Section Introduction

Welcome to this security lesson. Here we walk through three essential Gateway API security topics in sequence: TLS termination, HTTP-to-HTTPS redirects, and ReferenceGrant configuration for cross-namespace access. Each topic includes concise rationale, configuration examples, and best practices so you can apply them directly to your clusters.

TLS termination: where to terminate TLS (Gateway vs upstream) and how to present a trusted certificate to clients.
Redirects: configuring HTTP-to-HTTPS redirects to ensure traffic is encrypted.
Reference grants: enabling cross-namespace references (for example, a Gateway referencing a Secret in another namespace) securely.

These topics help you deploy the Gateway API according to industry best practices.

Tip: Use a consistent namespace strategy for Gateways, Secrets, and backend workloads. When components must be in different namespaces, use ReferenceGrant to give explicit access rather than granting broad cluster-wide permissions.

1 — TLS termination: Gateway vs upstream

Why it matters

Terminating TLS at the Gateway simplifies certificate management and allows features like routing, redirects, and Layer 7 filters to inspect traffic.
Terminating TLS at the backend (upstream passthrough) preserves end-to-end encryption but reduces the Gateway’s ability to perform HTTP-level processing.

When to choose which

Terminate at Gateway when you must inspect or route based on HTTP fields, offload certificate rotation, or integrate with policies (WAF, rate limiting).
Use passthrough when backend services require end-to-end TLS (client certs) or when you must preserve the original TLS session.

Example: Terminate TLS at the Gateway (HTTPS listener)

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: my-gateway
  namespace: gateway-namespace
spec:
  gatewayClassName: my-gatewayclass
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      # Reference to a TLS Secret in this (or another) namespace
      certificateRefs:
      - name: my-tls-secret

Example: Passthrough TLS (forward TLS to upstream)

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: passthrough-gateway
  namespace: gateway-namespace
spec:
  gatewayClassName: my-gatewayclass
  listeners:
  - name: tls-passthrough
    protocol: TLS
    port: 443
    tls:
      mode: Passthrough

Best practices

Use short-lived certificates and automate rotation with a tool like cert-manager.
Prefer TLS termination at the Gateway for most web-facing services; use passthrough only where required.
Restrict Secret access with least privilege and keep Secrets in the smallest set of namespaces needed.

References

Gateway API TLS docs: https://gateway-api.sigs.k8s.io/
cert-manager: https://cert-manager.io/

2 — Enforce HTTP-to-HTTPS redirects

Why redirect

Ensures all clients use encrypted connections.
Prevents accidental exposure of sensitive data via HTTP.

Use an HTTPRoute with a RequestRedirect filter to redirect HTTP traffic to HTTPS: Example: HTTPRoute that redirects all HTTP requests to HTTPS

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: redirect-http-to-https
  namespace: gateway-namespace
spec:
  parentRefs:
  - name: my-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    filters:
    - type: RequestRedirect
      requestRedirect:
        scheme: https
        port: 443
        statusCode: 301

Notes and options

Use statusCode 301 (permanent) or 302/307 depending on requirements. For SEO and permanent change, 301 is typical.
Combine redirects with HSTS to instruct browsers to always use HTTPS:
- Add a response header like Strict-Transport-Security: max-age=31536000; includeSubDomains; preload via a ResponseHeaderModifier filter if supported by your controller.

Be careful when enabling global 301 redirects during testing. Browsers cache 301 redirects — an incorrect redirect can be cached and difficult to undo during development.

3 — ReferenceGrant: cross-namespace references (Secrets, Services)

Problem

Gateways often need to reference objects that live in a different namespace (for example, a TLS Secret in apps referenced by a Gateway in gateway-namespace).
Kubernetes restricts cross-namespace references by default; you must explicitly grant permission using a ReferenceGrant located in the namespace of the referenced object.

ReferenceGrant structure

A ReferenceGrant must be created in the namespace of the resource being referenced (e.g., where the Secret lives).
It contains from entries (who is allowed to reference) and to entries (which local resources are allowed to be referenced).

Example: Allow a Gateway in gateway-namespace to reference a Secret in apps

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-gateway-to-secret
  namespace: apps
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: my-gateway
    namespace: gateway-namespace
  to:
  - group: ""
    kind: Secret
    name: my-tls-secret

How it works

Place this ReferenceGrant in the apps namespace (the namespace of my-tls-secret).
The Gateway in gateway-namespace can now reference my-tls-secret in apps via certificateRefs in its spec.

Security best practices

Only grant the minimum set of from identities required.
Scope the to entries to the specific Secret names rather than allowing all Secrets.
Audit ReferenceGrant objects regularly.

Quick comparison table

Topic	Goal	Example snippet
TLS termination at Gateway	Offload TLS to Gateway for routing and inspection	See `Gateway` TLS: `mode: Terminate` example above
TLS passthrough	Preserve end-to-end TLS between client and backend	See `Gateway` TLS: `mode: Passthrough` example above
HTTP-to-HTTPS redirect	Ensure encrypted traffic	`HTTPRoute` filter: `RequestRedirect: scheme: https`
Cross-namespace access	Allow Gateway to reference Secrets in another namespace	`ReferenceGrant` placed in Secret’s namespace

Links and references

Gateway API (official): https://gateway-api.sigs.k8s.io/
Kubernetes Secrets: https://kubernetes.io/docs/concepts/configuration/secret/
cert-manager (certificate automation): https://cert-manager.io/

That’s it for this lesson. Use the examples as templates and adapt them to your namespace layout, controller implementation, and security policy.

Introduction & Why Gateway API

Core Gateway API Resources

Advanced Traffic Management

TLS and Cross-Namespace Security

Troubleshooting and Best Practices

Section Introduction

1 — TLS termination: Gateway vs upstream

2 — Enforce HTTP-to-HTTPS redirects

3 — ReferenceGrant: cross-namespace references (Secrets, Services)

Quick comparison table

Links and references

Watch Video

​1 — TLS termination: Gateway vs upstream

​2 — Enforce HTTP-to-HTTPS redirects

​3 — ReferenceGrant: cross-namespace references (Secrets, Services)

​Quick comparison table

​Links and references

Watch Video

1 — TLS termination: Gateway vs upstream

2 — Enforce HTTP-to-HTTPS redirects

3 — ReferenceGrant: cross-namespace references (Secrets, Services)

Quick comparison table

Links and references