Skip to main content
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

​
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

​
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).
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.
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.

​
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 kinds and optional target names 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:

Watch Video