Обзор GitSync

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

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

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

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

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

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

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

  • Установка зависимостей на уровне репозитория — опциональная установка Python-зависимостей с использованием Python-окружения, заданного для конкретного репозитория.

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

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

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

  • Мониторинг — экспорт метрик Prometheus и готовый дашборд Grafana для мониторинга состояния и производительности синхронизации.

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

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

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

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

  2. GitSync клонирует или обновляет каждую настроенную конфигурацию репозитория независимо.

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

  4. Если задано конфигурацией, Python-зависимости устанавливаются с использованием Python-окружения, заданного для данного репозитория.

  5. Выбранные файлы копируются в целевую директорию.

  6. При необходимости удаляются устаревшие синхронизированные файлы.

  7. GitSync записывает журналы и экспортирует метрики.

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

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

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

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

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

Основные параметры:

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

  • расписание синхронизации;

  • тайм-аут синхронизации по умолчанию;

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

  • Python-окружение по умолчанию (TARGET_PYTHON), используемое для обратной совместимости, если для репозитория не указан собственный интерпретатор Python.

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

Настройки репозиториев задаются в опции config.json в ADCM.

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

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

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

Каждая конфигурация репозитория обрабатывается независимо.

GitSync поддерживает следующие сценарии синхронизации:

  • синхронизацию нескольких независимых репозиториев;

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

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

  • синхронизацию одной и той же директории из разных веток.

Во избежание конфликтов каждая задача синхронизации должна использовать уникальный target_folder.

Пример конфигурации
[
  {
    "url": "git@ssh.gitlab.example.io:org/project.git",
    "branch": "main",
    "directory": "./dags",
    "target_folder": "/opt/airflow/dags/main",
    "target_python": "/usr/lib/airflow/venv/bin/python",
    "files": "*.py"
  },
  {
    "url": "git@ssh.gitlab.example.io:org/project.git",
    "branch": "dev",
    "directory": "./dags",
    "target_folder": "/opt/airflow/dags/dev",
    "target_python": "/usr/lib/airflow/venv/bin/python",
    "files": "*.py"
  },
  {
    "url": "git@ssh.gitlab.example.io:org/project.git",
    "branch": "main",
    "directory": "./dbt",
    "target_folder": "/opt/dbt/project",
    "target_python": "/usr/lib/dbt/venv/bin/python",
    "files": "*"
  },
  {
    "url": "https://github.com/org/shared-dags.git",
    "branch": "main",
    "directory": "./",
    "target_folder": "/opt/airflow/dags/shared",
    "files": "*.py",
    "access_token": "******",
    "https_username": "oauth2"
  }
]

Синхронизация репозиториев

Каждая конфигурация репозитория рассматривается как независимая задача синхронизации.

GitSync хранит состояние синхронизации отдельно для каждой уникальной комбинации следующих параметров:

  • URL репозитория;

  • ветка;

  • директория.

Это позволяет выполнять независимую синхронизацию даже в том случае, если несколько задач используют один и тот же Git-репозиторий.

Например, одновременно поддерживаются следующие сценарии:

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

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

  • комбинация этих подходов.

Аутентификация 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. Убедитесь, что целевые директории доступны соответствующим приложениям.

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

Ограничения

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

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

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

    • files = "*";

    • delete_old_files = false.

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

  • Для SSH-репозиториев требуется корректная настройка ключей.

  • Каждая задача синхронизации должна использовать уникальный target_folder.

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

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