Управление большими файлами с помощью LFS#

В этой статье будет рассказано, как использовать LFS для управления большими файлами, включая настройку инстанса GitLab и конфигурацию Git клиента.

Применимые сценарии:

• Использование LFS для управления исполняемыми файлами в репозиториях кода, такими как скомпилированные JAR-пакеты
• Использование LFS для управления большими моделями AI в репозиториях кода

#Конфигурация инстанса GitLab

#Предварительные требования

• Инстанс GitLab развернут согласно документации GitLab Instance Deployment.

GitLab поддерживает два способа настройки LFS, основное отличие которых — место хранения файлов LFS.

1. Использование локального хранилища для сохранения файлов LFS
2. Использование объектного хранилища для сохранения файлов LFS

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

#Использование локального хранилища для файлов LFS

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

Файлы LFS, сохранённые локально, хранятся в attachment storage по пути: shareds/lfs-objects.

Тип attachment storage зависит от способа развертывания:

• Инстансы GitLab, развернутые с использованием метода HostPath, используют хранилище узла. Из-за сложности расширения хранилища узла этот метод не рекомендуется для production-сред.
• Инстансы GitLab, развернутые с использованием storage classes или указанных PVC, используют PVC в качестве носителя хранения.

#Использование объектного хранилища для файлов LFS (рекомендуется)

GitLab официально рекомендует использовать объектное хранилище для сохранения файлов LFS.

GitLab поддерживает несколько типов объектного хранилища. В следующем примере используется MinIO для иллюстрации настройки GitLab на использование объектного хранилища.

Создайте следующие бакеты в MinIO:

1. git-lfs
2. gitlab-uploads

Способ создания бакетов с помощью команды mc cli следующий:

# Установите адрес доступа MinIO, access key и secret key
export MINIO_HOST=minio.example.com
export MINIO_ACCESS_KEY=your-access-key
export MINIO_SECRET_KEY=your-secret-key
mc alias set minio http://${MINIO_HOST} ${MINIO_ACCESS_KEY} ${MINIO_SECRET_KEY}

# Создайте бакеты git-lfs и gitlab-uploads
mc mb minio/git-lfs
mc mb minio/gitlab-uploads

Подготовьте конфигурационный файл MinIO с именем rails-storage.yaml со следующим содержимым:

provider: AWS
region: us-east-1
aws_access_key_id: example
aws_secret_access_key: example
endpoint: "http://minio.example.com"
path_style: true

Где:

• provider — тип объектного хранилища, MinIO использует фиксированное значение AWS
• region — регион объектного хранилища, MinIO использует фиксированное значение us-east-1
• aws_access_key_id — идентификатор ключа доступа к объектному хранилищу
• aws_secret_access_key — ключ доступа к объектному хранилищу
• endpoint — адрес доступа к объектному хранилищу
• path_style — способ доступа к объектному хранилищу, здесь используется фиксированное значение true

Сохраните конфигурационный файл как секрет в кластере, при этом namespace должен совпадать с namespace инстанса GitLab:

export GITLAB_NS=<your-gitlab-namespace>
kubectl create secret generic gitlab-rails-storage \
    -n ${GITLAB_NS} \
    --from-file=connection=rails-storage.yaml

Измените конфигурацию инстанса GitLab, добавив следующее для включения объектного хранилища:

spec:
  helmValues:
    global:
      appConfig:
        object_store:
          connection:
            key: connection # ключ в секрете
            secret: gitlab-rails-storage # имя созданного секрета
          enabled: true

#Конфигурация ресурсов и параметров

В отличие от обычных API-запросов, при загрузке и скачивании файлов LFS компонент workhorse потребляет больше ресурсов CPU. Ресурсы компонента workhorse напрямую влияют на производительность push и pull.

Измените конфигурацию инстанса GitLab, добавив следующее для настройки ресурсов компонента workhorse:

spec:
  helmValues:
    gitlab:
      webservice:
        workhorse:
          resources:
            limits:
              cpu: 2
              memory: 500Mi
            requests:
              cpu: 200m
              memory: 200Mi

Кроме того, необходимо увеличить таймаут для компонента webservice. Метод настройки следующий:

spec:
  helmValues:
    gitlab:
      webservice:
        extraEnv:
          GITLAB_RAILS_RACK_TIMEOUT: "300"
    global:
      webservice:
        workerTimeout: 300

#Конфигурация Git клиента

#Предварительные требования

• Установлен Git клиент, выполните команду git version для проверки версии Git
• Установлен git-lfs клиент, выполните команду git-lfs version для проверки версии git-lfs

#Настройка параметров Git клиента

Выполните следующую команду для сохранения учетных данных клонирования, чтобы не вводить пароль при каждом pull и push:

git config --global credential.helper store

Выполните следующую команду для установки количества одновременных передач файлов LFS, что эффективно повышает стабильность push и pull, особенно при одновременной загрузке большого количества файлов:

git config --global lfs.concurrenttransfers 2

Выполните следующую команду для установки таймаута активности LFS. Этот параметр обязательно нужно добавить, если GitLab использует объектное хранилище:

git config --global lfs.activitytimeout 36000

#Конфигурация Git проекта

Выполните следующие команды для клонирования Git репозитория на локальную машину и запуска git lfs install для установки git hook LFS:

git clone http://example.com/root/local-lfs.git
cd local-lfs
git lfs install

Выполните следующую команду для установки шаблона отслеживания файлов LFS, например, для отслеживания всех файлов .safetensors:

git lfs track "*.safetensors"

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

git add .gitattributes
git commit -m "Add LFS tracking for .safetensors files"
git push

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

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

#Распространённые проблемы

#Ошибка клонирования очень больших репозиториев

При клонировании очень больших репозиториев, если у клиента недостаточно ресурсов, клиент может быть завершён системой после некоторого времени работы. Решение:

1. Добавить параметр GIT_LFS_SKIP_SMUDGE=1 при клонировании, чтобы пропустить выгрузку файлов LFS
2. Перейти в локальный каталог кода и выполнить команду git lfs pull для загрузки файлов LFS на локальную машину

GIT_LFS_SKIP_SMUDGE=1 git clone http://example.com/root/local-lfs.git
cd local-lfs
git lfs pull