How to enable GPU acceleration for DirectX in Windows containers - Container Service for Kubernetes

Background: What is DirectX

DirectX is a Windows API suite for 3D graphics, sound effects, and GPU-accelerated parallel computing in games and multimedia applications. It provides a unified driver standard that simplifies hardware setup.

Prerequisites

Before you begin, make sure you have:

An ACK managed cluster running Kubernetes 1.20.4 or later
A kubeconfig file configured for cluster access

Step 1: Create a Windows node pool with GPU support

Two node pool types support DirectX GPU acceleration:

	Standard Windows node pool	Elastic Windows node pool
Image source	ECS public images (default)	Custom image (required)
Supported OS	Windows Server 2019 only	Windows Server 2019 or Windows Server 2022
Setup effort	Lower — activate GRID driver, then create node pool	Higher — request shared image via ticket, then create node pool
Use when	You need a straightforward setup on Windows Server 2019	You need Windows Server 2022 or a pre-licensed custom image

Create a standard Windows node pool

Activate a licensed GRID driver:
- NVIDIA enterprise users: Download and install the GRID driver from the NVIDIA enterprise licensing site.
- Non-enterprise users: Use the community image with a pre-installed GRID driver.
Create a Windows node pool with this configuration:
- Instance type: A GPU-accelerated compute-optimized (gn, ebm, or scc series) or vGPU-accelerated (vgn or sgn series) instance type.
- Operating system: Windows Server 2019.

Create an elastic Windows node pool

Elastic Windows nodes require a custom image instead of the default ECS public images.

Submit a ticket to request a shared Windows image with an activated GRID driver license. Windows Server 2019 and Windows Server 2022 are supported by default. Specify the required Windows version in the ticket.
Create a Windows node pool with this configuration:
- Instance type: A GPU-accelerated compute-optimized (gn, ebm, or scc series) or vGPU-accelerated (vgn or sgn series) instance type.
- Operating system: Your required Windows version, such as Windows Server 2022.
- Custom image: The shared image you requested.

Step 2: Install the DirectX device plugin

Deploy the DirectX device plugin as a DaemonSet on Windows nodes.

Create a directx-device-plugin-windows.yaml file with this content:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  labels:
    k8s-app: directx-device-plugin-windows
  name: directx-device-plugin-windows
  namespace: kube-system
spec:
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      k8s-app: directx-device-plugin-windows
  template:
    metadata:
      annotations:
        scheduler.alpha.kubernetes.io/critical-pod: ""
      labels:
        k8s-app: directx-device-plugin-windows
    spec:
      tolerations:
        - operator: Exists
      # hostNetwork: true is supported for Windows workloads since Kubernetes 1.18,
      # allowing deployment without NetworkReady.
      hostNetwork: true
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: type
                    operator: NotIn
                    values:
                      - virtual-kubelet
                  - key: beta.kubernetes.io/os
                    operator: In
                    values:
                      - windows
                  - key: windows.alibabacloud.com/deployment-topology
                    operator: In
                    values:
                      - "2.0"
                  - key: windows.alibabacloud.com/directx-supported
                    operator: In
                    values:
                      - "true"
              - matchExpressions:
                  - key: type
                    operator: NotIn
                    values:
                      - virtual-kubelet
                  - key: kubernetes.io/os
                    operator: In
                    values:
                      - windows
                  - key: windows.alibabacloud.com/deployment-topology
                    operator: In
                    values:
                      - "2.0"
                  - key: windows.alibabacloud.com/directx-supported
                    operator: In
                    values:
                      - "true"
      containers:
        - name: directx
          command:
            - pwsh.exe
            - -NoLogo
            - -NonInteractive
            - -File
            - entrypoint.ps1
          # Replace the region in the image address with the region of your cluster.
          image: registry-cn-hangzhou-vpc.ack.aliyuncs.com/acs/directx-device-plugin-windows:v1.0.0
          imagePullPolicy: IfNotPresent
          volumeMounts:
            - name: host-binary
              mountPath: c:/host/opt/bin
            - name: wins-pipe
              mountPath: \\.\pipe\rancher_wins
      volumes:
        - name: host-binary
          hostPath:
            path: c:/opt/bin
            type: DirectoryOrCreate
        - name: wins-pipe
          hostPath:
            path: \\.\pipe\rancher_wins

