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

# Cross Namespace Security with ReferenceGrant

> Explains Kubernetes Gateway API ReferenceGrant used to securely permit and scope cross-namespace references to Services and Secrets while preserving RBAC and least privilege.

ReferenceGrant is a Gateway API object used to explicitly allow controlled cross-namespace references. In many Gateway API deployments, infrastructure components (for example, a Gateway and its controller) are placed in a dedicated namespace such as `gateway-system`, while application resources (Services, Secrets, Deployments, Routes) live in separate application namespaces. By default, cross-namespace references are denied — ReferenceGrant is the explicit mechanism to permit them securely.

Learn more about the Gateway API: [https://learn.kodekloud.com/user/courses/gateway-api-with-nginx-fabric-gateway](https://learn.kodekloud.com/user/courses/gateway-api-with-nginx-fabric-gateway)

## Why ReferenceGrant exists

A Gateway running in one namespace (the source namespace) may need to reference resources (Services, Secrets) in another namespace (the referent namespace). ReferenceGrant makes that access explicit and auditable, preventing accidental or unrestricted cross-namespace references.

Common scenario:

* Gateway controller and Gateways: `gateway-system`
* Application Service and TLS Secret: `backend`
  To allow Gateways in `gateway-system` to reference `Service` and `Secret` objects in `backend`, create a ReferenceGrant in the `backend` namespace.

## Important rules and behavior

| Rule | Description |
| - | - |
| Location of ReferenceGrant | The ReferenceGrant must be created in the referent namespace (the namespace that contains the target resources). For example: create the grant in `backend` when allowing references to `backend` resources. |
| Incorrect namespace has no effect | Creating a ReferenceGrant in the Gateway’s namespace (e.g. `gateway-system`) has no effect; cross-namespace access remains denied and you will not receive an error pointing to the misplaced ReferenceGrant. |
| RBAC still required | ReferenceGrant only allows the *reference*. Controllers and service accounts still need RBAC permissions to `get`/`list`/`watch` the referenced resources where applicable. |
| Scoping options | You can scope grants by source namespace, source `kind`/`group`, target `kind`s and optionally by target `name` to limit exposure. |

## ReferenceGrant YAML example

Note: Replace the `apiVersion` with the Gateway API version installed on your cluster (for example `gateway.networking.k8s.io/v1beta1` or another supported version).

```yaml theme={null}
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-gateway-system
  namespace: backend
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: Gateway
      namespace: gateway-system
  to:
    - group: ""          # core API group
      kind: Service
    - group: ""          # core API group
      kind: Secret
      name: tls-secret
```

Explanation of the example:

* The ReferenceGrant resource is created in the `backend` namespace (the namespace containing the Service and Secret).
* `from` identifies the allowed source type and source namespace (Gateways in `gateway-system`).
* `to` lists the allowed target kinds — here `Service` (any Service in `backend`) and a specific `Secret` named `tls-secret`.

<Callout icon="lightbulb" color="#1CB2FE">
  Always create the ReferenceGrant in the target resource's namespace (the namespace of the Service/Secret/etc.). Creating it in the gateway namespace will not enable cross-namespace access.
</Callout>

## When to use name restrictions

* Allow every Service in `backend`: omit the `name` field in the `to` entry for `Service`.
* Allow only a specific Secret: include the `name` property (e.g. `tls-secret`) for the `Secret` `to` entry.
* Use name restrictions to minimize blast radius and follow least-privilege principles.

## Quick implementation steps

1. Identify the referent namespace that contains the resources to be referenced (e.g. `backend`).
2. Create a ReferenceGrant in that referent namespace.
3. In the ReferenceGrant `from` section, specify the source `group`, `kind`, and `namespace` (e.g. Gateways in `gateway-system`).
4. In the `to` section, list target `kind`s and optional target `name`s to restrict access.
5. Ensure your Gateway controller’s service account has RBAC permissions to read the referenced resources.

## Troubleshooting tips

* No effect after creating ReferenceGrant: check that the ReferenceGrant is in the same namespace as the target resource.
* Reference denied with no helpful error: confirm the Gateway API version and the `apiVersion` field in your YAML match the installed Gateway API.
* Permission errors when reading resources: verify RBAC rules for the controller’s service account.

## Summary

* Cross-namespace references are denied by default in the Gateway API.
* Use ReferenceGrant, created in the referent namespace, to explicitly permit references from specific sources to specific target kinds or names.
* ReferenceGrant enables references but does not replace RBAC — controllers still need appropriate permissions.

References and further reading:

* Gateway API course (KodeKloud): [https://learn.kodekloud.com/user/courses/gateway-api-with-nginx-fabric-gateway](https://learn.kodekloud.com/user/courses/gateway-api-with-nginx-fabric-gateway)
* Gateway API main docs: [https://gateway-api.sigs.k8s.io/](https://gateway-api.sigs.k8s.io/)

<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/3b82996a-db7b-4442-a945-544d63008f3a" />
</CardGroup>


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