Обзор GitSync

Елена Костюченко

GitSync — это сервис ADO, предназначенный для загрузки DAG Airflow из удаленных Git-репозиториев и их синхронизации. Сервис обеспечивает управление DAG с помощью Git и интегрируется со средой Airflow.

Основные возможности GitSync:

  • Синхронизация репозиториев — клонирование и обновление файлов с одного или нескольких Git-репозиториев.

  • Автоматическое обновление файлов — синхронизация файлов DAG с содержимым директории DAG Airflow.

  • Гибкая фильтрация — выбор файлов с использованием шаблонов.

  • Параллельная обработка — одновременная работа с несколькими репозиториями с помощью воркеров.

  • Очистка — опциональное удаление устаревших файлов.

  • Управление SSH-ключами — централизованное управление ключами SSH через действия в ADCM.

Использование GitSync

GitSync работает как отдельный сервис и состоит из одного компонента (gitsync).

Процесс синхронизации DAG с помощью сервиса включает следующие шаги:

  1. Исходный код DAG хранится в одном или нескольких Git-репозиториях.

  2. GitSync клонирует или обновляет репозитории.

  3. Файлы фильтруются в соответствии с конфигурацией GitSync.

  4. Файлы DAG копируются в директорию Airflow.

  5. Устаревшие файлы при необходимости удаляются.

  6. GitSync логирует процесс и отправляет метрики.

Airflow автоматически обнаруживает обновленные файлы в директории DAG. Сканирование выполняется рекурсивно для всех подкаталогов (например, /opt/airflow/dags).

Конфигурация

Конфигурация GitSync состоит из двух уровней:

Конфигурация сервиса

Параметры сервисного уровня определяют общее поведение сервиса GitSync. Они задаются в разделе gitsync-env.sh в ADCM.

Ключевые параметры:

  • количество параллельных воркеров;

  • интервал синхронизации и тайм-аут;

  • настройки логирования.

Конфигурация репозиториев

Настройки репозиториев задаются в опции config.json в ADCM и содержат параметры подключения к репозиториям и настройки выбора DAG для синхронизации.

Пример конфигурации репозитория:

{
  "url": "git@ssh.gitlab.example.io:org/repo.git", (1)
  "branch": "main", (2)
  "directory": "./dags",
  "files": "*.py", (3)
  "sync_interval": 60, (4)
  "sync_timeout": 120,
  "ssh_key": "my-git-key", (5)
  "target_folder": "/opt/airflow/dags/project", (6)
  "delete_old_files": true (7)
}
1 URL Git-репозитория.
2 Ветка и директория.
3 Правила фильтрации файлов.
4 Интервал синхронизации и тайм-аут.
5 Название SSH-ключа (для SSH-репозиториев).
6 Целевая директория DAG в Airflow.
7 Параметры удаления устаревших файлов (опционально).

GitSync поддерживает одновременную синхронизацию DAG из нескольких репозиториев. Каждый репозиторий обрабатывается независимо пулом воркеров и должен использовать уникальный target_folder для предотвращения конфликтов.

Пример конфигурации для нескольких репозиториев
[
  {
    "url": "git@ssh.gitlab.example.io:org/marketing-dags.git",
    "sync_interval": 60,
    "target_folder": "/opt/airflow/dags/marketing",
    "branch": "main",
    "tag": null,
    "directory": "./dags",
    "files": "*.py",
    "sync_requirements": false,
    "requirements_path": null,
    "sync_timeout": 120,
    "ssh_key": "ssh_key_marketing",
    "delete_old_files": true
  },
  {
    "url": "git@ssh.gitlab.example.io:org/finance-dags.git",
    "sync_interval": 120,
    "target_folder": "/opt/airflow/dags/finance",
    "branch": "main",
    "tag": null,
    "directory": "./dags",
    "files": "*.py",
    "sync_requirements": false,
    "requirements_path": null,
    "sync_timeout": 300,
    "ssh_key": "ssh_key_finance",
    "delete_old_files": true
  },
  {
    "url": "git@ssh.gitlab.example.io:org/sales-dags.git",
    "sync_interval": 180,
    "target_folder": "/opt/airflow/dags/sales",
    "branch": "main",
    "tag": null,
    "directory": "./dags",
    "files": "*.py",
    "sync_requirements": false,
    "requirements_path": null,
    "sync_timeout": 300,
    "ssh_key": "ssh_key_sales",
    "delete_old_files": true
  },
  {
    "url": "https://github.com/org/shared-dags.git",
    "sync_interval": 300,
    "target_folder": "/opt/airflow/dags/shared",
    "branch": "main",
    "tag": null,
    "directory": "./",
    "files": "*.py",
    "sync_requirements": false,
    "requirements_path": null,
    "sync_timeout": 300,
    "access_token": "******",
    "https_username": "oauth2",
    "delete_old_files": false
  }
]

Аутентификация SSH

Для репозиториев с доступом по SSH GitSync предоставляет встроенное управление ключами:

  1. SSH-ключи загружаются с помощью действия Upload private key.

  2. Ключи хранятся и управляются GitSync в соответствии с конфигурацией сервиса.

  3. В конфигурации репозитория указывается имя ключа.

  4. Ключи добавляются во время выполнения.

Один и тот же SSH-ключ может использоваться для нескольких репозиториев.

Начало работы

Чтобы начать использовать GitSync:

  1. Добавьте и установите сервис GitSync в ADO.

  2. Настройте параметры сервиса.

  3. При необходимости загрузите SSH-ключи с помощью действия Upload private key GitSync.

  4. Определите конфигурации репозиториев.

  5. Убедитесь, что целевые каталоги DAG доступны для Airflow.

После завершения настройки GitSync автоматически поддерживает синхронизацию DAG в соответствии с заданными интервалами.

Ограничения

При настройке GitSync учитывайте следующие ограничения:

  • Python-окружение. Параметр TARGET_PYTHON задается на уровне сервиса и используется всеми репозиториями. Использование отдельных Python-окружений для разных репозиториев не поддерживается.

  • Гибкость конфигурации репозиториев. Следующие сценарии не поддерживаются и могут вызвать неопределенное поведение:

    • синхронизация нескольких директорий из одного репозитория и ветки;

    • синхронизация одного и того же репозитория из нескольких веток.

  • Поддержка dbt-проектов. Не является основным сценарием использования и не полностью протестирована. Артефакты, создаваемые во время работы сервиса (например, target/, logs/), могут быть удалены при некорректной настройке. Для использования dbt требуется следующая конфигурация:

    • files = "*";

    • delete_old_files = false.

  • Поведение синхронизации файлов. Параметр delete_old_files удаляет файлы на основе состояния репозитория и не различает устаревшие файлы и файлы, созданные во время выполнения.

  • Общие ограничения.

    • Требуется сетевой доступ к Git-репозиториям.

    • Для SSH требуется корректная настройка ключей.

    • Дублирование dag_id в разных репозиториях приводит к конфликтам.

Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней