Manage control plane permissions on Kubernetes

Uses: Kong Mesh

Restrict permissions to selected namespaces

You can define a list of namespaces that the Kong Mesh control plane can access. When this list is set, Kong Mesh will only have permissions in those selected namespaces and in its own system namespace. It won’t be able to access or manage resources in any other namespace.

To restrict Kong Mesh to a specific set of namespaces, set the kuma.namespaceAllowList option during installation:

kumactl install control-plane \
  --set "kuma.namespaceAllowList={first-namespace,second-namespace}" \
  | kubectl apply -f -

Copied!

# Before installing Kong Mesh with Helm, configure your local Helm repository:
# https://developer.konghq.com/mesh/2.13/production/cp-deployment/kubernetes/#helm
helm install \
  --create-namespace \
  --namespace kong-mesh-system \
  --set "kuma.namespaceAllowList={first-namespace,second-namespace}" \
  kong-mesh kong-mesh/kong-mesh

Copied!

This will create a RoleBinding in each listed namespace, binding the kong-mesh-control-plane-workloads ClusterRole to that namespace. It will also configure Kong Mesh’s mutating and validating webhooks to only work within the specified namespaces.

Manually manage RBAC resources

If your environment restricts creating cluster-scoped resources (ClusterRole or ClusterRoleBinding), or if you prefer to manage permissions yourself, you can disable automatic resource creation during installation.

Before installing Kong Mesh, you must manually create the following resources:

ClusterRole and ClusterRoleBinding used by the control plane
Role and RoleBinding within the control plane namespace
RoleBindings in selected namespaces when using namespaceAllowList (optional)

You can find the complete set of required manifests here:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kong-mesh-control-plane
rules:
- apiGroups:
  - ''
  resources:
  - namespaces
  - pods
  - nodes
  - services
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - discovery.k8s.io
  resources:
  - endpointslices
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - apps
  resources:
  - deployments
  - replicasets
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - batch
  resources:
  - jobs
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - gateway.networking.k8s.io
  resources:
  - gateways
  - referencegrants
  - httproutes
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - gateway.networking.k8s.io
  resources:
  - gatewayclasses
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - gateway.networking.k8s.io
  resources:
  - gatewayclasses/status
  verbs:
  - get
  - patch
  - update
- apiGroups:
  - kuma.io
  resources:
  - dataplanes
  - dataplaneinsights
  - meshes
  - zones
  - zoneinsights
  - zoneingresses
  - zoneingressinsights
  - zoneegresses
  - zoneegressinsights
  - meshinsights
  - serviceinsights
  - proxytemplates
  - ratelimits
  - trafficpermissions
  - trafficroutes
  - timeouts
  - retries
  - circuitbreakers
  - virtualoutbounds
  - containerpatches
  - externalservices
  - faultinjections
  - healthchecks
  - trafficlogs
  - traffictraces
  - meshgateways
  - meshgatewayroutes
  - meshgatewayinstances
  - meshgatewayconfigs
  - meshaccesslogs
  - meshcircuitbreakers
  - meshfaultinjections
  - meshglobalratelimits
  - meshhealthchecks
  - meshhttproutes
  - meshloadbalancingstrategies
  - meshmetrics
  - meshopas
  - meshpassthroughs
  - meshproxypatches
  - meshratelimits
  - meshretries
  - meshtcproutes
  - meshtimeouts
  - meshtlses
  - meshtraces
  - meshtrafficpermissions
  - hostnamegenerators
  - meshexternalservices
  - meshidentities
  - meshmultizoneservices
  - meshservices
  - meshtrusts
  - workloads
  verbs:
  - get
  - list
  - watch
  - create
  - update
  - patch
  - delete
- apiGroups:
  - kuma.io
  resources:
  - meshgatewayinstances/status
  - meshgatewayinstances/finalizers
  - meshes/finalizers
  - dataplanes/finalizers
  verbs:
  - get
  - patch
  - update
- apiGroups:
  - authentication.k8s.io
  resources:
  - tokenreviews
  verbs:
  - create

Copied!

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kong-mesh-control-plane-workloads
rules:
- apiGroups:
  - ''
  resources:
  - events
  verbs:
  - create
  - patch
- apiGroups:
  - apps
  resources:
  - deployments
  - replicasets
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - batch
  resources:
  - jobs
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - ''
  resources:
  - services
  verbs:
  - get
  - delete
  - list
  - watch
  - create
  - update
  - patch
- apiGroups:
  - ''
  resources:
  - pods/finalizers
  verbs:
  - get
  - patch
  - update
