Что такое определения пользовательских ресурсов Kubernetes (CRD)?

Пользовательские определения ресурсов (CRD) — это расширения API Kubernetes, которые могут определять новые типы объектов. Pods, ReplicaSets, ConfigMaps и Ingresses являются примерами распространенных встроенных ресурсов. CRD позволяют добавлять в этот список совершенно новые типы, а затем управлять ими с помощью знакомых инструментов Kubernetes, таких как Kubectl.

Механизм CRD намеренно абстрактен и может использоваться множеством способов для хранения данных и создания новых функций. Вы найдете пользовательские ресурсы во многих популярных инструментах сообщества: Cert-Manager определяет объекты, которые представляют SSL-сертификаты и эмитентов, а Helm представляет диаграммы как свои собственные CRD.

Что делает ресурс?

Ресурсы Kubernetes определяют типы данных, которые вы можете хранить в своем кластере. Доступ к ним осуществляется через API Kubernetes, который предоставляет конечные точки для создания, перечисления и изменения элементов в каждом типе ресурсов.

Вы можете добавить пользовательские ресурсы для хранения ваших собственных произвольных данных внутри вашего кластера. Создаваемые вами элементы будут храниться компонентом плоскости управления etcd вместе с экземплярами встроенных ресурсов. Пользовательские ресурсы автоматически отображаются через API, поэтому вам не нужно настраивать собственные инструменты для создания экземпляров элементов.

CRD по умолчанию действуют как простые структуры данных. Хотя CRD в дикой природе часто ведут себя по-своему, механизм CRD не обеспечивает этого. Пользовательские контроллеры и операторы Kubernetes можно использовать для реализации функций на основе пользовательских ресурсов. Без контроллера элементы CRD всегда будут существовать как статические данные в кластере, с которыми вы можете взаимодействовать через конечные точки CRUD, предоставляемые Kubernetes API.

CRD — это динамические компоненты, которые можно создавать и удалять в любое время. Некоторые типы объектов, включенные в Kubernetes, также реализованы как CRD, что обеспечивает большую модульность в ядре кластера.

Создание CRD

CRD сами по себе являются типом объекта Kubernetes. Вы создаете их так же, как и любой другой ресурс, записывая файл YAML и применяя его к своему кластеру:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: custom-apps.crds.example.com
spec:
  group: crds.example.com
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                app-name:
                  type: string
                app-version:
                  type: string
                release-count:
                  type: integer
  scope: Namespaced
  names:
    plural: custom-apps
    singular: custom-app
    kind: CustomApp

Используйте Kubectl, чтобы добавить CRD CustomApp в свой кластер:

$ kubectl apply -f custom-apps-crd.yaml
customresourcedefinition.apiextensions.k8s.io/custom-apps.crds.example.com created

Файл YAML определяет CRD, который можно использовать для хранения данных о приложениях. Для CRD требуется поле metadata.name и spec.group в точном формате: группа принимает форму субдомена, к которому принадлежит CRD. Тот же субдомен должен быть включен в metadata.name CRD. Значение names.plural добавляется в качестве нового компонента поддомена для создания окончательного metadata.name.

Поле spec.names определяет, как вы будете ссылаться на CRD при использовании Kubernetes API и команд Kubectl. В этом примере вы сможете запускать kubectl get custom-apps и kubectl get custom-app/example-app для взаимодействия с объектами, использующими CRD. Когда вы создаете новый объект в виде файла YAML, вы должны установить kind: CustomApp, чтобы сделать его экземпляром CRD.

CRD настраивается как тип объекта уровня пространства имен с помощью поля scope. Вы можете использовать Cluster в качестве альтернативного значения для этого поля, чтобы создавать объекты, которые существуют на уровне кластера вне любого пространства имен.

Данные, связанные с вашими настраиваемыми объектами, определяются в поле spec.versions.schema.openAPIV3Schema. Каждая указанная «версия» создает новую версию API CRD, на которую вы можете ссылаться с помощью поля apiVersion в ваших YAML-файлах ресурсов. Данные CRD настраиваются с использованием свойств OpenAPI; здесь каждое «настраиваемое приложение» в вашем кластере должно иметь свойства app-name, app-version и release-count, установленные в его YAML. спецификация.

Использование вашего CRD

Подготовка новых конечных точек API CRD может занять несколько минут. Проверьте ход выполнения, получив данные CRD с помощью Kubectl:

$ kubectl describe crd custom-apps.crds.example.com
...
Status:
  Accepted Names:
    Kind:       CustomApp
    List Kind:  CustomAppList
    Plural:     custom-apps
    Singular:   custom-app
  Conditions:
    Last Transition Time:  2022-04-04T13:29:24Z
    Message:               no conflicts found
    Reason:                NoConflicts
    Status:                True
    Type:                  NamesAccepted
    Last Transition Time:  2022-04-04T13:29:24Z
    Message:               the initial names have been accepted
    Reason:                InitialNamesAccepted
    Status:                True
    Type:                  Established
...

CRD готов к использованию, когда вы видите Type: Established в конце вывода команды. Kubernetes будет принимать запросы к конечной точке API CRD. В этом случае базовый URL API будет следующим:

