Delegate Gateway API Access with Kubernetes RBAC

Use Kubernetes role-based access control (RBAC) to divide Gateway API resource management among infrastructure, gateway, application, and backend teams. The examples in this guide give each team access only to the resources it owns.

The examples use standard Kubernetes and Gateway API resources and apply to both APISIX Ingress Controller and API7 Ingress Controller. They follow the Gateway API role-oriented security model.

Prerequisites

Complete the following prerequisites:

• Set up the Ingress Controller and gateway.
• Install the Gateway API custom resource definitions (CRDs) required by the Route kinds you plan to delegate.
• Create the namespaces used for Gateways, Routes, and backend resources.
• Identify the user or group names supplied by your cluster's identity provider.
• Use a cluster administrator or another account authorized to create and grant the RBAC resources in this guide.

Delegated RBAC Administrators

Kubernetes prevents users from granting permissions they do not hold. A delegated RBAC administrator can create a Role or ClusterRole only if it already holds every included permission or has escalate permission. It can create a binding only if it holds the permissions in the referenced role or has bind permission. See privilege escalation prevention for the complete authorization rules.

Plan the Delegation

Kubernetes RBAC controls who can manage Kubernetes resources. It does not determine whether a Route can attach to a Gateway or reference a resource in another namespace. Gateway owners use listener allowedRoutes to select permitted Route kinds and namespaces. Backend owners use ReferenceGrant to approve cross-namespace references.

The controller service account is separate from these user roles. The Ingress Controller installation grants its service account permission to watch resources and update their status; do not reuse that identity for users.

The examples use the following delegation model:

Team	Group	Manages	Scope
Infrastructure providers	infrastructure-providers	GatewayClass	Cluster
Gateway operators	gateway-operators	Gateway	aic namespace
Application developers	tenant-a-developers	Route resources and read-only access to the shared Gateway	tenant-a namespace and Gateway aic/apisix
Backend owners	backend-owners	ReferenceGrant	backend-ns namespace

Replace the example group, namespace, and Gateway names with values from your identity provider and cluster design. Specifically, update the resourceNames value in the shared-gateway-reader Role if your Gateway is not named apisix.

Do not grant these teams permission to update Gateway API */status resources. The Ingress Controller writes status to report whether resources are accepted, programmed, and able to resolve their references.

This guide delegates only standard Gateway API resources. If application teams also manage APISIX custom resources, such as BackendTrafficPolicy or HTTPRoutePolicy, grant those permissions separately according to the ownership of each custom resource.

Configure RBAC

Create and apply the RBAC resources for each team in your delegation model.

Delegate GatewayClass Management

GatewayClass is cluster-scoped and can select infrastructure managed by a Gateway API implementation. Reserve its management for infrastructure providers.

gatewayclass-rbac.yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: gatewayclass-editor
rules:
- apiGroups:
  - gateway.networking.k8s.io
  resources:
  - gatewayclasses
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: infrastructure-providers-gatewayclass-editor
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: gatewayclass-editor
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: Group
  name: infrastructure-providers

Apply the manifest:

kubectl apply -f gatewayclass-rbac.yaml

Delegate Gateway Management

Grant gateway operators permission to manage Gateways only in the namespace they operate. This example does not let them manage GatewayClasses or Routes.

gateway-rbac.yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: gateway-editor
  namespace: aic
rules:
- apiGroups:
  - gateway.networking.k8s.io
  resources:
  - gateways
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: gateway-operators-gateway-editor
  namespace: aic
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: gateway-editor
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: Group
  name: gateway-operators

Apply the manifest:

kubectl apply -f gateway-rbac.yaml

Delegate Route Management

Grant application developers permission to manage Routes in their application namespace. They cannot create or modify the shared Gateway.

route-rbac.yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: gateway-api-route-editor
  namespace: tenant-a
rules:
- apiGroups:
  - gateway.networking.k8s.io
  resources:
  - grpcroutes
  - httproutes
  - tcproutes
  - tlsroutes
  - udproutes
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: tenant-a-developers-route-editor
  namespace: tenant-a
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: gateway-api-route-editor
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: Group
  name: tenant-a-developers
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: shared-gateway-reader
  namespace: aic
rules:
- apiGroups:
  - gateway.networking.k8s.io
  resourceNames:
  - apisix
  resources:
  - gateways
  verbs:
  - get
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: tenant-a-developers-shared-gateway-reader
  namespace: aic
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: shared-gateway-reader
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: Group
  name: tenant-a-developers

Apply the manifest:

kubectl apply -f route-rbac.yaml

The read-only Role permits the application team to inspect the shared apisix Gateway in the aic namespace. It does not allow listing other Gateways or changing the shared Gateway.

Delegate ReferenceGrant Management

A ReferenceGrant is created in the namespace containing the referenced resource. It can authorize resources in other namespaces to reference selected Services, Secrets, or other targets. Grant its management to trusted owners of the target namespace, not to the team requesting access.

referencegrant-rbac.yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: referencegrant-editor
  namespace: backend-ns
rules:
- apiGroups:
  - gateway.networking.k8s.io
  resources:
  - referencegrants
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: backend-owners-referencegrant-editor
  namespace: backend-ns
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: referencegrant-editor
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: Group
  name: backend-owners

Apply the manifest:

kubectl apply -f referencegrant-rbac.yaml

The backend owner can now approve specific cross-namespace references. The application developer cannot approve its own request unless it also owns the backend namespace.

Verify Delegated Access

The following checks impersonate example users and groups. Running impersonation checks requires permission to impersonate those identities.

Verify the expected permissions:

kubectl auth can-i create gatewayclasses.gateway.networking.k8s.io \
  --all-namespaces \
  --as=infra-user \
  --as-group=infrastructure-providers

kubectl auth can-i create gateways.gateway.networking.k8s.io \
  -n aic \
  --as=gateway-user \
  --as-group=gateway-operators

kubectl auth can-i create httproutes.gateway.networking.k8s.io \
  -n tenant-a \
  --as=app-user \
  --as-group=tenant-a-developers

kubectl auth can-i get gateways.gateway.networking.k8s.io/apisix \
  -n aic \
  --as=app-user \
  --as-group=tenant-a-developers

kubectl auth can-i create referencegrants.gateway.networking.k8s.io \
  -n backend-ns \
  --as=backend-user \
  --as-group=backend-owners

Each command should return yes.

Verify that responsibility boundaries are enforced:

kubectl auth can-i create gateways.gateway.networking.k8s.io \
  -n aic \
  --as=app-user \
  --as-group=tenant-a-developers

kubectl auth can-i create referencegrants.gateway.networking.k8s.io \
  -n backend-ns \
  --as=app-user \
  --as-group=tenant-a-developers

kubectl auth can-i update gateways.gateway.networking.k8s.io \
  --subresource=status \
  -n aic \
  --as=gateway-user \
  --as-group=gateway-operators

Each command should return no.

RBAC verification confirms only whether an identity can perform an API operation. To authorize Route attachment and cross-namespace references, also configure allowedRoutes and ReferenceGrant.