Призначення пристроїв Podʼам та контейнерам

• 1: Налаштування DRA у кластері
• 2: Призначення пристроїв робочим навантаженням за допомогою DRA
• 3: Доступ до метаданих пристроїв DRA

1 - Налаштування DRA у кластері

На цій сторінці показано, як налаштувати динамічне виділення ресурсів (DRA) у кластері Kubernetes шляхом активації груп API та налаштування класів пристроїв. Ці інструкції призначені для адміністраторів кластерів.

Про DRA

Функція Kubernetes, яка дозволяє вам запитувати ресурси та ділитися ними з іншими Podʼами. Ці ресурси часто приєднуються до пристроїів, наприклад, до апаратних прискорювачів.

З DRA драйвери пристроїв і адміністратори кластерів визначають класи пристроїв, які доступні для заявки в робочих навантаженнях. Kubernetes виділяє відповідні пристрої для конкретних заявок і розміщує відповідні Podʼи на вузлах, які можуть отримати доступ до виділених пристроїв.

Переконайтеся, що ви ознайомлені з принципом роботи DRA та термінологією DRA, такою як DeviceClasses, ResourceClaims і ResourceClaimTemplates. Детальніше дивіться Динамічне виділення ресурсів (DRA).

Перш ніж ви розпочнете

Вам треба мати кластер Kubernetes, а також інструмент командного рядка kubectl має бути налаштований для роботи з вашим кластером. Рекомендується виконувати ці настанови у кластері, що має щонайменше два вузли, які не виконують роль вузлів управління. Якщо у вас немає кластера, ви можете створити його, за допомогою minikube або використовувати одну з цих пісочниць:

• iximiuz Labs
• Killercoda
• KodeKloud

Для перевірки версії введіть kubectl version.

• Підключіть пристрої до вашого кластера безпосередньо або опосередковано. Щоб уникнути можливих проблем із драйверами, дочекайтеся налаштування функції DRA для вашого кластера перед встановленням драйверів.

Опціонально: увімкніть додаткові групи API DRA

Загалом DRA є стабільною функцією в Kubernetes, проте деякі її аспекти можуть бути ще в стадії альфа- або бета-тестування. Якщо ви хочете використовувати будь-який аспект DRA, який ще не є стабільним, а повʼязана з ним функція залежить від спеціального типу API, тоді ви повинні увімкнути відповідні групи альфа- або бета-API.

Деякі старі драйвери або робочі навантаження DRA можуть все ще потребувати API v1beta1 з Kubernetes 1.30 або v1beta2 з Kubernetes 1.32. Тільки якщо потрібна підтримка цих версій, увімкніть наступні групи API:

• resource.k8s.io/v1beta1
• resource.k8s.io/v1beta2

Функції Alpha з окремими типами API потребують:

• resource.k8s.io/v1alpha3

Для отримання додаткової інформації дивіться Увімкнення або вимкнення груп API.

Перевірте, що DRA увімкнено

Щоб перевірити правильність налаштування кластера, спробуйте вивести список DeviceClasses:

kubectl get deviceclasses

Якщо конфігурація компонентів була правильною, ви побачите подібний результат:

No resources found

Якщо DRA налаштовано неправильно, результат буде схожий на:

error: the server doesn't have a resource type "deviceclasses"

Наприклад, це може статися, коли група API resource.k8s.io була вимкнена. Аналогічна перевірка застосовується до типів верхнього рівня якості альфа або бета.

Спробуйте наступні кроки для усунення несправностей:

1. Переконфігуруйте та перезапустіть компонент kube-apiserver.

2. Якщо повне поле .spec.resourceClaims видаляється з Podʼів, або якщо Podʼи плануються без урахування ResourceClaims, перевірте, чи не вимкнено функціональну можливість DynamicResourceAllocation для kube-apiserver, kube-controller-manager, kube-scheduler або kubelet.

Встановіть драйвери пристроїв

Після активації DRA для вашого кластера ви можете встановити драйвери для підключених пристроїв. Інструкції шукайте у документації виробника пристрою або проєкту, що підтримує драйвери. Встановлені драйвери мають бути сумісні з DRA.

