ResourceClaim v1alpha3

ResourceClaim описывает запрос на доступ к ресурсам в кластере для использования рабочими нагрузками.

apiVersion: resource.k8s.io/v1alpha3

import "k8s.io/api/resource/v1alpha3"

ResourceClaim

ResourceClaim описывает запрос на доступ к ресурсам в кластере для использования рабочими нагрузками. Например, если рабочей нагрузке нужен ускоритель с определёнными свойствами, то именно так формулируется этот запрос. Раздел статуса отслеживает, удовлетворён ли этот запрос и какие конкретные ресурсы были выделены.

Это тип альфа-версии и требует включения шлюза функций DynamicResourceAllocation.

apiVersion: resource.k8s.io/v1alpha3
kind: ResourceClaim
metadata (ObjectMeta)

Стандартные метаданные объекта
spec (ResourceClaimSpec), обязательно

Spec описывает запрашиваемое и как его настроить. Спецификация неизменяема.
status (ResourceClaimStatus)

Статус описывает, готов ли к использованию запрос и что было выделено.

ResourceClaimSpec

ResourceClaimSpec определяет, что запрашивается в ResourceClaim и как его настроить.

controller (строка)

Controller — это имя драйвера DRA, который должен обрабатывать выделение этого запроса. Если пусто, выделение обрабатывается планировщиком при планировании под.

Должен быть DNS-поддоменом и должен заканчиваться DNS-доменом, принадлежащим поставщику драйвера.

Это поле alpha и требует включения функции DRAControlPlaneController.
devices (DeviceClaim)

Devices определяет, как запрашивать устройства.

DeviceClaim определяет, как запрашивать устройства с помощью ResourceClaim.
- devices.config ([]DeviceClaimConfiguration)
  
  Атомарно: будет заменено во время слияния
  
  Это поле содержит конфигурацию для нескольких потенциальных драйверов, которые могут удовлетворить запросы в этом запросе. Оно игнорируется при выделении запроса.
  
  DeviceClaimConfiguration используется для параметров конфигурации в DeviceClaim.
  - devices.config.opaque (OpaqueDeviceConfiguration)
    
    Opaque предоставляет параметры конфигурации, специфичные для драйвера.
    
    OpaqueDeviceConfiguration содержит параметры конфигурации для драйвера в формате, определенном поставщиком драйвера.
    - devices.config.opaque.driver (строка), обязательно
      
      Driver используется для определения того, какой плагин kubelet должен получить эти параметры конфигурации.
      
      Политика приема, предоставленная разработчиком драйвера, может использовать это, чтобы решить, нужно ли ее проверять.
      
      Должен быть DNS-поддоменом и должен заканчиваться DNS-доменом, принадлежащим поставщику драйвера.
    - devices.config.opaque.parameters (RawExtension), обязательно
      
      Parameters могут содержать произвольные данные. Ответственность за обработку проверки и версионирования лежит на разработчике драйвера. Как правило, это включает самоидентификацию и версию ("kind" + "apiVersion" для типов Kubernetes), с преобразованием между различными версиями.
      
      *RawExtension используется для хранения расширений во внешних версиях.
      
      Чтобы использовать это, создайте поле, у которого RawExtension является его типом во внешней, версионированной структуре, а Object — в внутренней структуре. Вам также необходимо зарегистрировать ваши различные типы плагинов.
      
      // Внутренний пакет:
```
type MyAPIObject struct {
	runtime.TypeMeta `json:",inline"`
	MyPlugin runtime.Object `json:"myPlugin"`
}

type PluginA struct {
	AOption string `json:"aOption"`
}
```
      // Внешний пакет:
```
type MyAPIObject struct {
	runtime.TypeMeta `json:",inline"`
	MyPlugin runtime.RawExtension `json:"myPlugin"`
}

type PluginA struct {
	AOption string `json:"aOption"`
}
```
      // В сети, JSON будет выглядеть примерно так:
