Управление большими файлами с помощью 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, используют хранилище узла. Из-за сложности расширения хранилища узла этот метод не рекомендуется для производственных сред.
• Инстансы 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 — 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