/apis/custom-apps.crds.example.com/v1/namespaces/*/custom-apps/...

Теперь вы можете использовать Kubectl для просмотра объектов, созданных с помощью CRD:

$ kubectl get custom-apps
No resources found in default namespace.

Хотя объектов еще не существует, теперь Kubernetes знает, что у него есть тип ресурса с именем custom-apps.

Чтобы создать объект «настраиваемое приложение», напишите новый файл YAML с kind: CustomApp. Для apiVersion должны быть заданы имя группы и версия API, предоставленные CRD. В разделе spec включите свойства, которые вы определили в схеме CRD.

apiVersion: crds.example.com/v1
kind: CustomApp
metadata:
  name: demo-app-1
spec:
  app-name: demo-app
  app-version: 1.1.0
  release-count: 5

Используйте Kubectl, чтобы добавить объект в свой кластер:

$ kubectl apply -f custom-app.yaml
customapp.crds.example.com/demo-app created

Теперь вы можете получить информацию об объекте, используя знакомые команды Kubectl:

$ kubectl describe custom-app/demo-app-1
Name:         demo-app
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  crds.example.com/v1
Kind:         CustomApp
...
Spec:
  App - Name:       demo-app
  App - Version:    1.1.0
  Release - Count:  5
...
Events:             <none>

У вас есть функционирующий пользовательский ресурс, который теперь хранит некоторые данные внутри вашего кластера Kubernetes. Вы можете удалить CRD, удалив его в Kubectl; это автоматически очистит все объекты, которые его используют.

$ kubectl delete crd custom-apps.crds.example.com
customresourcedefinition.apiextensions.k8s.io "custom-apps.crds.example.com" deleted

Создание декларативных API с помощью CRD

Этот CRD не добавляет никакой функциональности кластеру. Он хранит данные, предоставляет API для взаимодействия с ними, и на него могут ссылаться другие объекты. CRD становятся более мощными, когда они соединены с настраиваемым контроллером, который может взять на себя ответственность за управление ими.

Контроллеры отслеживают ресурсы и предпринимают действия в ответ на их события. Написание контроллера для ваших CRD позволяет превратить их в декларативные API, которые вызывают реальные изменения внутри вашего кластера. Ваши объекты могут представлять желаемое состояние, а не точное текущее состояние.

Cert-Manager использует эту модель для автоматического получения SSL-сертификатов, когда в вашем кластере появляются новые объекты CertificateRequest. В ядре Kubernetes узлы извлекают и запускают образы контейнеров в ответ на появление подов. Контроллеры позволяют привязывать поведение к вашим собственным CRD, поэтому добавление «настраиваемого приложения» может привести к тому, что его конфигурация будет получена из внешней службы. Вы можете начать создавать контроллеры, используя Go SDK для интеграции собственного кода со средой выполнения Kubernetes.

Когда использовать CRD?

CRD лучше всего использовать для обработки данных, которые являются внутренними для вашей организации, команды или проекта. Они предназначены для представления четко определенных схем либо в виде статических значений, либо в виде декларативных API, поддерживаемых пользовательской реализацией контроллера.

Расширенные функции позволяют реализовать процедуры проверки для полей в вашей схеме. Вы также можете использовать финализаторы для обработки удаления объектов и адаптировать систему управления версиями для обработки изменений в ваших определениях CRD.

CRD иногда пересекаются с Kubernetes ConfigMap. Это встроенные объекты для хранения общих данных конфигурации, связанных с вашими приложениями. ConfigMap подходит, когда вы будете использовать значения в определенном месте вашего кластера, например, в поде, который получает доступ к настройкам базы данных как переменные среды, введенные из ConfigMap.

CRD предназначены для использования, когда данные должны быть первоклассными в вашем кластере. Вы можете создавать несколько экземпляров типа ресурса CRD, напрямую взаимодействовать с ними с помощью Kubectl и создавать собственные структурированные схемы, которые помогают пользователям вводить правильные значения. Они могут быть лучшим выбором, когда данные существуют независимо от любого другого элемента в вашем кластере.

Краткое содержание

Определения пользовательских ресурсов Kubernetes (CRD) определяют новые типы объектов, которые можно использовать с Kubernetes API и Kubectl. Каждый CRD получает свой собственный версионный API, имеет структурированную схему и может использоваться для реализации новых функций в кластере при поддержке сопутствующего контроллера.

CRD иногда могут показаться сложными и зарезервированы для сложных ситуаций. Этого не должно быть. Простые CRD для хранения статических значений в вашем кластере легко создать, как показано в примере «пользовательского приложения» выше. Их можно использовать для хранения данных автономного кластера, поэтому они получают первоклассную обработку в Kubernetes.

Также важно понимать, в каких случаях CRD не подходят. Встроенные объекты, такие как ConfigMaps и Secrets, предназначены для поддержки большинства форм конфигурации, которые будут напрямую использоваться модулями вашего приложения. Написание CRD, определяющего схему файла конфигурации вашего приложения, обычно не требуется, и его сложнее поддерживать с течением времени, поскольку вы не получите преимуществ от функций ConfigMap, таких как автоматические последовательные обновления и внедрение переменных среды.