Runtime classes

By default, this is disabled.

RuntimeClass syncing allows virtual clusters to use runtime classes from the host cluster. RuntimeClass resources define container runtime configurations including security sandboxes, alternative runtimes like gVisor or Kata Containers, and runtime-specific settings.

Virtual clusters are isolated from each other; a RuntimeClass created in one virtual cluster does not exist in another. For more details on enabling and disabling synced resources, see the sync configuration documentation.

You can enable this feature to sync RuntimeClass resources from the host cluster to the virtual cluster. Add labels to RuntimeClass resources in your host cluster and configure vCluster to sync only those matching specific selectors. When you create a Pod that references a synced RuntimeClass, the host cluster uses that runtime configuration.

This approach provides centralized control over runtime configurations and ensures consistent container runtime behavior across virtual clusters. Common use cases include:

• Security isolation: Control which security runtimes different teams can access while sharing a single host cluster. Only authorized workloads can use enhanced security runtimes such as gVisor or Kata Containers. This prevents unauthorized access to privileged runtime configurations.

• Development environments: Sync only required RuntimeClasses to reduce noise and avoid unnecessary exposure to production runtime configurations.

• Multi-tenancy: Enable teams to use specific runtime configurations while preventing access to incompatible or resource-intensive runtimes that could affect other tenants. Each team gets only the runtime classes appropriate for their workloads and security requirements.

• Compliance: Maintain strict control over container runtime configurations by defining runtime classes once in the host cluster and making only approved runtime configurations available to virtual clusters. All workloads use compliant runtime settings.

• Resource optimization: Prevent teams from using resource-intensive runtime configurations that could impact cluster performance without proper oversight. Access to high-overhead runtimes is restricted and used only when necessary.

Enable syncing

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

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

sync:
  fromHost:
    runtimeClasses:
      enabled: true

If you try to create the RuntimeClass 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 RuntimeClass resources and those synced from the host cluster, ensuring that only RuntimeClass resources from the host cluster exist in the virtual cluster.

RuntimeClass resource limitation

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

How syncing works

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

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

• Pod resources (virtual → host): vCluster syncs Pod resources from the virtual cluster to the host cluster only if any of the following is true:

  • No selector is defined for RuntimeClass syncing, which allows all Pod resources to sync regardless of the runtimeClassName.
  • The Pod's runtimeClassName references a RuntimeClass resource that matches the selector and is synced from the host cluster.
  • The Pod has an empty runtimeClassName field.

The same selector controls both sync flows. The selector determines which RuntimeClass resources are imported from the host cluster and which Pod resources can sync to the host cluster based on the referenced RuntimeClass resource.

Use selectors to filter

Selectors provide precise control over which RuntimeClass resources get synced from the host cluster and which Pod 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 RuntimeClass for it to be synced. This provides straightforward filtering based on specific labels.

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

Example with matchLabels

sync:
  fromHost:
    runtimeClasses:
      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 RuntimeClass resources where the key of the label is kubernetes.io/runtime.class and the value of that label is either gvisor or youki:

Example with matchExpressions

sync:
  fromHost:
    runtimeClasses:
      enabled: true
      selector:
        matchExpressions:
          - key: kubernetes.io/runtime.class
            operator: In
            values:
              - gvisor
              - youki

Combined filter criteria

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

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

Example with matchLabels and matchExpressions

sync:
  fromHost:
    runtimeClasses:
      enabled: true
      selector:
        matchLabels:
          environment: development
        matchExpressions:
          - key: kubernetes.io/runtime.class
            operator: In
            values:
              - gvisor
              - youki

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

• environment: development
• Either kubernetes.io/runtime.class:gvisor or kubernetes.io/runtime.class:youki

Sync behavior considerations

Resource lifecycle

Synced RuntimeClass resources function like any other Kubernetes resource in the virtual cluster. You can view them with kubectl get runtimeclass and reference them in your Pod resource specifications with the runtimeClassName field.

When you modify the RuntimeClass resource in the host cluster, vCluster re-evaluates whether it still matches the selector criteria. If the RuntimeClass continues to match, vCluster updates the corresponding resource in the virtual cluster to reflect the changes. If the RuntimeClass 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 RuntimeClass resources matching the defined selector criteria. The selector also functions as a creation validation mechanism - when you create Pod resources in the virtual cluster, the resources can only reference RuntimeClass resources that exist in the virtual cluster.

Orphaned resources

When vCluster removes a synced RuntimeClass from the virtual cluster due to selector changes or deletion from the host cluster, any Pod resources that reference it remain in the virtual and host clusters. These orphaned Pod 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 RuntimeClass 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 creates the Pod resource that references a RuntimeClass not matching the selector criteria, several things occur to provide clear feedback:

• The Pod fails to sync to the host cluster
• vCluster records an event on the Pod resource in the virtual cluster
• The event indicates that the specified RuntimeClass 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 Pod resource was not synced because the referenced RuntimeClass does not match the defined selector criteria.

The error output looks like this:

Example error handling output

vcluster-virtual-cluster-1:~$ kubectl describe pod my-pod
Name:                       my-pod
Namespace:                  default
RuntimeClass:     youki
Events:
  Type     Reason            Age   From                   Message
  ----     ------            ----  ----                    -------
  Warning  SyncWarning       10s   pod-syncer      did not sync pod "my-pod" to host because it does not match the selector under 'sync.fromHost.runtimeClasses.selector'

Config reference

runtimeClasses required object pro

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

enabled required boolean false pro

Enabled defines if this option should be enabled.

patches required object[] pro

Patches patch the resource according to the provided specification.

path required string pro

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 pro

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string pro

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object pro

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 pro

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string pro

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

kind required string pro

Kind is the kind of the referenced object.

kindPath required string pro

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

namePath required string pro

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

namespacePath required string pro

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 pro

Labels treats the path value as a labels selector.

selector required object pro

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

matchLabels required object pro

matchExpressions required object[] pro

key required string pro

operator required string pro

values required string[] pro