```
{
	"kind":"MyAPIObject",
	"apiVersion":"v1",
	"myPlugin": {
		"kind":"PluginA",
		"aOption":"foo",
	},
}
```
      Итак, что происходит? Прежде всего, decode использует json или yaml для разархивирования сериализованных данных в ваш внешний MyAPIObject. Это приводит к тому, что необработанный JSON сохраняется, но не распаковывается. Следующим шагом является копирование (используя pkg/conversion) во внутреннюю структуру. В пакете runtime, DefaultScheme установлены функции преобразования, которые распакуют JSON, хранящийся в RawExtension, преобразуют его в правильный тип объекта и сохранят его в Object. (TODO: В случае, если объект неизвестного типа, будет создан и сохранён объект runtime.Unknown.)*
  - devices.config.requests ([]string)
    
    Атомарно: будет заменено во время слияния
    
    Requests перечисляет имена запросов, к которым применяется конфигурация. Если пусто, она применяется ко всем запросам.
- devices.constraints ([]DeviceConstraint)
  
  Атомарно: будет заменено во время слияния
  
  Эти ограничения должны выполняться набором устройств, выделенных для запроса.
  
  DeviceConstraint должен иметь ровно одно поле, установленное помимо Requests.
  - devices.constraints.matchAttribute (строка)
    
    MatchAttribute требует, чтобы у всех устройств в вопросе был этот атрибут, а его тип и значение были одинаковыми для этих устройств.
    
    Например, если вы указали «dra.example.com/numa» (гипотетический пример!), то будут выбраны только устройства в одном узле NUMA. Устройство, у которого нет этого атрибута, не будет выбрано. Все устройства должны использовать значение одного и того же типа для этого атрибута, поскольку это часть его спецификации, но если одно устройство этого не сделает, то оно также не будет выбрано.
    
    Должен включать квалификатор домена.
  - devices.constraints.requests ([]string)
    
    Атомарно: будет заменено во время слияния
    
    Requests — это список одного или нескольких запросов в этом запросе, которые должны удовлетворять этому ограничению. Если один запрос удовлетворяется несколькими устройствами, все устройства должны удовлетворять ограничению. Если это не указано, это ограничение применяется ко всем запросам в этом запросе.
