Device classes

		Enterprise
Available in these plans	Free	Dev	Prod	Scale
DRA Sync

Supported Configurations

Running the control plane as a container with:

• Host Nodes

By default, this is disabled.

DeviceClass syncing allows virtual clusters to use device classes from the host cluster. With DeviceClass syncing enabled, virtual clusters can reference DeviceClass resources from the host cluster in resourceclaims and resourceclaimtemplates.

You can enable this feature to sync DeviceClass resources from the host cluster to the virtual cluster. Add labels to DeviceClass resources in your host cluster and configure vCluster to sync only those that match specific label selectors. When you create a ResourceClaims or ResourceClaimTemplates resource in the virtual cluster that references a synced DeviceClass, the host cluster's resourceclaim controller handles the resource claims allocation.

This saves resources since you don't need resourceclaim controllers in every virtual cluster. It also gives you centralized control over which DeviceClass teams can access.

This approach is useful in scenarios where selective access to DeviceClass configurations is required. Common use cases include:

• Development environments: Sync only the DeviceClass resources required for development clusters to reduce noise and avoid unnecessary exposure.
• Multi-tenancy: Enable teams to use their own DeviceClass resources while sharing a single host cluster.
• Security: Restrict the DeviceClass resources available in the virtual cluster to enforce access control and prevent unintended configurations.

Enable syncing

When enabled, vCluster takes control of all DeviceClass resources in the virtual cluster. It only allows DeviceClass resources that are synced from the host cluster to exist.

This example configuration enables syncing all DeviceClass resources from the host cluster to the virtual cluster:

sync:
  fromHost:
    deviceClasses:
      enabled: true

If you try to create the DeviceClass resource directly in the virtual cluster, using for example kubectl create or kubectl apply, vCluster detects it and deletes it immediately. This prevents conflicts between locally created DeviceClass resources and those synced from the host cluster, ensuring that only DeviceClass resources from the host cluster exist in the virtual cluster.

DeviceClass resource limitation

When enabled, DeviceClass resource creation can only occur in the host cluster. Any DeviceClass resources created in the virtual cluster will be deleted.

How syncing works

When DeviceClass syncing is enabled, vCluster can use a label selector to control which DeviceClass, ResourceClaims and ResourceClaimTemplates resources are synchronized between the host and virtual clusters. This affects the resource types with separate unidirectional sync flows:

• DeviceClass resources (host → virtual): vCluster syncs DeviceClass resources from the host cluster to the virtual cluster. You cannot create DeviceClass resources directly in the virtual cluster. If a selector is defined, only DeviceClass resources matching the selector will sync. If no selector is defined, all DeviceClass resources are synced.

• ResourceClaims resources (virtual → host): vCluster syncs ResourceClaims resources from the virtual cluster to the host cluster only if all the referenced deviceClassName exist in the host cluster and any of the following is true:

  • No selector is defined for DeviceClass syncing, which allows all ResourceClaims resources to sync regardless of the deviceClassName.
  • Each of the ResourceClaims's deviceClassName references a DeviceClass resource that matches the selector and is synced from the host cluster.

• ResourceClaimTemplates resources (virtual → host): vCluster syncs ResourceClaimTemplates resources from the virtual cluster to the host cluster only if all the referenced deviceClassName exist in the host cluster and any of the following is true:

  • No selector is defined for DeviceClass syncing, which allows all ResourceClaimTemplates resources to sync regardless of the deviceClassName.
  • Each of the ResourceClaimTemplates's deviceClassName references a DeviceClass resource that matches the selector and is synced from the host cluster.

The same selector controls both sync flows. The selector determines which DeviceClass resources are imported from the host cluster and which ResourceClaims and ResourceClaimTemplates resources can sync to the host cluster based on the referenced DeviceClass resources.

Use selectors to filter

Selectors provide precise control over which DeviceClass resources get synced from the host cluster and which ResourceClaims resources gets synced to the host cluster. vCluster supports two types of selector criteria that follow standard Kubernetes label selector syntax.

Filter with matchLabels

The matchLabels selector defines exact label key-value pairs that must be present on an DeviceClass for it to be synced. This provides straightforward filtering based on specific labels.

The following example syncs only DeviceClass resources with a environment: development label:

Example with matchLabels

sync:
  toHost:
    resourceClaims:
      enabled: true
  fromHost:
    deviceClasses:
      enabled: true
      selector:
        matchLabels:
          environment: development

Filter with matchExpressions

The matchExpressions selector allows more flexible, set-based filtering with support for multiple operators:

• In: Select all resources that has a specific key and the value is in the set of values
• NotIn: Select all resources that has a specific key and the value is not in the set of values
• Exists: Select all resources including a label with the key; no values are checked
• DoesNotExist: Select all resources without a label with the key; no values are checked

