GPU Passthrough (Experimental)

How to enable GPU passthrough for an Orka VM.

🚧

Quick navigation

Jump to: Defaults | Limitations | Enable GPU Passthrough for new VM configurations | Enable GPU Passthrough at time of VM deploy

When creating a VM config or deploying a VM using an existing config, you can choose to enable GPU passthrough for the VM. All VMs deployed from a config with GPU passthrough enabled will attempt to deploy a VM in the cluster utilizing the host GPU of the selected node. This can be disabled or enabled per VM at the time of deployment.

📘

IMPORTANT

GPU passthrough must first be enabled in your cluster in order to use this feature. Contact the MacStadium team for more details.

At this time, GPU passthrough is only supported in clusters with the 2013 Mac Pro. The feature is enabled per node if the host contains dual AMD FirePro D500 cards.

Before you begin, make sure that your Orka environment is updated to Orka 1.5.0 or later and that GPU passthrough is enabled in the cluster


Defaults

By default, GPU passthrough is disabled at the environment level. The feature must first be enabled in the cluster in order to create a VM config with GPU passthrough enabled, or to deploy a VM with GPU passthrough.

GPU passthrough can be enabled in the cluster either at the time of cluster provisioning or during an API update. Contact the MacStadium team for more information.

GPU passthrough is disabled by default in all new VM configurations, and must be explicitly enabled at the time of config creation or VM deployment. For VM configurations created with Orka 1.4.3 or earlier, the setting is disabled.

Limitations

  • GPU passthrough is currently only available on 2013 Mac Pro hosts with dual AMD FirePro D500 cards
  • The cluster must be configured to use the OpenCore bootloader for all virtual machines
  • Only one VM per node can be deployed at a time utilizing GPU passthrough. Both cards on the host will be passed to the VM
  • VNC console cannot be enabled for a VM utilizing GPU passthrough. Apple Screen Sharing and/or SSH access should be enabled in the base image
  • The VM cannot be shut down or rebooted from within the guest, e.g. Apple menu → Shut Down …

❗️

DANGER

Shutting down the VM improperly may cause the host to lock up, requiring a reboot of the node and downtime in the cluster. Use extreme caution when making use of this feature. The VM should always be shut down and booted using the orka vm start and orka vm stop commands.

There is no need to run orka vm stop before deleting or purging a VM.

📘

IMPORTANT

gpu_passthrough and vnc_console cannot both be set to true, or the Orka API will return an error. When gpu_passthrough is set to true VNC console is automatically disabled in the config if not explicitly specified.

Enable GPU Passthrough for new VM configurations

To create a VM configuration with GPU passthrough enabled, either send a request to the Orka API as follows or use the ORKA CLI:

ORKA API

curl --location --request POST 'http://10.221.188.100/resources/vm/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data-raw '{
    "orka_vm_name": "<NAME>",
    "orka_base_image": "<BASE_IMAGE>",
    "orka_image": "<NAME>",
    "orka_cpu_core": <CPU_COUNT>,
    "vcpu_count": <VCPU_COUNT>,
    "gpu_passthrough": true,
    "vnc_console": false
}'

ORKA CLI

orka vm create-config -v <VM_NAME> -b <BASE_IMAGE> -c <CPU> -C <VCPU> --vnc no --gpu yes 

OR

orka vm create-config -v <VM_NAME> -b <BASE_IMAGE> -c <CPU> -C <VCPU> --vnc no --gpu yes -y

All VMs deployed with this configuration will deploy a VM with GPU passthrough enabled by default, unless disabled at the time of deployment.

Enable GPU Passthrough at time of VM deploy

GPU passthrough can also be enabled or disabled at the time of deployment. This can allow you to utilize a VM configuration created without GPU passthrough enabled, or even a configuration created with a prior version of Orka:

ORKA API

curl --location --request POST 'http://10.221.188.100/resources/vm/deploy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data-raw '{
    "orka_vm_name": "<NAME>",
    "gpu_passthrough": true,
    "vnc_console": false
}'

ORKA CLI

orka vm deploy -v <VM_NAME> --gpu yes --vnc no

OR 

orka vm deploy -v <VM_NAME> --gpu yes --vnc no -y

Enable GPU Passthrough on VM create via the ORKA CLI

orka vm create -v <VM_NAME> -b <BASE_IMAGE> -c <CPU> -C <VCPU> --vnc no --gpu yes 

OR

orka vm create -v <VM_NAME> -b <BASE_IMAGE> -c <CPU> -C <VCPU> --vnc no --gpu yes -y

Did this page help you?