- devices.requests ([]DeviceRequest)
  
  Атомарно: будет заменено во время слияния
  
  Requests представляют собой отдельные запросы на выделение различных устройств, которые должны быть удовлетворены. Если пусто, ничего не нужно выделять.
  
  *DeviceRequest — это запрос на устройства, необходимые для запроса. Как правило, это запрос на один ресурс, такой как устройство, но также может запрашивать несколько одинаковых устройств.
  
  В настоящее время требуется DeviceClassName. Клиенты должны проверить, что он действительно установлен. Его отсутствие указывает на то, что что-то изменилось таким образом, что клиент пока не поддерживает, в таком случае он должен отказаться от обработки запроса.*
  - devices.requests.deviceClassName (строка), обязательно
    
    DeviceClassName ссылается на определенный DeviceClass, который может определять дополнительную конфигурацию и селекторы, которые будут унаследованы этим запросом.
    
    Необходим класс. Какие классы доступны, зависит от кластера.
    
    Администраторы могут использовать это для ограничения того, какие устройства могут быть запрошены, устанавливая классы только с селекторами для разрешенных устройств. Если пользователи могут запрашивать все, без ограничений, администраторы могут создать пустой DeviceClass для пользователей для ссылки.
  - devices.requests.name (строка), обязательно
    
    Name может быть использован для ссылки на этот запрос в записи pod.spec.containers[].resources.claims и в ограничении запроса.
    
    Должен быть DNS-меткой.
  - devices.requests.adminAccess (булево)
    
    AdminAccess указывает, что это запрос на административный доступ к устройству(ам). Ожидается, что запросы с AdminAccess будут использоваться для мониторинга или других сервисов управления устройством. Они игнорируют все обычные запросы на устройство с точки зрения режимов доступа и любых распределений ресурсов.
  - devices.requests.allocationMode (строка)
    
    AllocationMode и связанные с ним поля определяют, как устройства выделяются для удовлетворения этого запроса. Поддерживаемые значения:
    - ExactCount: Этот запрос на определенное количество устройств. Это значение по умолчанию. Точное количество указано в поле count.
    - All: Этот запрос на все соответствующие устройства в пуле. Выделение завершится ошибкой, если некоторые устройства уже выделены, если не запрошен adminAccess.
    Если AllocationMode не указан, режим по умолчанию — ExactCount. Если режим ExactCount, а count не указан, значение по умолчанию — один. Все остальные запросы должны указать это поле.
    
    В будущем могут быть добавлены другие режимы. Клиенты должны отклонять запросы с неизвестными режимами.
  - devices.requests.count (int64)
    
    Count используется только тогда, когда режим count равен «ExactCount». Должно быть больше нуля. Если AllocationMode — ExactCount, а это поле не указано, значение по умолчанию — один.
  - devices.requests.selectors ([]DeviceSelector)
    
    Атомарно: будет заменено во время слияния
    
    Селекторы определяют критерии, которые должны быть удовлетворены конкретным устройством, чтобы это устройство рассматривалось для этого запроса. Все селекторы должны быть выполнены, чтобы устройство рассматривалось.
    
    DeviceSelector должен иметь ровно одно поле, установленное.
    - devices.requests.selectors.cel (CELDeviceSelector)
      
      CEL содержит выражение CEL для выбора устройства.
      
      CELDeviceSelector содержит выражение CEL для выбора устройства.
      - devices.requests.selectors.cel.expression (строка), обязательно
        
        Expression — это выражение CEL, которое оценивает одно устройство. Оно должно оцениваться как true, когда рассматриваемое устройство удовлетворяет желаемым критериям, и как false, когда не удовлетворяет. Любой другой результат — это ошибка, и выделение устройств прекращается.
        
        Входным значением выражения является объект с именем «device», который содержит следующие свойства:
        
        driver (строка): имя драйвера, который определяет это устройство.
        
        attributes (map[string]object): атрибуты устройства, сгруппированные по префиксу (например, device.attributes["dra.example.com"] оценивается как объект со всеми атрибутами, которые были префиксрованы «dra.example.com»).
        
        capacity (map[string]object): мощности устройства, сгруппированные по префиксу.
        
        Пример: Рассмотрим устройство с driver="dra.example.com", которое предоставляет два атрибута с именем "model" и "ext.example.com/family" и одну мощность с именем "modules". Этот вход в выражение будет иметь следующие поля:
        
        device.driver device.attributes["dra.example.com"].model device.attributes["ext.example.com"].family device.capacity["dra.example.com"].modules
        
        Поле device.driver может использоваться для проверки конкретного драйвера, либо как предварительное условие высокого уровня (т.е. вы хотите рассматривать только устройства от этого драйвера), либо как часть многочленного выражения, которое должно учитывать устройства разных драйверов.
        
        Тип значения каждого атрибута определяется определением устройства, и пользователи, которые пишут эти выражения, должны обратиться к документации по своим конкретным драйверам. Тип значения каждой мощности — Quantity.
        
        Если используется неизвестный префикс в качестве поиска в device.attributes или device.capacity, будет возвращена пустая карта. Любая ссылка на неизвестное поле приведет к ошибке оценки и прекращению выделения.
        
        Надежное выражение должно проверять существование атрибутов перед ссылкой на них.
        
        Для удобства использования функция cel.bind() включена и может использоваться для упрощения выражений, которые обращаются к нескольким атрибутам с одним и тем же доменом. Например:
        
        cel.bind(dra, device.attributes["dra.example.com"], dra.someBool && dra.anotherBool)

ResourceClaimStatus

ResourceClaimStatus отслеживает, был ли ресурс выделен и каков был результат этого.

распределение (AllocationResult)

Распределение устанавливается после успешного распределения требования.

AllocationResult содержит атрибуты распределенного ресурса.
- распределение.контроллер (строка)
  
  Контроллер — это имя драйвера DRA, который обрабатывал распределение. Этот драйвер также отвечает за освобождение требования. Он пустой, когда требование может быть освобождено без участия драйвера.
  
  Драйвер может распределять устройства, предоставленные другими драйверами, поэтому имя драйвера здесь может отличаться от имен драйверов, указанных в результатах.
  
  Это поле в стадии альфа-тестирования и требует активации функции DRAControlPlaneController.