The following example syncs DeviceClass resources where the key of the label is kubernetes.io/device.class and the value of that label is either nvidia or amd:

Example with matchExpressions

sync:
  toHost:
    resourceClaims:
      enabled: true
  fromHost:
    deviceClasses:
      enabled: true
      selector:
        matchExpressions:
          - key: kubernetes.io/device.class
            operator: In
            values:
              - nvidia
              - amd

Combined filter criteria

Label conditions are additive meaning all specified label conditions must match for the DeviceClass resource to be selected to be synced. This means that if you define multiple matchLabels and matchExpressions, the DeviceClass resource must satisfy all criteria to be synced to the virtual cluster.

The following example syncs DeviceClass resources that match both label and expression criteria:

Example with matchLabels and matchExpressions

sync:
  toHost:
    resourceClaims:
      enabled: true
  fromHost:
    deviceClasses:
      enabled: true
      selector:
        matchLabels:
          environment: development
        matchExpressions:
          - key: kubernetes.io/device.class
            operator: In
            values:
              - nvidia
              - amd

In this example, the DeviceClass must have the following labels to sync to the virtual cluster:

• environment: development
• Either kubernetes.io/device.class:nvidia or kubernetes.io/device.class:amd

Sync behavior considerations

Resource lifecycle

Synced DeviceClass resources function like any other Kubernetes resource in the virtual cluster. You can view them with kubectl get deviceclass and reference them in your ResourceClaims and ResourceClaimTemplates resources specifications with the DeviceClassName field.

When you modify the DeviceClass resource in the host cluster, vCluster re-evaluates whether it still matches the selector criteria. If the DeviceClass continues to match, vCluster updates the corresponding resource in the virtual cluster to reflect the changes. If the DeviceClass no longer matches the selector criteria, vCluster removes it from the virtual cluster.

The selector system acts as both a resource filter and a validation mechanism. As a resource filter, it ensures that vCluster creates only DeviceClass resources matching the defined selector criteria. The selector also functions as a creation validation mechanism - when you create ResourceClaims and ResourceClaimTemplates resources in the virtual cluster, the resources can only reference DeviceClass resources that exist in the virtual cluster.

Orphaned resources

When vCluster removes a synced DeviceClass from the virtual cluster due to selector changes or deletion from the host cluster, any ResourceClaims and ResourceClaimTemplates resources that reference it remain in the virtual and host clusters. These orphaned ResourceClaims and ResourceClaimTemplates resources stop receiving updates but vCluster does not automatically delete them to prevent unintended data loss.

To remove these orphaned resources, you must delete them manually in the virtual and host clusters. This manual approach ensures that you maintain full control over resource cleanup and can verify that deletions are intentional.

Error handling and troubleshooting

When the DeviceClass resource doesn't match the selector criteria during evaluation, vCluster logs a warning in the syncer pod's output to help with troubleshooting and monitoring. This logging provides visibility into which resources are being filtered out and why.

When you create ResourceClaims and ResourceClaimTemplates resources that reference a DeviceClass not matching the selector criteria, several things occur to provide clear feedback:

• The ResourceClaims or ResourceClaimTemplates fails to sync to the host cluster
• vCluster records an event on the ResourceClaims or ResourceClaimTemplates resource in the virtual cluster
• The event indicates that the specified DeviceClass is not available according to the current selector configuration

The error output appears as a Kubernetes event that you can view using kubectl describe. The event message clearly states that the ResourceClaims or ResourceClaimTemplates resource was not synced because the referenced DeviceClass does not match the defined selector criteria.

The error output looks like this:

Example error handling output

vcluster-virtual-cluster-1:~$ kubectl describe resourceclaim my-resourceclaim
Name:                       my-resourceclaim
Namespace:                  default
DeviceClass:                amd
Events:
  Type     Reason            Age   From                   Message
  ----     ------            ----  ----                    -------
  Warning  SyncWarning       10s   resourceclaim-syncer      did not sync resourceclaim "my-resourceclaim" to host. Failures : Device class amd does not match the selector under 'sync.fromHost.deviceClasses.selector'

Config reference

deviceClasses required object

DeviceClasses defines if device classes should get synced from the host cluster to the virtual cluster, but not back.

enabled required boolean false

Enabled defines if this option should be enabled.

patches required object[]

Patches patch the resource according to the provided specification.

path required string

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string

Kind is the kind of the referenced object.

kindPath required string

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string

NamePath is the optional relative path to the reference name within the object.

namespacePath required string

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object

Labels treats the path value as a labels selector.

selector required object

Selector defines the selector to use for the resource. If not set, all resources of that type will be synced.

matchLabels required object

matchExpressions required object[]

key required string

operator required string

values required string[]