Least Privilege Mode

		Enterprise
Available in these plans	Free	Dev	Prod	Scale
Least Privilege Mode

By default, to minimize operational overhead, the vCluster Platform Agent requests broad permissions to support all platform features.

If your organization follows strict RBAC policies, Least Privilege Mode can be used to limit the vCluster Platform Agent permissions only to your deployment needs.

Scope

Least Privilege Mode applies only to agents deployed on external host clusters. It does not apply to the agent running in the cluster where the platform is installed.

Agent Upgrades

To use this approach, you must disable automatic agent upgrades in the vCluster Platform because this process requires the agent to also have self-upgrade permissions.

Instead, you must manage the upgrades yourself, so that the agent permissions can be limited to its runtime needs.

See Self-managed agents / Disable agent upgrades for more details.

How it works

Least Privilege Mode is configured under agentValues.leastPrivilegeMode.

The following configuration options are available:

• Feature toggles - Enable/disable toggles for the features that should be supported by the agent (ClusterAccess, ProjectQuotas, Secrets, SleepMode).
• Cluster scope permissions – Controls the cluster scope permissions granted to the vCluster Platform Agent. Permissions can be extended to accommodate permissions for custom resources.
• Managed namespaces scope permissions – Controls the permissions granted to the vCluster Platform Agent into the namespaces where virtual cluster instances are installed.

When a feature toggle is disabled, the corresponding permissions will not be requested and the internal Kubernetes controllers will not be started.

Requests for the disabled features will not be fulfilled. For example, if the ProjectQuotas feature is disabled, the project quotas will not be enforced for the virtual cluster instances deployed on the connected cluster.

See the Configuration reference section for feature specific disabled state handling.

Example

The following example enables Least Privilege Mode and disables all optional features for the vCluster Platform agent:

platform.yaml

agentValues:
  leastPrivilegeMode:
    enabled: true
    clusterAccess:
      enabled: false
    projectQuotas:
      enabled: false
    secrets:
      enabled: false
    sleepMode:
      enabled: false

Configuration reference

leastPrivilegeMode

Least Privilege Mode configuration

enabled boolean false

Enables Least Privilege Mode for the agent

If set to false, the agent uses the default permission model configured via serviceAccount.clusterRole configuration.

clusterAccess object

Cluster Access feature configuration

enabled boolean true

Controls whether the agent supports the vCluster Platform Cluster Access feature.

If set to false, vCluster Platform users will not be able to access the connected cluster through the platform infrastructure.

projectQuotas object

Project Quotas feature configuration

enabled boolean true

Controls whether the agent supports the vCluster Platform Project Quotas feature.

If set to false, project quotas will not be enforced for the virtual cluster instances deployed on the connected cluster.

secrets object

Global/Project Secrets feature configuration

enabled boolean true

Controls whether the agent supports the vCluster Platform Global/Project Secrets feature.

If set to false, Global/Project secrets will not be synchronized with the connected cluster.

sleepMode object

SleepMode feature configuration

enabled boolean true

Controls whether the agent supports the vCluster Platform SleepMode feature.

If set to false, sleep/auto-sleep/wake actions will be ignored for the virtual cluster instances deployed on the connected cluster.

clusterRole object

ClusterRole configuration

enabled boolean true

Controls whether the vCluster Platform Agent ClusterRole and ClusterRoleBinding resources should be created.

Disable this if vCluster Platform Agent RBAC configuration is managed through different means.

extraRules object[]

Allows granting additional permissions to the vCluster Platform Agent at the cluster scope.

platform.yaml

agentValues:
  leastPrivilegeMode:
    enabled: true
    clusterRole:
      extraRules:
        - apiGroups: ["my.custom.group/v1"]
          resources: ["my-custom-resources"]
          verbs: ["get", "list", "watch"]

overwriteRules object[]

Allows overwriting the vCluster Platform Agent cluster scope permissions.

Advanced option. To be used only if you need to remove the default permissions granted to the agent.

namespaceAdminRole object

Managed namespace admin configuration

The vCluster Platform Agent namespace-admin Role provides permissions to allow the agent to manage virtual cluster instances within a managed namespace, without cluster-admin level permissions. As part of the virtual cluster instances reconciliation loop, the namespace-admin role is created in the managed namespace and assigned to the vCluster Platform Agent service account.

enabled boolean true

Controls whether the vCluster Platform Agent namespace-admin Role and RoleBinding resources should be created within the managed namespaces.

Disable this if vCluster Platform Agent RBAC configuration is managed through different means.

extraRules object[]

Allows granting additional permissions to the vCluster Platform Agent within the managed namespaces where virtual cluster instances are installed.

platform.yaml

agentValues:
  leastPrivilegeMode:
    enabled: true
    namespaceAdminRole:
      extraRules:
        - apiGroups: ["my.custom.group/v1"]
          resources: ["my-custom-resources"]
          verbs: ["get", "list", "watch"]

overwriteRules object[]

Allows overwriting the vCluster Platform Agent permissions within the managed namespaces.

Advanced option. To be used only if you need to remove the default permissions granted to the agent.

role object

Role configuration

The vCluster Platform Agent Role provides common Kubernetes controllers permissions required to allow the agent to function. Permissions for configMaps read, secrets read and coordination API are included in this role.

enabled boolean true

Controls whether the vCluster Platform Agent Role and RoleBinding resources should be created.

Disable this if vCluster Platform Agent RBAC configuration is managed through different means.

Recommended approach

Start with the absolute minimum configuration. Add the required features one by one.

A typical rollout looks like this:

1. Confirm that the vCluster Platform managed agent upgrades is disabled for the connected clusters.
2. Enable Least Privilege Mode and disable all optional features.
3. Verify deployment:
   • Confirm that virtual cluster instances can be deployed as expected.
   • Validate deployment compliance with your organization's policies.
4. Enable required features one by one and repeat the verification steps.
5. Test agent behavior in a non-production environment.
6. Roll out the same configuration to production.

Troubleshooting

If the agent stops working after enabling Least Privilege Mode:

• Review agent logs for RBAC permission errors. agentValues.env.KUBERNETES_VERBOSITY_LEVEL: "4" option can be used to gain visibility into the vCluster Platform Agent Kubernetes API requests.
• Confirm that you are applying this only to the agents running on external host clusters

If you need more help troubleshooting agent behavior, see Troubleshooting.