Щоб перевірити роботу встановлених драйверів, виведіть список ResourceSlices у кластері:

kubectl get resourceslices

Вивід буде схожий на:

NAME                                                  NODE                DRIVER               POOL                             AGE
00000-driver.example.com-cluster-1-node-1-abcde      cluster-1-node-1    driver.example.com   cluster-1-device-pool-1-r1gc     7s
00000-driver.example.com-cluster-1-node-2-fghij      cluster-1-node-2    driver.example.com   cluster-1-device-pool-2-446z     8s

Спробуйте наступні кроки для усунення несправностей:

1. Перевірте стан драйвера DRA та шукайте повідомлення про помилки щодо публікації ResourceSlices у виводі його журналу. Постачальник драйвера може надати додаткові інструкції щодо встановлення та усунення несправностей.

Створіть DeviceClasses

Ви можете визначити категорії пристроїв, які оператори ваших застосунків можуть використовувати у робочих навантаженнях, створюючи DeviceClasses. Деякі постачальники драйверів також можуть рекомендувати створити DeviceClasses під час встановлення драйверів.

ResourceSlices, які публікує ваш драйвер, містять інформацію про пристрої, якими керує драйвер, такі як ємність, метадані та атрибути. Ви можете використовувати Загальна мова виразів для фільтрації властивостей у DeviceClasses, що спрощує пошук пристроїв для операторів навантажень.

1. Щоб знайти властивості пристрою, які можна вибирати у DeviceClasses за допомогою виразів CEL, отримайте специфікацію ResourceSlice:

   kubectl get resourceslice <resourceslice-name> -o yaml
   

   Вивід буде схожий на:

   apiVersion: resource.k8s.io/v1
   kind: ResourceSlice
   # lines omitted for clarity
   spec:
     devices:
     - attributes:
         type:
           string: gpu
       capacity:
         memory:
           value: 64Gi
       name: gpu-0
     - attributes:
         type:
           string: gpu
       capacity:
         memory:
           value: 64Gi
       name: gpu-1
     driver: driver.example.com
     nodeName: cluster-1-node-1
   # lines omitted for clarity
   

   Ви також можете переглянути документацію постачальника драйверів для доступних властивостей і значень.

2. Ознайомтеся з прикладом маніфесту DeviceClass, який вибирає будь-який пристрій, керований драйвером driver.example.com:

   dra/deviceclass.yaml

   apiVersion: resource.k8s.io/v1
    kind: DeviceClass
    metadata:
      name: example-device-class
    spec:
      selectors:
      - cel:
          expression: |-
            device.driver == "driver.example.com"
    

3. Створіть DeviceClass у вашому кластері:

   kubectl apply -f https://k8s.io/examples/dra/deviceclass.yaml
   

очищення

Щоб видалити DeviceClass, створений у цьому завданні, виконайте команду:

kubectl delete -f https://k8s.io/examples/dra/deviceclass.yaml

Що далі

• Дізнайтеся більше про DRA
• Виділення пристроїв для навантажень за допомогою DRA

2 - Призначення пристроїв робочим навантаженням за допомогою DRA

На цій сторінці показано, як призначати пристрої для ваших Podʼів за допомогою динамічного розподілу ресурсів (DRA). Ці інструкції призначені для операторів робочих навантажень. Перед прочитанням цієї сторінки ознайомтеся з принципами роботи DRA та термінами, такими як ResourceClaims і ResourceClaimTemplates. Докладніше дивіться у розділі Динамічний розподіл ресурсів (DRA).

Про призначення пристроїв з DRA

Як оператор робочих навантажень, ви можете запитувати пристрої для своїх навантажень, створюючи ResourceClaims або ResourceClaimTemplates. Під час розгортання навантаження Kubernetes і драйвери пристроїв знаходять доступні пристрої, призначають їх вашим Podʼам і розміщують Podʼи на вузлах, які мають доступ до цих пристроїв.

Перш ніж ви розпочнете

