Источники данных — механизм DDP, который позволяет синхронизировать информацию из внешних инфраструктурных систем (например, GitLab, либо Kubernetes) и преобразовывать её в параметры той или иной сущности.

Также источники данных позволяют:

  • Создавать новые сущности.
  • Удалять сущности, которые были удалены из внешних инфраструктурных систем.
  • Создавать связи между сущностями.

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

Типы источников данных

  • Встроенные (BuiltIn) — источники данных, для которых логика опроса инфраструктурных систем поставляется в рамках DDP.
  • Вебхуки (Webhooks) — механизм приёма данных во входящих POST-запросах от внешних систем, подробнее в разделе «Вебхуки».

Параметры источников данных

Некоторые типы источников данных поддерживают настраиваемые параметры, позволяющие дополнительно конфигурировать их поведение. Подробная информация о параметрах для каждого типа источника данных приведена в разделе «Типы источников данных».

Правила источников данных

Для каждого источника данных администратором системы настраиваются правила, по которым будут:

  • Создаваться новые сущности.
  • Создаваться новые связи.
  • Производиться поиск соответствующих сущностей для обновления их параметров.
  • Производиться поиск сущностей для удаления.

Правила описываются в формате "source": "target". Для описания правил используется синтаксис Go template.

В DDP реализованы 5 типов правил:

  • Правила фильтрации (filter rules).
  • Правила создания (create rules).
  • Правила сопоставления (match rules).
  • Правила обновления (update rules).
  • Правила создания связей (create relation rules).

Правила фильтрации

После получения данных из внешней системы применяются правила фильтрации: каждое следующее правило обрабатывает уже отфильтрованный набор элементов.

В диалоге редактирования источника данных откройте вкладку «Правила». В блоке «Правила фильтрации» для каждого правила задаются три поля:

  1. Действие — оставить только элементы, у которых значение выбранного поля совпало с регулярным выражением (вариант «Оставить только совпадения»), или убрать из набора такие элементы (вариант «Убрать совпадения»).
  2. Источник — путь к полю в структуре данных в формате Go template.
  3. Условие — регулярное выражение для проверки значения этого поля.

Если правил нет, дальше по цепочке проходят все полученные элементы. Если действие не выбрано, подставляется вариант «Оставить только совпадения».

Чтобы оставить только записи с нужным значением поля (например, чтобы в поле name значение начиналось с first), выберите «Оставить только совпадения». В источнике укажите выражение для этого поля, например {{ .name }}, в условии — регулярное выражение для подходящих значений. Чтобы не обрабатывать записи, которые совпадают с шаблоном, выберите «Убрать совпадения» и задайте шаблон в условии.

Если в условии указано невалидное регулярное выражение, правило не выполняется; ошибка попадает в лог синхронизации и обработка источника данных продолжается.

Правила создания

Правила создания определяют, каким образом информация, полученная от бэкенда источника данных, будет использоваться при создании новых сущностей.

Например, при следующей спецификации одного из ресурсов внешней инфраструктурной системы, полученного через источник данных:

...
metadata:
  name: example
  namespace: default
...

и следующих правилах создания:

"match": [
  {
    "source": "{{ .metadata.name }}",
    "target": "Name"
  },
  {
    "source": "{{ .metadata.namespace }}-{{ .metadata.name }}",
    "target": "Slug"
  }
]

после синхронизации источника данных будет создана сущность, название (Name) которой будет иметь значение example, а идентификатор (Slug) — значение default-example.

Правила сопоставления

Правила сопоставления определяют, каким образом производить поиск существующих, либо только что созданных источником данных сущностей для обновления их параметров.

Правила обновления

Правила обновления определяют, какие параметры сущности автоматически заполняются на основе спецификации соответствующего ресурса из внешней системы. Сущность, параметры которой необходимо заполнить, определяется на основе правил сопоставления.

Импорт из спецификации

Экспериментальный функционал

С использованием механизма импорта, правила обновления и параметры обновляемого ресурса можно сформировать автоматически по JSON, YAML или OpenAPI-спецификации данных.

Настройка в интерфейсе
  1. На вкладке «Основная информация» выберите ресурс, к которому будет привязан источник данных.
  2. В диалоге редактирования источника данных откройте вкладку «Правила».
  3. В блоке «Правила обновления» нажмите кнопку «Импортировать из спецификации».
Шаги по настройке
  1. Загрузка данных — выберите формат (автоопределение, JSON, YAML, OpenAPI 3.x, Swagger 2.0) и вставьте содержимое спецификации в поле «Данные». Если в спецификации несколько схем, на следующем шаге в поле «Выберите схему для импорта» можно выбрать схему для маппинга.
  2. Настройка маппинга — в таблице отображаются столбцы «Путь в данных», «Тип в источнике», «Идентификатор параметра», «Название параметра», «Тип параметра». Можно редактировать идентификатор, название и тип параметра, отметить галочками строки для применения. Строки, для которых в ресурсе уже есть параметр с таким идентификатором или названием, помечаются меткой «Существует».
  3. Применение — нажмите «Применить»: в блок «Правила обновления» источника данных добавятся сформированные правила. Новые параметры ресурса будут созданы при сохранении источника данных.