Deploy the DaemonSet:

kubectl create -f directx-device-plugin-windows.yaml

Step 3: Enable DirectX GPU acceleration for a workload

The DirectX device plugin automatically adds the class/<interface class GUID> device to Windows containers, enabling DirectX access on the ECS host. See Devices in containers on Windows.

Add the resources field to the container spec of any workload that requires GPU acceleration:

spec:
  ...
  template:
    ...
    spec:
      ...
      containers:
        - name: gpu-user
          ...
+         resources:
+           limits:
+             windows.alibabacloud.com/directx: "1"
+           requests:
+             windows.alibabacloud.com/directx: "1"

Important

This does not exclusively allocate GPU resources to one container. GPU resources are shared dynamically between the ECS host and containers, so multiple Windows containers on the same host can use DirectX acceleration simultaneously.

See GPU acceleration in Windows containers.

Step 4: Verify GPU acceleration

Run a sample GPU job to verify DirectX acceleration.

Create a gpu-job-windows.yaml file with this content:

apiVersion: batch/v1
kind: Job
metadata:
  labels:
    k8s-app: gpu-job-windows
  name: gpu-job-windows
  namespace: default
spec:
  parallelism: 1
  completions: 1
  backoffLimit: 3
  manualSelector: true
  selector:
    matchLabels:
      k8s-app: gpu-job-windows
  template:
    metadata:
      labels:
        k8s-app: gpu-job-windows
    spec:
      restartPolicy: Never
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: type
                    operator: NotIn
                    values:
                      - virtual-kubelet
                  - key: beta.kubernetes.io/os
                    operator: In
                    values:
                      - windows
              - matchExpressions:
                  - key: type
                    operator: NotIn
                    values:
                      - virtual-kubelet
                  - key: kubernetes.io/os
                    operator: In
                    values:
                      - windows
      tolerations:
        - key: os
          value: windows
      containers:
        - name: gpu
          # Replace the region in the image address with the region of your cluster.
          image: registry-cn-hangzhou-vpc.ack.aliyuncs.com/acs/sample-gpu-windows:v1.0.0
          imagePullPolicy: IfNotPresent
          resources:
            limits:
              windows.alibabacloud.com/directx: "1"
            requests:
              windows.alibabacloud.com/directx: "1"

Note

The sample image registry-{region}-vpc.ack.aliyuncs.com/acs/sample-gpu-windows is built on Microsoft Windows (15.3 GB, may take time to pull). The job uses WinMLRunner to run 100 Tiny YOLOv2 evaluations and output performance data. Results may vary by environment.

Deploy the job:
```
kubectl create -f gpu-job-windows.yaml
```

Check the job logs:

kubectl logs -f gpu-job-windows

Expected output:

INFO: Executing model of "tinyyolov2-7" 100 times within GPU driver ...

Created LearningModelDevice with GPU: NVIDIA GRID T4-8Q
Loading model (path = c:\data\tinyyolov2-7\model.onnx)...
=================================================================
Name: Example Model
Author: OnnxMLTools
Version: 0
Domain: onnxconverter-common
Description: The Tiny YOLO network from the paper 'YOLO9000: Better, Faster, Stronger' (2016), arXiv:1612.08242
Path: c:\data\tinyyolov2-7\model.onnx
Support FP16: false

Input Feature Info:
Name: image
Feature Kind: Image (Height: 416, Width:  416)

Output Feature Info:
Name: grid
Feature Kind: Float

This confirms the gpu-job-windows job runs with DirectX GPU acceleration.