Вам треба мати кластер Kubernetes, а також інструмент командного рядка kubectl має бути налаштований для роботи з вашим кластером. Рекомендується виконувати ці настанови у кластері, що має щонайменше два вузли, які не виконують роль вузлів управління. Якщо у вас немає кластера, ви можете створити його, за допомогою minikube або використовувати одну з цих пісочниць:

• iximiuz Labs
• Killercoda
• KodeKloud

Для перевірки версії введіть kubectl version.

• Переконайтеся, що адміністратор вашого кластера налаштував DRA, підключив пристрої та встановив драйвери. Докладніше дивіться у розділі Налаштування DRA у кластері.

Визначення пристроїв для подання заявок на них

Адміністратор вашого кластера або драйвери пристроїв створюють DeviceClasses, які визначають категорії пристроїв. Ви можете отримувати пристрої, використовуючи Загальна мова виразів для фільтрації за конкретними властивостями пристроїв.

Отримайте список DeviceClasses у кластері:

kubectl get deviceclasses

Вивід буде схожим на наступний:

NAME                 AGE
driver.example.com   16m

Якщо ви отримали помилку доступу, можливо, у вас немає прав для перегляду DeviceClasses. Зверніться до адміністратора кластера або постачальника драйверів щодо доступних властивостей пристроїв.

Запитування ресурсів

Ви можете запитувати ресурси з DeviceClass за допомогою ResourceClaims. Щоб створити ResourceClaim, виконайте одну з наступних дій:

• Створіть ResourceClaim вручну, якщо ви хочете, щоб декілька Podʼів мали спільний доступ до одних і тих самих пристроїв, або якщо ви хочете, щоб claim існував довше, ніж Pod.
• Використовуйте ResourceClaimTemplate, щоб Kubernetes генерував і керував ResourceClaims для кожного Podʼа. Створіть ResourceClaimTemplate, якщо ви хочете, щоб кожен Pod мав доступ до окремих пристроїв із подібними конфігураціями. Наприклад, це може знадобитися для одночасного доступу до пристроїв у Pod для Job, який використовує паралельне виконання.

Якщо ви безпосередньо посилаєтеся на конкретний ResourceClaim у Pod, цей ResourceClaim вже має існувати у кластері. Якщо зазначений ResourceClaim не існує, Pod залишатиметься у стані очікування, доки ResourceClaim не буде створено. Ви можете посилатися на автоматично створений ResourceClaim у Podʼі, але це не рекомендується, оскільки такі ResourceClaim прив'язані до часу життя Pod, який їх створив.

Щоб створити робоче навантаження, яке отримує ресурси, виберіть одну з наступних опцій:

• ResourceClaimTemplate
• ResourceClaim

Ознайомтеся з наступним прикладом маніфесту:

dra/resourceclaimtemplate.yaml

apiVersion: resource.k8s.io/v1
kind: ResourceClaimTemplate
metadata:
  name: example-resource-claim-template
spec:
  spec:
    devices:
      requests:
      - name: gpu-claim
        exactly:
          deviceClassName: example-device-class
          selectors:
            - cel:
                expression: |-
                  device.attributes["driver.example.com"].type == "gpu" &&
                  device.capacity["driver.example.com"].memory == quantity("64Gi")

Цей маніфест створює ResourceClaimTemplate, який запитує пристрої у DeviceClass example-device-class, що відповідають обом наступним параметрам:

• Пристрої, які мають атрибут driver.example.com/type зі значенням gpu.
• Пристрої, які мають ємність 64Gi.

Щоб створити ResourceClaimTemplate, виконайте наступну команду:

kubectl apply -f https://k8s.io/examples/dra/resourceclaimtemplate.yaml

Ознайомтеся з наступним прикладом маніфесту:

dra/resourceclaim.yaml

apiVersion: resource.k8s.io/v1
kind: ResourceClaim
metadata:
  name: example-resource-claim
