Управление большими файлами с помощью 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

Сохраните файл конфигурации как secret в кластере, при этом 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-lfs клиент, проверьте версию командой git-lfs version

#Настройка параметров 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 hook для LFS с помощью git lfs install:

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