> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Section Introduction

> Guide covering Gateway API security including TLS termination options, HTTP to HTTPS redirects, and ReferenceGrant setup for secure cross namespace Secret access.

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.

<Callout icon="lightbulb" color="#1CB2FE">
  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.
</Callout>

***

## 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)

```yaml theme={null}
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)

```yaml theme={null}
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/](https://gateway-api.sigs.k8s.io/)
* cert-manager: [https://cert-manager.io/](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

```yaml theme={null}
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.

<Callout icon="warning" color="#FF6B6B">
  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.
</Callout>

***

## 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`

```YAML theme={null}
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/](https://gateway-api.sigs.k8s.io/)
* Kubernetes Secrets: [https://kubernetes.io/docs/concepts/configuration/secret/](https://kubernetes.io/docs/concepts/configuration/secret/)
* cert-manager (certificate automation): [https://cert-manager.io/](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.

<CardGroup>
  <Card title="Watch Video" icon="video" cta="Learn more" href="https://learn.kodekloud.com/user/courses/gateway-api-with-nginx-fabric-gateway/module/59594ad7-a7ed-4494-97a1-25fa5b519588/lesson/8766d39c-c0ee-47b5-ae55-881c68ab93ee" />
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.