Поведение системы при импорте
  1. Автосоздание параметров ресурса — для полей спецификации, по которым в ресурсе ещё нет параметра, предлагаются новые параметры; они добавляются в ресурс при сохранении источника данных.
  2. Автозаполнение правил обновления — по каждому выбранному полю создаётся правило: источник задаётся выражением Go template по пути в данных (например, {{ .metadata.name }}), параметр — идентификатор параметра ресурса. После нажатия «Применить» эти правила появляются в блоке «Правила обновления» на вкладке «Правила» источника данных.
Поддерживаемые форматы

Автоопределение, JSON, YAML, OpenAPI 3.x, Swagger 2.0. Типы из спецификации (string, integer, array, object и т.д.) сопоставляются с типами параметров DDP; при необходимости тип можно изменить на шаге «Настройка маппинга».

Правила создания связей

Правила создания связей определяют, какие связи создаются для сущности, соответствующей правилам сопоставления. При задании правил создания связей заполняется:

  • Связь ресурса.
  • Поле из спецификации ресурса внешней инфраструктурной системы, на основании которого выполняется поиск сущности для установления связи.

Например, при следующей спецификации одного из ресурсов внешней инфраструктурной системы, полученного через источник данных:

...
metadata:
  name: example
  namespace: default
...

и следующем правиле создания связей:

"createRelations": [
  {
    "resourceRelationUuid": "<12345678-1234-5678-1234-567812345678>",
    "parentEntitySlug": "{{ .metadata.namespace }}",
    "childEntitySlug": ""
  }
]

будет:

  • Если указан идентификатор родительской сущности (parentEntitySlug), поиск выполняется только среди сущностей родительского ресурса.

  • Если указан идентификатор дочерней сущности (childEntitySlug), поиск выполняется только среди сущностей дочернего ресурса.

  • В рамках одного правила необходимо указывать либо родительский, либо дочерний идентификатор.

  • Если заданы оба идентификатора, поиск выполняется только по родительскому ресурсу.

Если в родительском ресурсе существует сущность с идентификатором default, создаётся связь между этой сущностью и сущностью ресурса, к которому привязан источник данных и которая соответствует правилам сопоставления.

Синхронизация

Каждый источник данных имеет несколько параметров настройки синхронизации:

  • Периодическая синхронизация — включение или выключение периодической синхронизации.
  • Периодичность запуска — cron-выражение, определяющее интервал запуска периодической синхронизации.

При включенном параметре «Периодическая синхронизация» источник данных будет автоматически обновлять информацию из внешних инфраструктурных систем с интервалом, определенным в параметре «Периодичность запуска».

Также каждый источник данных может быть синхронизирован вручную в любой момент времени через веб-интерфейс (пункт «Синхронизировать» в меню источника данных), либо через API.

Удаление сущностей

Каждый источник данных имеет несколько параметров удаления сущностей:

  • Удаление несуществующих сущностей.
  • Удаление только сущностей, созданных этим источником данных.

При включении параметра «Удаление несуществующих сущностей» источник данных будет сравнивать список ресурсов, полученных из внешней инфраструктурной системы и список существующих сущностей ресурса. При обнаружении в DDP сущностей, которые отсутствуют в списке полученных, они будут удалены из DDP.

При включении параметра «Удаление только сущностей, созданных этим источником данных» источник данных будет дополнительно сравнивать, каким образом была создана сущность, которую необходимо удалить. Если сущность была создана этим источником данных, то она будет удалена, если нет, то источник данных перейдет к обработке следующей сущности в списке без удаления текущей.

Поиск создателя (origin) сущности производится по двум полям в спецификации сущности:

{
    "origin": {
        "type": "<datasource | manual | webhook",
        "uuid": "12345678-1234-5678-1234-567812345678>"
    }
}

Логирование запусков

Для каждого запуска источника данных создается запись в БД, содержащая полный лог выполнения. Максимальное количество подобных записей регулируется параметром «максимальное количество записей» в конфигурации источника данных. При достижении максимального количества старые записи будут удаляться.

Параметр datasources.logging.enabled в конфигурационном файле DDP позволяет выводить в stdout, либо скрывать логи синхронизации источника данных. При значении true логи будут выводиться в stdout, при значении false логи выводиться не будут.

Записи в БД с полным логом запуска источника данных создаются независимо от значения параметра datasources.logging.enabled.

Системная учетная запись

При настройке источника данных необходимо выбрать системную учетную запись для запуска синхронизации.

Реквизиты данной учетной записи будут использоваться источником данных для доступа к опрашиваемой инфраструктурной системе.

Помимо системной учетной записи необходимо указание того, какие ее реквизиты будут использованы при запуске источника данных. Для этого в секции «Безопасность / Учетные данные» добавляются новые учетные данные с определенным идентификатором.

Значение данного идентификатора может быть подставлено в конфигурацию источника данных с использованием синтаксиса Go template.

Например, если в заголовке для источника данных необходимо передать секретное значение с идентификатором token, то оно может быть указано в следующем виде:

{{ .credentials.token }}