spec:
  devices:
    requests:
    - name: single-gpu-claim
      exactly:
        deviceClassName: example-device-class
        allocationMode: All
        selectors:
        - cel:
            expression: |-
              device.attributes["driver.example.com"].type == "gpu" &&
              device.capacity["driver.example.com"].memory == quantity("64Gi")

Цей маніфест створює ResourceClaim, який запитує пристрої у DeviceClass example-device-class, що відповідають обом наступним параметрам:

• Пристрої, які мають атрибут driver.example.com/type зі значенням gpu.
• Пристрої, які мають ємність 64Gi.

Щоб створити ResourceClaim, виконайте наступну команду:

kubectl apply -f https://k8s.io/examples/dra/resourceclaim.yaml

Запит пристроїв у робочих навантаженнях за допомогою DRA

Щоб запросити пристрій, вкажіть ResourceClaim або ResourceClaimTemplate у полі resourceClaims специфікації Podʼа. Потім запросіть конкретний claim за назвою у полі resources.claims контейнера цього Podʼа. Ви можете вказати декілька записів у полі resourceClaims та використовувати конкретні claims у різних контейнерах.

1. Ознайомтеся з наступним прикладом Job:

   dra/dra-example-job.yaml

   apiVersion: batch/v1
   kind: Job
   metadata:
     name: example-dra-job
   spec:
     completions: 10
     parallelism: 2
     template:
       spec:
         restartPolicy: Never
         containers:
         - name: container0
           image: ubuntu:24.04
           command: ["sleep", "9999"]
           resources:
             claims:
             - name: separate-gpu-claim
         - name: container1
           image: ubuntu:24.04
           command: ["sleep", "9999"]
           resources:
             claims:
             - name: shared-gpu-claim
         - name: container2
           image: ubuntu:24.04
           command: ["sleep", "9999"]
           resources:
             claims:
             - name: shared-gpu-claim
         resourceClaims:
         - name: separate-gpu-claim
           resourceClaimTemplateName: example-resource-claim-template
         - name: shared-gpu-claim
           resourceClaimName: example-resource-claim
   

   Кожен Pod у цьому Job має наступні властивості:

   • Робить доступними для контейнерів ResourceClaimTemplate з назвою separate-gpu-claim та ResourceClaim з назвою shared-gpu-claim.
   • Запускає наступні контейнери:
     • container0 запитує пристрої з ResourceClaimTemplate separate-gpu-claim.
     • container1 та container2 мають спільний доступ до пристроїв з ResourceClaim shared-gpu-claim.

2. Створіть Job:

   kubectl apply -f https://k8s.io/examples/dra/dra-example-job.yaml
   

Спробуйте наступні кроки для усунення неполадок:

1. Коли робоче навантаження не запускається, як очікувалося, перевірте обʼєкти на кожному рівні з kubectl describe, щоб дізнатися, чи є якісь поля статусу або події, які можуть пояснити, чому робоче навантаження не запускається.
2. Коли створення Pod не вдається з must specify one of: resourceClaimName, resourceClaimTemplateName, перевірте, що всі записи в pod.spec.resourceClaims мають точно одне з цих полів. Якщо так, то можливо, що в кластері встановлено модифікуючий веб-хук Podʼа, який був створений для API Kubernetes < 1.32. Попросіть адміністратора кластера перевірити це.

Очищення

Щоб видалити обʼєкти Kubernetes, створені у цьому завданні, виконайте наступні кроки:

1. Видаліть приклад Job:

   kubectl delete -f https://k8s.io/examples/dra/dra-example-job.yaml
   

2. Щоб видалити свої claims ресурсів, виконайте одну з наступних команд:

   • Видаліть ResourceClaimTemplate:

     kubectl delete -f https://k8s.io/examples/dra/resourceclaimtemplate.yaml
     

   • Видаліть ResourceClaim:

     kubectl delete -f https://k8s.io/examples/dra/resourceclaim.yaml
     

Що далі

• Дізнайтеся більше про DRA

3 - Доступ до метаданих пристроїв DRA