- распределение.устройства (DeviceAllocationResult)
  
  Устройства — это результат распределения устройств.
  
  DeviceAllocationResult — это результат распределения устройств.
  - распределение.устройства.конфигурация ([]DeviceAllocationConfiguration)
    
    Атомарно: будет заменено во время слияния
    
    Это поле представляет собой комбинацию всех параметров конфигурации требования и класса. Драйверы могут различать их на основе флага.
    
    Это включает параметры конфигурации для драйверов, у которых нет распределенных устройств в результате, поскольку от драйверов зависит, какие параметры конфигурации они поддерживают. Они могут игнорировать неизвестные параметры конфигурации без ошибок.
    
    DeviceAllocationConfiguration встраивается в AllocationResult.
    - распределение.устройства.конфигурация.источник (строка), обязательно
      
      Источник указывает, получена ли конфигурация из класса и, следовательно, не является чем-то, что обычный пользователь мог бы установить, или из требования.
    - распределение.устройства.конфигурация.неопределённые (OpaqueDeviceConfiguration)
      
      Неопределённые параметры содержат параметры конфигурации, специфичные для драйвера.
      
      OpaqueDeviceConfiguration содержит параметры конфигурации драйвера в формате, определённом поставщиком драйвера.
      - распределение.устройства.конфигурация.неопределённые.драйвер (строка), обязательно
        
        Драйвер используется для определения того, какой плагин kubelet должен получить эти параметры конфигурации.
        
        Политика допуска, предоставленная разработчиком драйвера, может использовать это, чтобы определить, нужно ли её проверять.
        
        Должен быть доменным поддоменом DNS и должен оканчиваться доменным именем DNS, принадлежащим поставщику драйвера.
      - распределение.устройства.конфигурация.неопределённые.параметры (RawExtension), обязательно
        
        Параметры могут содержать произвольные данные. Ответственность за валидацию и версионирование лежит на разработчике драйвера. Обычно это включает самоидентификацию и версию («kind» + «apiVersion» для типов Kubernetes), с преобразованием между различными версиями.
        
        *RawExtension используется для хранения расширений во внешних версиях.
        
        Для использования этого, создайте поле, которое имеет RawExtension в качестве своего типа во внешней версии, и Object в вашей внутренней структуре. Вам также необходимо зарегистрировать ваши различные типы плагинов.
        
        // Внутренний пакет:
        
        type MyAPIObject struct { runtime.TypeMeta json:",inline" MyPlugin runtime.Object json:"myPlugin" }
        
        type PluginA struct { AOption string json:"aOption" }
        
        // Внешний пакет:
        
        type MyAPIObject struct { runtime.TypeMeta json:",inline" MyPlugin runtime.RawExtension json:"myPlugin" }
        
        type PluginA struct { AOption string json:"aOption" }
        
        // В сети, JSON будет выглядеть примерно так:
        
        { "kind":"MyAPIObject", "apiVersion":"v1", "myPlugin": { "kind":"PluginA", "aOption":"foo", }, }
        
        Итак, что происходит? Сначала декодирование использует json или yaml для распаковки сериализованных данных в ваш внешний MyAPIObject. Это приводит к тому, что сырой JSON хранится, но не распаковывается. Следующий шаг — копирование (с помощью pkg/conversion) во внутреннюю структуру. В пакете runtime установлены функции преобразования в DefaultScheme, которые распакуют JSON, хранящийся в RawExtension, преобразуют его в правильный тип объекта и сохранят его в Object. (TODO: В случае, если объект неизвестного типа, будет создан и сохранён объект runtime.Unknown.)*
    - распределение.устройства.конфигурация.запросы ([]строка)
      
      Атомарно: будет заменено во время слияния
      
      Запросы перечисляют имена запросов, к которым применяется конфигурация. Если пусто, она применяется ко всем запросам.
  - распределение.устройства.результаты ([]DeviceRequestAllocationResult)
    
    Атомарно: будет заменено во время слияния
    
    Результаты перечисляют все распределенные устройства.
    
    DeviceRequestAllocationResult содержит результат распределения для одного запроса.
    - распределение.устройства.результаты.устройство (строка), обязательно
      
      Устройство ссылается на один экземпляр устройства по его имени в пуле ресурсов драйвера. Должно быть меткой DNS.
    - распределение.устройства.результаты.драйвер (строка), обязательно
      
      Драйвер указывает имя драйвера DRA, чей плагин kubelet должен быть вызван для обработки распределения, как только требование потребуется на узле.
      
      Должен быть доменным поддоменом DNS и должен оканчиваться доменным именем DNS, принадлежащим поставщику драйвера.
    - распределение.устройства.результаты.пул (строка), обязательно
      
      Это имя вместе с именем драйвера и полем имени устройства идентифицирует, какое устройство было распределено (\<driver name>/\<pool name>/\<device name>).
      
      Длина не должна превышать 253 символов и может содержать один или несколько поддоменов DNS, разделенных слешами.
    - распределение.устройства.результаты.запрос (строка), обязательно
      
      Запрос — это имя запроса в требовании, которое привело к распределению этого устройства. Для каждого запроса может быть распределено несколько устройств.
