RBAC

vCluster automatically generates the RBAC roles and bindings it needs based on the features you enable and the resources you choose to sync.

note

Some configuration options modify or add to the default RBAC rules. If you're using any of the following, vCluster includes the necessary permissions. When enabled, the following configuration fields modify the default behavior:

• controlPlane.advanced.virtualScheduler: Adds required read permissions for the virtual scheduler.
• networking.replicateServices.fromHost: Adds required permissions to manage endpoints and services.
• integrations.metrics.proxy.nodes: Adds required read permissions for node resources.
• plugins: Adds roles and clusterRoles defined by each plugin.
• sync.toHost.namespaces: Adds required permissions for vCluster to manage namespaces and service accounts.

Disable automatic RBAC generation

In environments with strict access controls, users may not have permission to create Kubernetes RBAC resources such as Role, ClusterRole, or ServiceAccount. In these cases, you can configure vCluster to use a service account that has already been created by an administrator with the necessary permissions. To do this, disable vCluster’s automatic RBAC generation and reference the managed service account in vcluster.yaml:

Use a managed service account and disable default RBAC

controlPlane:
  advanced:
    serviceAccount:
      name: custom-vc-sa
rbac:
  role:
    enabled: false
  clusterRole:
    enabled: false

Alternatively, you can disable ClusterRole creation—this is often necessary when users don’t have permission to create ClusterRole resources:

Disable only ClusterRole creation

rbac:
  clusterRole:
    enabled: false

Add custom RBAC rules

Use extraRules to configure additional RBAC rules when the automatically generated or plugin rules are not sufficient. Use this option sparingly—most configurations should not require it. The following example shows how to apply it:

Add extra RBAC rules

rbac:
  role:
    enabled: true
    extraRules:
      - apiGroups: [""]
        resources: ["pods/status", "pods/ephemeralcontainers"]
        verbs: ["patch", "update"]

Overwrite rules

For more control over permissions, use overwriteRules to disable the default rules generated by the vCluster Helm chart.

When overwriteRules is enabled, you must manually define all required rules for the vCluster and its plugins to function. This approach can simplify permission management by allowing the Helm chart to still create the Role, RoleBinding, and ServiceAccount, while you retain full control over the rules.

The following example disables cluster-wide rules and specifies namespace-level permissions:

Overwrite all default RBAC rules

rbac:
  role:
    enabled: true
    overwriteRules:
      - apiGroups: [""]
        resources: ["pods/status", "pods/ephemeralcontainers"]
        verbs: ["patch", "update"]
  clusterRole:
    enabled: false

Config reference

rbac required object pro

RBAC options for the virtual cluster.

role required object pro

Role holds virtual cluster role configuration

enabled required boolean true pro

Enabled defines if the role should be enabled or disabled.

extraRules required object[] [] pro

ExtraRules will add rules to the role.

overwriteRules required object[] [] pro

OverwriteRules will overwrite the role rules completely.

clusterRole required object pro

ClusterRole holds virtual cluster cluster role configuration

enabled required string|boolean auto pro

Enabled defines if the cluster role should be enabled or disabled. If auto, vCluster automatically determines whether the virtual cluster requires a cluster role.

extraRules required object[] [] pro

ExtraRules will add rules to the cluster role.

overwriteRules required object[] [] pro

OverwriteRules will overwrite the cluster role rules completely.