Ця сторінка показує, як отримати доступ до метаданих пристроїв з контейнерів, які використовують динамічний розподіл ресурсів (DRA). Метадані пристроїв дозволяють робочим навантаженням дізнаватися інформацію про виділені пристрої, такі як атрибути пристроїв або деталі мережевого інтерфейсу, шляхом читання JSON-файлів за відомими шляхами всередині контейнера.

Перед тим як ознайомитися з цією сторінкою, перегляньте інформацію про Динамічний розподіл ресурсів (DRA) та про те, як виділяти пристрої для робочих навантажень.

Перш ніж ви розпочнете

Вам треба мати кластер Kubernetes, а також інструмент командного рядка kubectl має бути налаштований для роботи з вашим кластером. Рекомендується виконувати ці настанови у кластері, що має щонайменше два вузли, які не виконують роль вузлів управління. Якщо у вас немає кластера, ви можете створити його, за допомогою minikube або використовувати одну з цих пісочниць:

• iximiuz Labs
• Killercoda
• KodeKloud

Для перевірки версії введіть kubectl version.

• Переконайтесь, що адміністратор вашого кластера налаштував DRA, підключив пристрої та встановив драйвери. Для отримання додаткової інформації дивіться Налаштування DRA в кластері.
• Переконайтесь, що драйвер DRA, розгорнутий у вашому кластері, підтримує метадані пристроїв. Драйвери, які використовують втулок kubelet DRA, активують параметри EnableDeviceMetadata та MetadataVersions під час запуску втулка. Перевірте документацію драйвера для отримання деталей.

Доступ до метаданих ресурсів за допомогою ResourceClaim

Коли ви використовуєте безпосередньо вказаний ResourceClaim для виділення пристроїв, файли метаданих пристроїв зʼявляються всередині контейнера за адресою:

/var/run/kubernetes.io/dra-device-attributes/resourceclaims/<claimName>/<requestName>/<driverName>-metadata.json

1. Перегляньте наступний приклад маніфесту:

   dra/dra-device-metadata-pod.yaml

   apiVersion: resource.k8s.io/v1
   kind: ResourceClaim
   metadata:
     name: gpu-claim
   spec:
     devices:
       requests:
       - name: gpu
         exactly:
           deviceClassName: gpu.example.com
   ---
   apiVersion: v1
   kind: Pod
   metadata:
     name: gpu-metadata-reader
   spec:
     resourceClaims:
     - name: my-gpu
       resourceClaimName: gpu-claim
     containers:
     - name: workload
       image: ubuntu:24.04
       resources:
         claims:
         - name: my-gpu
           request: gpu
       command:
       - sh
       - -c
       - |
         echo "=== DRA device metadata ==="
         find /var/run/kubernetes.io/dra-device-attributes -name '*-metadata.json' -print -exec cat {} \;
         sleep 3600
     restartPolicy: Never
   

   Цей маніфест створює ResourceClaim з назвою gpu-claim, який запитує пристрій з DeviceClass gpu.example.com, та Pod, який читає метадані пристрою.

2. Створіть ResourceClaim та Pod:

   kubectl apply -f https://k8s.io/examples/dra/dra-device-metadata-pod.yaml
   

3. Після запуску Podʼа перегляньте журнали контейнера, щоб побачити метадані:

   kubectl logs gpu-metadata-reader
   

   Вивід буде схожий на:

   === DRA device metadata ===
   /var/run/kubernetes.io/dra-device-attributes/resourceclaims/gpu-claim/gpu/gpu.example.com-metadata.json
   {
     "kind": "DeviceMetadata",
     "apiVersion": "metadata.resource.k8s.io/v1alpha1",
     ...
   }
   

4. Щоб переглянути повний файл метаданих, виконайте команду exec у контейнері:

   kubectl exec gpu-metadata-reader -- \
     cat /var/run/kubernetes.io/dra-device-attributes/resourceclaims/gpu-claim/gpu/gpu.example.com-metadata.json
   

   Вивід буде JSON-обʼєктом, що містить атрибути пристрою, такі як модель, версія драйвера та UUID пристрою. Дивіться схему метаданих для деталей структури JSON.