- распределение.селектор_узлов (NodeSelector)
  
  NodeSelector определяет, где доступны распределенные ресурсы. Если не задано, они доступны везде.
  
  Селектор узлов представляет собой объединение результатов одного или нескольких запросов меток по набору узлов; то есть, он представляет собой ИЛИ селекторов, представленных терминами селектора узлов.
  - распределение.селектор_узлов.термины_селектора_узлов ([]NodeSelectorTerm), обязательно
    
    Атомарно: будет заменено во время слияния
    
    Обязательно. Список терминов селектора узлов. Термины — ИЛИ.
    
    Пустой или нулевой термин селектора узлов не соответствует ни одному объекту. Требования к ним — И. Тип TopologySelectorTerm реализует подмножество NodeSelectorTerm.
    - распределение.селектор_узлов.термины_селектора_узлов.выражения_сопоставления ([]NodeSelectorRequirement)
      
      Атомарно: будет заменено во время слияния
      
      Список требований к селектору узлов по меткам узлов.
    - распределение.селектор_узлов.термины_селектора_узлов.соответствия_полям ([]NodeSelectorRequirement)
      
      Атомарно: будет заменено во время слияния
      
      Список требований к селектору узлов по полям узлов.
запрос_освобождения (булево)

Указывает, что требование должно быть освобождено. Пока это установлено, к ReservedFor нельзя добавлять новых потребителей.

Используется только в том случае, если требование нужно освободить драйверу DRA. Этот драйвер должен затем освободить это требование и сбросить поле вместе с очисткой поля Распределение.

Это поле в стадии альфа-тестирования и требует активации функции DRAControlPlaneController.
зарезервировано_для ([]ResourceClaimConsumerReference)

Стратегия исправления: слияние по ключу uid

Карта: уникальные значения по ключу uid будут сохранены во время слияния

Зарезервировано_для указывает, какие сущности в настоящее время могут использовать требование. Контейнер Pod, который ссылается на ResourceClaim, который не зарезервирован для этого контейнера Pod, не будет запущен. Требование, которое используется или может использоваться, потому что оно зарезервировано, не должно быть освобождено.

В кластере с несколькими экземплярами планировщиков два контейнера Pod могут быть запланированы одновременно разными планировщиками. Когда они ссылаются на один и тот же ResourceClaim, который уже достиг максимального числа потребителей, только один контейнер Pod может быть запланирован.

Оба планировщика пытаются добавить свой контейнер Pod в поле claim.status.reservedFor, но только обновление, которое первым достигает API-сервера, сохраняется. Другое терпит неудачу с ошибкой, и планировщик, который его выдал, знает, что должен вернуть контейнер Pod в очередь, ожидая, пока ResourceClaim снова станет доступным.

Может быть не более 32 таких резервирований. Это может быть увеличено в будущем, но не уменьшено.

ResourceClaimConsumerReference содержит достаточную информацию, чтобы позволить вам найти потребителя ResourceClaim. Пользователь должен быть ресурсом в том же пространстве имен, что и ResourceClaim.
- зарезервировано_для.имя (строка), обязательно
  
  Имя — это имя ссылаемого ресурса.
- зарезервировано_для.ресурс (строка), обязательно
  
  Ресурс — это тип ссылаемого ресурса, например «pods».
- зарезервировано_для.uid (строка), обязательно
  
  UID идентифицирует точно один экземпляр ресурса.
- зарезервировано_для.apiGroup (строка)
  
  APIGroup — это группа для ссылаемого ресурса. Она пуста для основного API. Это соответствует группе в APIVersion, которая используется при создании ресурсов.

Список_требований_ресурсов

ResourceClaimList — это набор требований.

apiVersion: resource.k8s.io/v1alpha3
kind: ResourceClaimList
metadata (ListMeta)

Стандартные метаданные списка
items ([]ResourceClaim), обязательно

Items — это список требований к ресурсам.

© 2024 The Kubernetes Authors | Documentation Distributed under CC BY 4.0
Copyright © 2024 The Linux Foundation ®. All rights reserved.
https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/resource-claim-v1alpha3/