Kuma Star

Manage control plane permissions on Kubernetes

By default, Kuma deployed on Kubernetes reacts to events and observes all resources at the cluster scope. This approach benefits first-time users who want to explore its functionality and simplifies migration into the mesh. However, in production environments, restricting access to specific resources can enhance security and ensure that Kuma does not impact running applications.

Restrict permissions to selected namespaces

You can define a list of namespaces that Kuma’s control plane can access. When this list is set, Kuma 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.

Set allowed namespaces during installation

To restrict Kuma to a specific set of namespaces, set the following option during installation:

kumactl install control-plane \
  --set "namespaceAllowList={kuma-demo}" \
  | kubectl apply -f -

Replace kuma-demo with a comma-separated list of namespaces you want Kuma to manage.

This will create a RoleBinding in each listed namespace, binding the kuma-control-plane-workloads ClusterRole to that namespace. It will also configure Kuma’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 creation during installation.

Before installing Kuma, you must manually create the following resources:

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

You can find the complete set of required manifests here:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kuma-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
  - meshhealthchecks
  - meshhttproutes
  - meshloadbalancingstrategies
  - meshmetrics
  - meshpassthroughs
  - meshproxypatches
  - meshratelimits
  - meshretries
  - meshtcproutes
  - meshtimeouts
  - meshtlses
  - meshtraces
  - meshtrafficpermissions
  - hostnamegenerators
  - meshexternalservices
  - meshmultizoneservices
  - meshservices
  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

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

All required resources must be created before installing Kuma.

To disable automatic resource creation, use the following settings during installation:

Skip creation of all resources:

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

Skip only cluster-scoped resources:

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

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