Управление большими файлами с помощью 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 — идентификатор ключа доступа к объектному хранилищу
• 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-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 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