Storing LFS objects in remote object storage

It is possible to store LFS objects in remote object storage which allows you
to offload local hard disk R/W operations, and free up disk space significantly.
GitLab is tightly integrated with Fog, so you can refer to its documentation
to check which storage services can be integrated with GitLab.
You can also use external object storage in a private local network. For example,
Minio is a standalone object storage service, is easy to set up, and works well with GitLab instances.

GitLab provides two different options for the uploading mechanism: "Direct upload" and "Background upload".

Option 1. Direct upload

User pushes an lfs file to the GitLab instance

GitLab-workhorse uploads the file directly to the external object storage

GitLab-workhorse notifies GitLab-rails that the upload process is complete

Option 2. Background upload

User pushes an lfs file to the GitLab instance

GitLab-rails stores the file in the local file storage

GitLab-rails then uploads the file to the external object storage asynchronously

The following general settings are supported.

Setting

Description

Default

enabled

Enable/disable object storage

false

remote_directory

The bucket name where LFS objects will be stored

direct_upload

Set to true to enable direct upload of LFS without the need of local shared storage. Option may be removed once we decide to support only single storage for all files.

false

background_upload

Set to false to disable automatic upload. Option may be removed once upload is direct to S3

true

proxy_download

Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data

This will migrate existing LFS objects to object storage. New LFS objects
will be forwarded to object storage unless
gitlab_rails['lfs_object_store_background_upload'] is set to false.

S3 for installations from source

For source installations the settings are nested under lfs: and then
object_store::

Edit /home/git/gitlab/config/gitlab.yml and add or amend the following
lines:

lfs:enabled:trueobject_store:enabled:falseremote_directory:lfs-objects# Bucket nameconnection:provider:AWSaws_access_key_id:1ABCD2EFGHI34JKLM567Naws_secret_access_key:abcdefhijklmnopQRSTUVwxyz0123456789ABCDEregion:eu-central-1# Use the following options to configure an AWS compatible host such as Miniohost:'localhost'endpoint:'http://127.0.0.1:9000'path_style:true

This will migrate existing LFS objects to object storage. New LFS objects
will be forwarded to object storage unless background_upload is set to
false.

Storage statistics

You can see the total storage used for LFS objects on groups and projects
in the administration area, as well as through the groups
and projects APIs.

Troubleshooting: Google::Apis::TransmissionError: execution expired

If LFS integration is configred with Google Cloud Storage and background uploads (background_upload: true and direct_upload: false),
sidekiq workers may encouter this error. This is because the uploading timed out with very large files.
LFS files up to 6Gb can be uploaded without any extra steps, otherwise you need to use the following workaround.

$ sudo gitlab-rails console # Login to rails console># Set up timeouts. 20 minutes is enough to upload 30GB LFS files.># These settings are only in effect for the same session, i.e. they are not effective for sidekiq workers.> ::Google::Apis::ClientOptions.default.open_timeout_sec = 1200> ::Google::Apis::ClientOptions.default.read_timeout_sec = 1200> ::Google::Apis::ClientOptions.default.send_timeout_sec = 1200># Upload LFS files manually. This process does not use sidekiq at all.> LfsObject.where(file_store: [nil, 1]).find_each do |lfs_object|> lfs_object.file.migrate!(ObjectStorage::Store::REMOTE)if lfs_object.file.file.exists?> end