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

Хранилище вложений зависит от метода развертывания:

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