Доступ до метаданих ресурсів за допомогою ResourceClaimTemplate

Коли ви використовуєте ResourceClaimTemplate, Kubernetes генерує ResourceClaim для кожного Podʼа. Оскільки згенерована назва заявки непередбачувана, файли метаданих зʼявляються за шляхом, який використовує імʼя посилання на заявку Podʼа:

/var/run/kubernetes.io/dra-device-attributes/resourceclaimtemplates/<podClaimName>/<requestName>/<driverName>-metadata.json

Поле <podClaimName> відповідає полю name у записі spec.resourceClaims[] Podʼа. JSON-метадані також включають поле podClaimName, яке фіксує це зіставлення.

1. Перегляньте наступний приклад маніфесту:

   dra/dra-device-metadata-template-pod.yaml

   apiVersion: resource.k8s.io/v1
   kind: ResourceClaimTemplate
   metadata:
     name: gpu-claim-template
   spec:
     spec:
       devices:
         requests:
         - name: gpu
           exactly:
             deviceClassName: gpu.example.com
   ---
   apiVersion: v1
   kind: Pod
   metadata:
     name: gpu-metadata-template-reader
   spec:
     resourceClaims:
     - name: my-gpu
       resourceClaimTemplateName: gpu-claim-template
     containers:
     - name: workload
       image: ubuntu:24.04
       resources:
         claims:
         - name: my-gpu
           request: gpu
       command:
       - sh
       - -c
       - |
         echo "=== DRA device metadata (from template) ==="
         find /var/run/kubernetes.io/dra-device-attributes -name '*-metadata.json' -print -exec cat {} \;
         sleep 3600
     restartPolicy: Never
   

   Цей маніфест створює ResourceClaimTemplate та Pod. Кожен Pod отримує власний згенерований ResourceClaim. Шлях до метаданих використовує імʼя посилання на заявку Podʼа my-gpu.

2. Створіть ResourceClaimTemplate та Pod:

   kubectl apply -f https://k8s.io/examples/dra/dra-device-metadata-template-pod.yaml
   

3. Після запуску Podʼа перегляньте метадані:

   kubectl exec gpu-metadata-template-reader -- \
     cat /var/run/kubernetes.io/dra-device-attributes/resourceclaimtemplates/my-gpu/gpu/gpu.example.com-metadata.json
   

Читання метаданих у вашому застосунку

Go застосунки

Пакунок k8s.io/dynamic-resource-allocation/devicemetadata надає готові функції для читання файлів метаданих. Ці функції автоматично обробляють узгодження версій, декодують потік метаданих і перетворюють його на внутрішні типи, щоб ваш код працював з різними версіями схеми без ручної перевірки версій.

Для безпосередньо вказаної ResourceClaim:

import "k8s.io/dynamic-resource-allocation/devicemetadata"

dm, err := devicemetadata.ReadResourceClaimMetadata("gpu-claim", "gpu")

Для заявки, створеної з шаблону, (використовуючи імʼя посилання на заявку Pod):

dm, err := devicemetadata.ReadResourceClaimTemplateMetadata("my-gpu", "gpu")

Якщо ви знаєте конкретне імʼя драйвера, ви можете прочитати файл метаданих одного драйвера:

dm, err := devicemetadata.ReadResourceClaimMetadataWithDriverName("gpu.example.com", "gpu-claim", "gpu")

Отриманий *metadata.DeviceMetadata містить метадані заявки, запити та атрибути кожного пристрою.

Застосунки іншими мовами можуть безпосередньо читати JSON-файл і перевіряти поле apiVersion, щоб визначити версію схеми перед розбором.

Очищення

Видаліть створені ресурси:

kubectl delete -f https://k8s.io/examples/dra/dra-device-metadata-pod.yaml
kubectl delete -f https://k8s.io/examples/dra/dra-device-metadata-template-pod.yaml

Що далі

• Дізнайтеся більше про метадані пристроїв DRA
• Призначення пристроїв робочим навантаженням за допомогою DRA
• Для отримання додаткової інформації про дизайн див. KEP-5304.