- apiGroups:
  - gateway.networking.k8s.io
  resources:
  - gateways
  - referencegrants
  - httproutes
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - gateway.networking.k8s.io
  resources:
  - gateways/status
  - httproutes/status
  verbs:
  - get
  - patch
  - update

Copied!

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kong-mesh-control-plane-kmesh
rules:
- apiGroups:
  - kuma.io
  resources:
  - opapolicies
  - accessroles
  - accessrolebindings
  - accessaudits
  verbs:
  - get
  - list
  - watch
  - create
  - update
  - patch
  - delete

Copied!

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kong-mesh-control-plane
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kong-mesh-control-plane
subjects:
- kind: ServiceAccount
  name: kong-mesh-control-plane
  namespace: kong-mesh-system

Copied!

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kong-mesh-control-plane-workloads
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kong-mesh-control-plane-workloads
subjects:
- kind: ServiceAccount
  name: kong-mesh-control-plane
  namespace: kong-mesh-system

Copied!

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kong-mesh-control-plane-kmesh
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: kong-mesh-control-plane-kmesh
subjects:
- kind: ServiceAccount
  name: kong-mesh-control-plane
  namespace: kong-mesh-system

Copied!

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: kong-mesh-control-plane
  namespace: kong-mesh-system
rules:
- apiGroups:
  - coordination.k8s.io
  resources:
  - leases
  verbs:
  - get
  - list
  - watch
  - create
  - update
  - patch
  - delete
- apiGroups:
  - ''
  resources:
  - configmaps
  - secrets
  verbs:
  - get
  - delete
  - list
  - watch
  - create
  - update
  - patch
- apiGroups:
  - ''
  resources:
  - events
  verbs:
  - create
  - patch
- apiGroups:
  - ''
  resources:
  - pods
  verbs:
  - delete
- apiGroups:
  - gateway.networking.k8s.io
  resources:
  - gateways
  - referencegrants
  - httproutes
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - gateway.networking.k8s.io
  resources:
  - gateways/status
  - httproutes/status
  verbs:
  - get
  - patch
  - update

Copied!

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: kong-mesh-control-plane-kmesh
  namespace: kong-mesh-system
rules:
- apiGroups:
  - cert-manager.io
  resources:
  - certificaterequests
  verbs:
  - create
  - get
  - watch
  - update
  - delete
  - patch

Copied!

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: kong-mesh-control-plane
  namespace: kong-mesh-system
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: kong-mesh-control-plane
subjects:
- kind: ServiceAccount
  name: kong-mesh-control-plane
  namespace: kong-mesh-system

Copied!

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: kong-mesh-control-plane-kmesh
  namespace: kong-mesh-system
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: kong-mesh-control-plane-kmesh
subjects:
- kind: ServiceAccount
  name: kong-mesh-control-plane
  namespace: kong-mesh-system

Copied!

These manifests include the kong-mesh-control-plane-workloads binding, granting the control plane write access to resources across all namespaces.

All required resources must be created before installing Kong Mesh.

Disable automatic resource creation

To skip creation of all resources, use kuma.skipRBAC=true during installation:

kumactl install control-plane \
  --set "kuma.skipRBAC=true" \
  | kubectl apply -f -

Copied!

# Before installing Kong Mesh with Helm, configure your local Helm repository:
# https://developer.konghq.com/mesh/2.13/production/cp-deployment/kubernetes/#helm
helm install \
  --create-namespace \
  --namespace kong-mesh-system \
  --set "kuma.skipRBAC=true" \
  kong-mesh kong-mesh/kong-mesh

Copied!

To skip only cluster-scoped resources kuma.controlPlane.skipClusterRoleCreation=true:

kumactl install control-plane \
  --set "kuma.controlPlane.skipClusterRoleCreation=true" \
  | kubectl apply -f -

Copied!

# Before installing Kong Mesh with Helm, configure your local Helm repository:
# https://developer.konghq.com/mesh/2.13/production/cp-deployment/kubernetes/#helm
helm install \
  --create-namespace \
  --namespace kong-mesh-system \
  --set "kuma.controlPlane.skipClusterRoleCreation=true" \
  kong-mesh kong-mesh/kong-mesh

Copied!

If you choose to manage Kong Mesh’s RBAC resources yourself, make sure to keep them in sync during upgrades. When a new version of Kong Mesh is released, roles and role bindings may change, and it’s your responsibility to update them accordingly.

Manage control plane permissions on Kubernetes

Restrict permissions to selected namespaces

Manually manage RBAC resources

Disable automatic resource creation

Help us make these docs great!

Still need help